Aller au contenu principal
Version : 2.4.0

i18n - Introduction

It is easy to translate a Docusaurus website with its internationalization (i18n) support.

Goals​

It is important to understand the design decisions behind the Docusaurus i18n support.

For more context, you can read the initial RFC and PR.

i18n goals​

Les objectifs du système Docusaurus i18n sont :

  • Simple: just put the translated files in the correct filesystem location
  • Flexible translation workflows: use Git (monorepo, forks, or submodules), SaaS software, FTP
  • Flexible deployment options: single, multiple domains, or hybrid
  • Modular: allow plugin authors to provide i18n support
  • Low-overhead runtime: documentation is mostly static and does not require heavy JS libraries or polyfills
  • Scalable build-times: allow building and deploying localized sites independently
  • Localize assets: an image of your site might contain text that should be translated
  • No coupling: not forced to use any SaaS, yet integrations are possible
  • Easy to use with Crowdin: a lot of Docusaurus v1 sites use Crowdin and should be able to migrate to v2
  • Good SEO defaults: we set useful SEO headers like hreflang for you
  • RTL support: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
  • Default translations: classic theme labels are translated for you in many languages

i18n non-goals​

Nous ne prenons pas en charge :

  • Automatic locale detection: opinionated, and best done on the server (your hosting provider)
  • Translation SaaS software: you are responsible to understand the external tools of your choice
  • Translation of slugs: technically complicated, little SEO value

Translation workflow​

Overview​

Vue d'ensemble du flux de travail pour créer un site web Docusaurus traduit :

  1. Configure: declare the default locale and alternative locales in docusaurus.config.js
  2. Translate: put the translation files at the correct filesystem location
  3. Deploy: build and deploy your site using a single or multi-domain strategy

Translation files​

Vous travaillerez avec 3 types de fichiers de traduction.

Markdown files​

Ceci est le contenu principal de votre site web Docusaurus.

Les documents Markdown et MDX sont traduits dans leur ensemble, afin de préserver pleinement le contexte de la traduction, au lieu de fractionner chaque phrase en une chaîne distincte.

JSON files​

Le JSON est utilisé pour traduire :

  • Your React code: standalone React pages in src/pages, or other components
  • Layout labels provided through themeConfig: navbar, footer
  • Libellés de mise en page fournis par les options du plugin : libellés des catégories de la barre latérale des documents, titre de la barre latérale du blog...

The JSON format used is called Chrome i18n:

{
  "myTranslationKey1": {
    "message": "Message traduit 1",
    "description": "myTranslationKey1 est utilisé sur la page d'accueil"
  },
  "myTranslationKey2": {
    "message": "Message traduit 2",
    "description": "myTranslationKey2 est utilisé dans la FAQ"
  }
}

Le choix a été fait pour 2 raisons :

Data files​

Certains plugins peuvent lire des fichiers de données externes qui sont intégralement traduits. For example, the blog plugin uses an authors.yml file that can be translated by creating a copy under i18n/[locale]/docusaurus-plugin-content-blog/authors.yml.

Translation files location​

Les fichiers de traduction doivent être créés au bon emplacement du système de fichiers.

Each locale and plugin has its own i18n subfolder:

website/i18n/[locale]/[pluginName]/...
remarque

For multi-instance plugins, the path is website/i18n/[locale]/[pluginName]-[pluginId]/....

La traduction très simple d'un site de Docusaurus en français conduit à la structure suivante :

website/i18n
└── fr
    ├── code.json  # Tout libellé de texte présent dans le code React
    │              # Inclut les libellés de texte du code des thèmes
    ├── docusaurus-plugin-content-blog # les données de traduction dont a besoin le plugin du blog
    │   └── 2020-01-01-hello.md
    │
    ├── docusaurus-plugin-content-docs # les données de traduction dont a besoin le plugin de doc
    │   ├── current
    │   │   ├── doc1.md
    │   │   └── doc2.mdx
    │   └── current.json
    │
    └── docusaurus-theme-classic # les données de traduction dont a besoin le thème classique
        ├── footer.json   # Libellés de texte dans la configuration du thème de votre pied de page
        └── navbar.json   # Libellés de texte dans la configuration du thème de votre barre de navigation

The JSON files are initialized with the docusaurus write-translations CLI command. Each plugin sources its own translated content under the corresponding folder, while the code.json file defines all text labels used in the React code.

Each content plugin or theme is different, and defines its own translation files location: