Aller au contenu principal
Version: 2.4.3

i18n - Introduction

Il est facile de traduire un site web Docusaurus grâce à sa prise en charge de l'internationalisation (i18n).

Objectifs​

Il est important de comprendre les décisions de conception derrière la prise en charge de l'i18n de Docusaurus.

Pour plus de contexte, vous pouvez lire la RFC et la PR de départ.

Les objectifs de l'i18n​

Les objectifs du système Docusaurus i18n sont :

  • Simple : il suffit de placer les fichiers traduits dans le bon emplacement du système de fichiers
  • Flux de traduction flexibles : basés sur Git (monorepo, forks ou submodules), logiciel SaaS, FTP
  • Options de déploiement flexibles : domaines uniques, multiples ou hybrides
  • Modulaire : permet aux auteurs de plugins de fournir une prise en charge i18n
  • Runtime léger : la documentation est principalement statique et ne nécessite pas de librairie JS ou de polyfills lourds
  • Délais de construction modulables : permet la construction et le déploiement indépendant de sites localisés
  • Localiser les ressources : une image de votre site peut contenir du texte qui doit être traduit
  • Pas de couplage : aucune obligation d'utiliser un SaaS, mais les intégrations sont possibles
  • Facile à utiliser avec Crowdin : plusieurs sites Docusaurus v1 utilisent Crowdin, et devraient être en mesure de migrer vers v2
  • Bon SEO par défauts : nous définissons pour vous des entêtes SEO utiles comme hreflang
  • Prise en charge RTL : les locales avec lecture de droite à gauche (Arabe, Hébreu, etc.) sont pris en charge et faciles à implémenter
  • Traductions par défaut : les libellés du thème classic sont traduites pour vous dans de nombreuses langues

Les aspects non liés à l'i18n​

Nous ne prenons pas en charge :

  • Détection automatique des locales : opinion controversée, à réaliser de préférence sur le serveur (de votre hébergeur)
  • Logiciels SaaS de traduction : vous êtes responsable de la compréhension des outils externes de votre choix
  • Traduction des slugs : techniquement compliqué, peu de valeur pour le SEO

Processus de traduction​

Vue d'ensemble​

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

  1. Configurez : déclarez la locale par défaut et les locales alternatives dans docusaurus.config.js
  2. Traduisez : mettez les fichiers traduits dans le bon emplacement du système de fichiers
  3. Déployez : construisez et déployez votre site en utilisant une stratégie basée sur un ou plusieurs domaines

Fichiers de traduction​

Vous travaillerez avec 3 types de fichiers de traduction.

Fichiers Markdown​

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.

Fichiers JSON​

Le JSON est utilisé pour traduire :

  • Votre code React : les pages React autonomes dans src/pages, ou d'autres composants
  • Libellés de mise en page fournis par themeConfig : barre de navigation, pied de page
  • 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...

Le format JSON utilisé est appelé 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 :

Fichiers de données​

Certains plugins peuvent lire des fichiers de données externes qui sont intégralement traduits. Par exemple, le plugin du blog utilise un fichier authors.yml qui peut être traduit en créant une copie sous 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.

Chaque locale et chaque plugin a son propre sous-dossier i18n :

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

Pour les plugins multi-instances, le chemin est 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

Les fichiers JSON sont initialisés avec la commande CLI docusaurus write-translations. 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.

Chaque plugin de contenu ou de thème est différent, et il définit son propre emplacement des fichiers de traduction :