Aller au contenu principal
Version: Canary 🚧

i18n - Introduction

Il est facile de traduire un site web Docusaurus grâce à son support de l'internationalisation (i18n).

Objectifs​

Il est important de comprendre les décisions de conception derrière le support de Docusaurus i18n.

Pour plus de contexte, vous pouvez lire les textes initiaux RFC et PR.

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
  • Flexible : utilisez Git (monorepo, forks, ou sous-modules), un SaaS ou un FTP
  • Déploiement : domaine unique, plusieurs domaines ou hybride
  • Modulaire : permet aux auteurs de plugins de fournir un support i18n
  • Runtime léger: la documentation est principalement statique et ne nécessite pas de librairies JS ou de polyfills lourds
  • Temps de build scalables : 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 la v2
  • Bon SEO par défaut : nous définissons des en-têtes SEO utiles comme hreflang pour vous
  • Prise en charge RTL : les locales avec lecture de droite à gauche (arabe, hébreu, etc.) sont prises 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 (« Optimisation pour les moteurs de recherche »)

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.

Emplacement des fichiers de traduction​

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. Chaque plugin fournit son propre contenu traduit dans le dossier correspondant, tandis que le fichier code.json définit tous les libellés utilisés dans le code React.

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