Aller au contenu principal
Version: 2.0.0-alpha.75

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 librairie 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 textes du thème classiques 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
  • 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 devrez travailler avec 2 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 : en utilisant le composant <Translate>
  • votre thème : la barre de navigation, le pied de page
  • vos plugins: les étiquettes decatégorie de la barre latérale des docs

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 :

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    ├── docusaurus-plugin-content-blog    │   └── 2020-01-01-hello.md    ├── docusaurus-plugin-content-docs    │   ├── current #    │   │   ├── doc1.md    │   │   └── doc2.mdx    │   └── current.json    └── docusaurus-theme-classic        ├── footer.json        └── navbar.json

Les fichiers JSON sont initialisés avec la commande CLI docusaurus write-translations.

Le fichier code.json est extrait des composants React en utilisant l'API <Translate>.

info

Notez que le plugin docusaurus-plugin-content-docs a un sous-dossier current et un fichier current.json, utile pour la fonctionnalité de version des docs.

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