Aller au contenu principal
Version : 3.7.0

i18n - Utilisation de git

Une stratégie de traduction possible consiste à maßtriser la version des fichiers de traduction avec Git (ou tout autre VCS).

Compromis​

Cette stratégie a des avantages :

  • Facile Ă  dĂ©marrer : commitez simplement le dossier i18n Ă  Git
  • Facile pour les dĂ©veloppeurs : Git, GitHub et les pull requests sont des outils de dĂ©veloppement standard
  • Gratuit (ou sans coĂ»t supplĂ©mentaire, en supposant que vous utilisiez dĂ©jĂ  Git)
  • Faible interaction : ne nĂ©cessite pas de s'inscrire Ă  un outil externe
  • Gratifiant : les contributeurs sont heureux d'avoir un bon historique de leurs contributions

L'utilisation de Git présente également quelques lacunes :

  • Difficile pour les non-dĂ©veloppeurs : ils ne maĂźtrisent pas Git et les pull-requests
  • Difficile pour les traducteurs professionnels : ils sont habituĂ©s aux logiciels de traduction SaaS et aux fonctionnalitĂ©s avancĂ©es
  • Difficile Ă  maintenir : vous devez garder les fichiers traduits en les synchronisant avec les fichiers non traduits
remarque

Certains projets techniques Ă  grande Ă©chelle (React, Vue.js, MDN, TypeScript, Nuxt.js, etc.) utilisent Git pour les traductions.

Reportez-vous au RFC Docusaurus i18n pour nos notes et liens concernant l'Ă©tude de ces systĂšmes.

Initialisation​

Il s'agit d'une présentation de l'utilisation de Git pour traduire en français un site web Docusaurus anglais nouvellement initialisé, et suppose que vous avez déjà suivi le tutoriel i18n.

PrĂ©parez le site Docusaurus​

Initialisez un nouveau site Docusaurus :

npx create-docusaurus@latest website classic

Ajoutez la configuration du site pour la langue française :

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: 'localeDropdown',
          position: 'left',
        },
        // ...
      ],
    },
  },
  // ...
};

Traduisez la page d'accueil :

src/pages/index.js
import React from 'react';
import Translate from '@docusaurus/Translate';
import Layout from '@theme/Layout';

export default function Home() {
  return (
    <Layout>
      <h1 style={{margin: 20}}>
        <Translate description="The homepage main heading">
          Welcome to my Docusaurus translated site!
        </Translate>
      </h1>
    </Layout>
  );
}

Initialisez le dossier i18n​

Utilisez la commande CLI write-translations pour initialiser les fichiers de traduction JSON pour la langue française :

npm run write-translations -- --locale fr

  1 translations written at i18n/fr/code.json
 11 translations written at i18n/fr/docusaurus-theme-classic/footer.json
  4 translations written at i18n/fr/docusaurus-theme-classic/navbar.json
  3 translations written at i18n/fr/docusaurus-plugin-content-docs/current.json
astuce

Utilisez l'option --messagePrefix '(fr) ' pour faire ressortir les chaĂźnes non traduites.

Hello apparaĂźtra comme (fr) Hello et indique qu'une traduction est manquante.

Copiez vos fichiers Markdown non traduits dans le dossier français :

mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current

mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog

mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages

Ajoutez tous ces fichiers Ă  Git.

Traduisez les fichiers​

Traduisez les fichiers Markdown et JSON dans i18n/fr et committez la traduction.

Vous devriez maintenant ĂȘtre en mesure de dĂ©marrer votre site en français et de voir les traductions :

npm run start -- --locale fr

Vous pouvez Ă©galement construire le site localement ou sur votre CI :

npm run build
# ou
npm run build -- --locale fr

RĂ©pĂ©tez​

Suivez le mĂȘme processus pour chaque locale que vous devez prendre en charge.

Maintenance​

Garder les fichiers traduits cohĂ©rents avec les originaux peut ĂȘtre difficile, en particulier pour les documents Markdown.

Traductions Markdown​

Lorsqu'un document Markdown non traduit est modifié, il est de votre responsabilité de maintenir les fichiers traduits respectivement, et nous n'avons malheureusement pas un bon moyen de vous aider à le faire.

Pour maintenir la cohérence de vos sites traduits, lorsque le doc website/docs/doc1.md est modifié, vous avez besoin de reporter ces modifications vers i18n/fr/docusaurus-plugin-content-docs/current/doc1.md.

Traductions JSON​

Pour vous aider Ă  maintenir les fichiers de traduction JSON, il est possible d'exĂ©cuter Ă  nouveau la commande CLI write-translations :

npm run write-translations -- --locale fr

Les nouvelles traductions seront ajoutées et les traductions existantes ne seront pas remplacées.

astuce

RĂ©initialisez vos traductions avec l'option --override.

Traduisez les URL de modification​

Quand l'utilisateur navigue sur une page à /fr/doc1, le bouton de modification liera par défaut le doc non localisé website/docs/doc1.md.

Vos traductions sont sur Git, et vous pouvez utiliser l'option editLocalizedFiles : true des plugins docs et blog.

Le bouton de modification sera lié au doc localisé i18n/fr/docusaurus-plugin-content-docs/current/doc1.md.