Version : Canary 🚧

i18n - Tutoriel

Ce tutoriel vous guidera à travers les principes de base du système i18n de Docusaurus.

Nous allons ajouter les traductions françaises à un site web nouvellement initialisé de Docusaurus en anglais.

Initialisez un nouveau site avec npx [email protected] website classic (comme celui-ci).

Configurez votre site

Modifiez docusaurus.config.js pour ajouter le support i18n pour la langue française.

Configuration du site

Utilisez la configuration i18n du site pour déclarer les locales i18n :

docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'fa'],
    localeConfigs: {
      en: {
        htmlLang: 'en-GB',
      },
      // Vous pouvez omettre une locale (par exemple, fr) si vous n'avez pas besoin de modifier les paramètres par défaut.
      fa: {
        direction: 'rtl',
      },
    },
  },
};

Les noms de locales sont utilisés pour les emplacements des fichiers de traduction, ainsi que pour l'URL de base de vos locales traduites. Lors de la compilation de toutes les locales, seule la locale par défaut aura son nom omis dans l'URL de base.

Docusaurus utilise les noms des locales pour fournir des valeurs par défaut judicieuses : l'attribut <html lang="...">, le libellé de la locale, le format du calendrier, etc. Vous pouvez personnaliser ces valeurs par défaut avec le localeConfigs.

Configuration du thème

Ajouter un élément à la barre de navigation de type localeDropdown afin que les utilisateurs puissent sélectionner la locale qu'ils souhaitent :

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
        },
      ],
    },
  },
};

Démarrez votre site

Démarrez votre site localisé en mode développement, en utilisant la locale de votre choix :

npm
Yarn
pnpm

npm run start -- --locale fr

yarn run start --locale fr

pnpm run start -- --locale fr

Votre site est accessible à l'adresse http://localhost:3000/fr/.

Nous n'avons pas encore fourni de traduction, donc le site est principalement non traduit.

astuce

Docusaurus fournit des traductions par défaut pour les libellés de thème génériques, telles que « Suivant » et « Précédent » pour la pagination.

Veuillez nous aider à compléter ces traductions par défaut.

attention

Chaque locale est une application autonome distincte mono-page : il n'est donc pas possible de démarrer les sites Docusaurus avec toutes les locales en même temps.

Traduisez votre site

Toutes les données de traduction pour la locale française sont stockées dans website/i18n/fr. 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.

remarque

Après avoir copié des fichiers, redémarrez votre site avec npm run start -- --locale fr. Le rechargement à chaud fonctionnera mieux lors de l'édition des fichiers existants.

Traduire votre code React

Pour tout code React que vous avez écrit vous-même : pages React, composants React, etc, vous utiliserez les API de traduction.

Repérez tous les libellés de texte dans votre code React qui seront visibles par vos utilisateurs, et marquez-les avec les API de traduction. Il y a deux types d'API :

Le composant <Translate> enveloppe une chaîne de caractères en tant qu'élément JSX;
La fonction de rappel translate() prend un message et retourne une chaîne de caractères.

Utilisez celui qui correspond le mieux au contexte sémantiquement. Par exemple, le <Translate> peut être utilisé comme fils de React, tandis que pour les props qui attendent une chaîne, la callback peut être utilisée.

attention

Un élément JSX est un objet, pas une chaîne. L'utiliser dans des contextes attendant des chaînes de caractères (comme les enfants de <option>) le contraindra à une chaîne, qui renvoie "[object Object]". Bien que nous vous encouragions à utiliser <Translate> comme enfants JSX, n'utilisez le formulaire de l'élément que lorsqu'il fonctionne réellement.

Before
After

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

export default function Home() {
  return (
    <Layout>
      <h1>Bienvenue sur mon site web</h1>
      <main>
        Vous pouvez aussi visiter mon
        <Link to="https://docusaurus.io/blog">blog</Link>
        <img
          src="/img/home.png"
          alt="Home icon"
        />
      </main>
    </Layout>
  );
}

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

import Translate, {translate} from '@docusaurus/Translate';

export default function Home() {
  return (
    <Layout>
      <h1>
        <Translate>Welcome to my website</Translate>
      </h1>
      <main>
        <Translate
          id="homepage.visitMyBlog"
          description="The homepage message to ask the user to visit my blog"
          values={{
            blogLink: (
              <Link to="https://docusaurus.io/blog">
                <Translate
                  id="homepage.visitMyBlog.linkLabel"
                  description="The label for the link to my blog">
                  blog
                </Translate>
              </Link>
            ),
          }}>
          {'You can also visit my {blogLink}'}
        </Translate>

        <img
          src="/img/home.png"
          alt={
            translate({
              message: 'Home icon',
              description: 'The homepage icon alt message',
            })
          }
        />
      </main>
    </Layout>
  );
}

info

Docusaurus fournit un runtime de traduction très petit et léger et ne prend en charge que l'interpolation de placeholders, en utilisant un sous-ensemble du Format de message ICU.

La plupart des sites web de documentation sont généralement statiques et n'ont pas besoin de fonctionnalités i18n avancées (nombre, genre, etc.). Utilisez une bibliothèque comme react-intl pour des cas d'utilisation plus avancés.

La commande docusaurus write-translations analysera statiquement tous les fichiers de code React utilisés dans votre site, extraira les appels à ces APIs, et les agrégera dans le fichier code.json. Les fichiers de traduction seront stockés sous forme de mappage des ID vers les objets de message de traduction (y compris le libellé traduit et la description du libellé). Dans vos appels aux API de traduction (<Translate> ou translate()), vous devez spécifier soit le message non traduit par défaut, soit l'ID, afin que Docusaurus puisse correctement corréler chaque entrée de traduction à l'appel de l'API.

les libellés de texte doivent être statiques

La commande docusaurus write-translations ne fait qu'une analyse statique de votre code. Elle ne fait pas fonctionner votre site. Par conséquent, les messages dynamiques ne peuvent pas être extraits, car le message est une expression, pas une chaîne :

const items = [
  {id: 1, title: 'Hello'},
  {id: 2, title: 'World'},
];

function ItemsList() {
  return (
    <ul>
      {/* NE LE FAITES PAS : ne fonctionne pas avec la commande write-translations */}
      {items.map((item) => (
        <li key={item.id}>
          <Translate>{item.title}</Translate>
        </li>
      ))}
    <ul>
  );
}

Cela se comporte toujours correctement au moment de l'exécution. Cependant, à l'avenir, nous pourrions fournir un mécanisme « sans exécution », permettant aux traductions d'être directement incluses dans le code React à travers les transformations de Babel, au lieu d'appeler les APIs à l'exécution. Par conséquent, pour être à l'épreuve du temps, vous devriez toujours préférer les messages analysables statiquement. Par exemple, nous pouvons refactoriser le code ci-dessus en :

const items = [
  {id: 1, title: <Translate>Hello</Translate>},
  {id: 2, title: <Translate>World</Translate>},
];

function ItemsList() {
  return (
    <ul>
      {/* Les titres sont maintenant déjà traduits lors du rendu ! */}
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    <ul>
  );
}

Vous pouvez voir les appels aux API de traduction comme de purs marqueurs qui indiquent à Docusaurus que « voici un libellé à remplacer par un message traduit ».

Pluralisation

Lorsque vous exécutez write-translations, vous remarquerez que certains libellés sont pluralisés :

i18n/en/code.json
{
  // ...
  "theme.blog.post.plurals": "One post|{count} posts"
  // ...
}

Chaque langue aura une liste de catégories de pluriel possibles. Docusaurus les classera dans l'ordre suivant ["zero", "one", "two", "few", "many", "other"]. Par exemple, comme l'anglais (en) possède deux formes de pluriel ("one" et "other"), le message de traduction comporte deux libellés séparés par un pipe (|). Pour le polonais (pl), qui possède trois formes de pluriel ("one", "few" et "many"), il faut fournir trois libellés dans cet ordre, réunis par des pipes.

Vous pouvez aussi mettre les messages de votre propre code au pluriel :

import {translate} from '@docusaurus/Translate';
import {usePluralForm} from '@docusaurus/theme-common';

function ItemsList({items}) {
  // `usePluralForm` fournira le sélecteur pluriel pour la locale actuelle
  const {selectMessage} = usePluralForm();
  // Sélectionne le libellé pluralisé approprié en fonction de `items.length`
  const message = selectMessage(
    items.length,
    translate(
      {message: 'One item|{count} items'},
      {count: items.length},
    ),
  );
  return (
    <>
      <h2>{message}</h2>
      <ul>{items.map((item) => <li key={item.id}>{item.title}</li>)}<ul>
    </>
  );
}

remarque

Docusaurus utilise Intl.PluralRules pour résoudre et sélectionner les formes plurielles. Il est important de fournir le bon nombre de formes plurielles dans le bon ordre pour que selectMessage fonctionne.

Traduire les données du plugin

Les fichiers de traduction JSON sont utilisés pour tout ce qui est disséminé dans votre code :

Le code React, y compris les libellés traduits que vous avez marqués ci-dessus
Les libellés de la barre de navigation et du pied de page dans la configuration du thème
Les libellés des catégories de la barre latérale dans sidebars.js
Titre de la barre latérale du blog dans les options du plugin
...

Exécutez la commande write-translations :

npm
Yarn
pnpm

npm run write-translations -- --locale fr

yarn write-translations --locale fr

pnpm run write-translations -- --locale fr

Cela extraira et initialisera les fichiers de traduction JSON que vous devez traduire. Le fichier code.json à la racine comprend tous les appels d'API de traduction extraits du code source, qui pourrait être soit écrit par vous, soit fourni par les thèmes, dont certains peuvent déjà être traduits par défaut.

i18n/fr/code.json
{
  // Aucun ID pour le composant <Translate> : le message par défaut est utilisé comme ID
  "Welcome to my website": {
    "message": "Welcome to my website"
  },
  "home.visitMyBlog": {
    "message": "You can also visit my {blog}",
    "description": "The homepage message to ask the user to visit my blog"
  },
  "homepage.visitMyBlog.linkLabel": {
    "message": "Blog",
    "description": "The label for the link to my blog"
  },
  "Home icon": {
    "message": "Home icon",
    "description": "The homepage icon alt message"
  }
}

Les plugins et les thèmes écriront également leurs propres fichiers de traduction JSON, tels que:

i18n/fr/docusaurus-theme-classic/navbar.json
{
  "title": {
    "message": "My Site",
    "description": "The title in the navbar"
  },
  "item.label.Docs": {
    "message": "Docs",
    "description": "Navbar item with label Docs"
  },
  "item.label.Blog": {
    "message": "Blog",
    "description": "Navbar item with label Blog"
  },
  "item.label.GitHub": {
    "message": "GitHub",
    "description": "Navbar item with label GitHub"
  }
}

Traduisez l'attribut message dans les fichiers JSON de i18n/fr, et la mise en page de votre site et votre page d'accueil devraient maintenant être traduites.

Traduisez les fichiers Markdown

Les plugins officiels de contenu Docusaurus utilisent largement les fichiers Markdown/MDX et vous permettent de les traduire.

Traduisez les docs

Copiez vos fichiers docs Markdown depuis docs/ vers i18n/fr/docusaurus-plugin-content-docs/current, et traduisez-les :

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

info

Notez que le plugin docusaurus-plugin-content-docs divise toujours son contenu par versions. Les données dans le dossier ./docs seront traduites dans le sous-dossier current et le fichier current.json. Consultez le guide de version de doc pour plus d'informations sur ce que signifie "current".

Traduisez le blog

Copiez vos fichiers de blog Markdown dans i18n/fr/docusaurus-plugin-content-blog et traduisez-les :

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

Traduisez les pages

Copiez vos pages de fichiers Markdown vers i18n/fr/docusaurus-plugin-content-pages et traduisez-les :

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

attention

Nous ne copions que les fichiers .md et .mdx car les pages React sont déjà traduites par des fichiers de traduction JSON.

Utilisez les ID de titre explicites

Par défaut, un titre Markdown ### Hello World aura un ID généré hello-world. D'autres documents peuvent le cibler avec [link](#hello-world). Cependant, après traduction, le titre devient ### Bonjour le Monde, avec l'ID bonjour-le-monde.

Les ID générés ne sont pas toujours adaptés aux sites localisés, car ils vous obligent à localiser tous les liens d'ancrage :

- [link](#hello-world).
+ [link](#bonjour-le-monde)

Pour les sites localisés, il est recommandé d'utiliser les ID de titre explicites.

Déployez votre site

Vous pouvez choisir de déployer votre site sous un domaine unique ou utiliser plusieurs (sous-)domaines.

Déploiement sur un domaine unique

Exécutez la commande suivante :

npm
Yarn
pnpm

npm run build

yarn build

pnpm run build

Docusaurus construira une application mono-page par locale :

site/build : pour la langue par défaut, l'anglais
site/build/fr : pour la langue française

Vous pouvez maintenant déployer le dossier de compilation `` dans la solution d'hébergement statique de votre choix.

remarque

Le site web Docusaurus v2 utilise cette stratégie :

astuce

Les hébergeurs statiques redirigent généralement /unknown/url vers /404.html par convention, affichant toujours une page 404 anglaise.

Localisez vos 404 pages en configurant votre hôte pour rediriger /fr/* vers /fr/404.html.

Ce n'est pas toujours possible, et dépend de votre hôte : GitHub Pages ne peut pas le faire, Netlify peut.

Déploiement multi-domaines

Vous pouvez également construire votre site pour une seule locale :

npm
Yarn
pnpm

npm run build -- --locale fr

yarn build --locale fr

pnpm run build -- --locale fr

Docusaurus n'ajoutera pas le préfixe d'URL /fr/.

Sur votre hébergeur statique :

créez un déploiement par locale
configurez la commande build appropriée, en utilisant l'option --locale
configurez le (sous-)domaine de votre choix pour chaque déploiement

attention

Cette stratégie n'est pas possible avec les pages GitHub, car il n'est possible d'avoir un seul déploiement.

Hybride

Il est possible d'avoir des locales en utilisant des sous-chemins, et d'autres en utilisant des sous-domaines.

Il est également possible de déployer chaque locale en tant que sous-domaine séparé, assembler les sous-domaines dans un seul domaine unifié au niveau CDN :

Déployez votre site en tant que fr.docusaurus.io
Configurez un CDN pour le servir depuis docusaurus.io/fr

Gestion des traductions

Docusaurus ne se soucie pas de la manière dont vous gérez vos traductions : tout ce dont il a besoin, c'est que tous les fichiers de traduction (JSON, Markdown ou autres fichiers de données) soient disponibles dans le système de fichiers lors de la construction. Toutefois, en tant que créateurs de sites, vous devez tenir compte de la manière dont les traductions sont gérées afin que vos collaborateurs puissent collaborer efficacement.

Nous partagerons deux stratégies communes de collaboration en matière de traduction : en utilisant git et en utilisant Crowdin.

i18n - Tutoriel

Configurez votre site​

Configuration du site​

Configuration du thème​

Démarrez votre site​

Traduisez votre site​

Traduire votre code React​

Pluralisation​

Traduire les données du plugin​

Traduisez les fichiers Markdown​

Traduisez les docs​

Traduisez le blog​

Traduisez les pages​

Déployez votre site​

Déploiement sur un domaine unique​

Déploiement multi-domaines​

Hybride​

Gestion des traductions​

Configurez votre site

Configuration du site

Configuration du thème

Démarrez votre site

Traduisez votre site

Traduire votre code React

Pluralisation

Traduire les données du plugin

Traduisez les fichiers Markdown

Traduisez les docs

Traduisez le blog

Traduisez les pages

Déployez votre site

Déploiement sur un domaine unique

Déploiement multi-domaines

Hybride

Gestion des traductions