Aller au contenu principal
Version: 2.0.0-beta.4

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 @docusaurus/init@latest init 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'],  },};

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 run start -- --locale fr

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

Nous n'avons fourni aucune traduction, et 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.

caution

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 !#

Les traductions françaises seront ajoutées dans website/i18n/fr.

Docusaurus est modulaire, et chaque plugin de contenu a son propre sous-dossier.

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.

Utiliser les API de traduction#

Ouvrez la page d'accueil, et utilisez les API de traduction :

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={{blog: <Link to="https://docusaurus.io/blog">blog</Link>}}>          {'You can also visit my {blog}'}        </Translate>
        <input          type="text"          placeholder={            translate({              message: 'Hello',              description: 'The homepage input placeholder',            })          }        />      </main>    </Layout>  );}
caution

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.

Traduisez les fichiers JSON#

Les fichiers de traduction JSON sont utilisés pour tout ce qui n'est pas contenu dans un document Markdown :

  • Code React/JSX
  • Libellés de la barre de navigation et du pied de page
  • Libellés de catégorie de la barre latérale des documents
  • ...

Exécutez la commande write-translations :

npm run write-translations -- --locale fr

Cela extraira et initialisera les fichiers de traduction JSON que vous devez traduire.

Les traductions de la page d'accueil sont statiquement extraites du code source de React :

i18n/fr/code.json
{  "Welcome to my website": {    "message": "Welcome to my website",    "description": "The homepage welcome message"  },  "Hello": {    "message": "Hello",    "description": "The homepage input placeholder"  }}

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 dans i18n/fr/docusaurus-plugin-content-docs/current, et traduisez-les :

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

current est nécessaire pour la fonctionnalité de gestion de version de la documentation : chaque version de la documentation a son propre sous-dossier.

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-blogcp -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-pagescp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pagescp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
caution

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

Utilisez les identifiants 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).

Le titre traduit 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)
astuce

Pour les sites localisés, il est recommandé d'utiliser les identifiants 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 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/urls 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 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
caution

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