Aller au contenu principal
Version: 3.0.0-rc.1

Sites traduits

Cette page explique comment migrer un site traduit Docusaurus v1 vers Docusaurus v2.

i18n differences​

Docusaurus v2 i18n est conceptuellement assez similaire à Docusaurus v1 i18n avec quelques différences.

Il n'est pas fortement couplé à Crowdin, et vous pouvez utiliser Git ou un autre SaaS à la place.

Different filesystem paths​

On Docusaurus v2, localized content is generally found at website/i18n/[locale].

Docusaurus v2 est modulaire et il est basé sur un système de plugins, et chaque plugin est responsable de la gestion de ses propres traductions.

Each plugin has its own i18n subfolder, like: website/i18n/fr/docusaurus-plugin-content-blog

Updated translation APIs​

With Docusaurus v1, you translate your pages with <translate>:

const translate = require('../../server/translate.js').translate;

<h2>
  <translate desc="the header description">
    This header will be translated
  </translate>
</h2>;

On Docusaurus v2, you translate your pages with <Translate>

import Translate from '@docusaurus/Translate';

<h2>
  <Translate id="header.translation.id" description="the header description">
    This header will be translated
  </Translate>
</h2>;
remarque

The write-translations CLI still works to extract translations from your code.

The code translations are now added to i18n/[locale]/code.json using Chrome i18n JSON format.

Stricter Markdown parser​

Docusaurus v2 is using MDX to parse Markdown files.

MDX compile les fichiers Markdown en composants React, il est plus strict que l'analyseur Docusaurus v1 et il fera échouer votre compilation en cas d'erreur au lieu de rendre un contenu défectueux.

De plus, les éléments HTML doivent être remplacés par des éléments JSX.

C'est particulièrement important pour i18n car si vos traductions ne sont pas bonnes sur Crowdin et utilisent des balises invalides, votre site traduit v2 pourrait échouer à la construction : vous devrez peut-être effectuer un nettoyage des traductions pour corriger les erreurs.

Migration strategies​

This section will help you figure out how to keep your existing v1 translations after you migrate to v2.

There are multiple possible strategies to migrate a Docusaurus v1 site using Crowdin, with different tradeoffs.

attention

Cette documentation est un outil pour vous aider à migrer. Aidez-nous à l'améliorer si vous trouvez une meilleure solution !

Avant toute chose, nous vous recommandons de :

danger

N'essayez pas de migrer sans comprendre Crowdin et Docusaurus v2 i18n.

Create a new Crowdin project​

To avoid any risk of breaking your v1 site in production, one possible strategy is to duplicate the original v1 Crowdin project.

info

This strategy was used to upgrade the Jest website.

Malheureusement, Crowdin n'a aucune fonctionnalité « Dupliquer/clone du projet », ce qui complique les choses.

  • Download the translation memory of your original project in .tmx format (https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm > View Records)
  • Upload the translation memory to your new project (https://crowdin.com/project/<NEW_PROJECT>/settings#tm > View Records)
  • Reconfigure crowdin.yml for Docusaurus v2 according to the i18n docs
  • Téléchargez les fichiers source de Docusaurus v2 avec la CLI Crowdin vers le nouveau projet
  • Mark sensitive strings like id or slug as "hidden string" on Crowdin
  • On the "Translations" tab, click on "Pre-Translation > via TM" (https://crowdin.com/project/<NEW_PROJECT>/settings#translations)
  • Essayez d'abord avec « 100% match » (plus de contenu sera traduit en « Perfect ») et pré-traduisez vos sources
  • Téléchargez les traductions de Crowdin localement
  • Essayez d'exécuter/construire votre site et voyez s'il y a des erreurs

Vous aurez probablement des erreurs sur votre premier essai : la pré-traduction peut essayer de traduire des choses qu'il ne faut pas traduire (frontmatter, admonition, blocs de code...), et les fichiers MD traduits peuvent être invalides pour l'analyseur MDX.

Vous devrez corriger toutes les erreurs jusqu'à la compilation de votre site. You can do that by modifying the translated MD files locally, and fix your site for one locale at a time using docusaurus build --locale fr.

Il n'y a pas de guide ultime que nous pourrions écrire pour corriger ces erreurs, mais les erreurs courantes sont dues à :

  • Trop peu de chaînes de caractères sont marquées comme "chaînes cachées" dans Crowdin, ce qui entraîne des tentatives de pré-traduction de ces chaînes de caractères.
  • Avoir de mauvaises traductions v1, conduisant à un balisage invalide en v2 : des mauvais éléments HTML dans les traductions et des balises non fermées
  • Anything rejected by the MDX parser, like using HTML elements instead of JSX elements (use the MDX playground for debugging)

Vous pouvez répéter ce processus de pré-traduction, en essayant éventuellement l'option « Perfect » et en limitant la pré-traduction à certaines langues/fichiers.

astuce

Utilisez mdx-code-block autour des éléments Markdown problématiques : Crowdin est moins susceptible de tout gâcher avec des blocs de code.

remarque

Vous remarquerez probablement que certaines choses ont été traduites sur votre ancien projet, mais sont maintenant non traduites dans votre nouveau projet.

L'analyseur Markdown de Crowdin évolue en permanence et chaque projet Crowdin possède une version différente de l'analyseur, ce qui peut conduire à ce que la pré-traduction ne soit pas en mesure de pré-traduire toutes les chaînes de caractères.

Cette version de l'analyseur est non documentée, et vous devrez demander au support de Crowdin de connaître la version de l'analyseur de votre projet et de corriger une version spécifique.

L'utilisation de la même version du CLI et de l'analyseur à travers les 2 projets Crowdin pourrait donner de meilleurs résultats.

danger

Crowdin dispose d'une fonction « télécharger des traductions », mais d'après notre expérience, elle ne donne pas de très bons résultats pour Markdown

Use the existing Crowdin project​

Si cela ne vous dérange pas de modifier votre projet Crowdin existant et de risquer de tout gâcher, il est possible d'utiliser le système de branches de Crowdin.

attention

Ce workflow n'a pas été testé dans la pratique, veuillez nous faire part de sa qualité.

De cette façon, vous n'auriez pas besoin de créer un nouveau projet Crowdin, de transférer la mémoire de traduction, d'appliquer les pré-traductions et d'essayer de corriger les erreurs de pré-traduction.

Vous pouvez créer une branche Crowdin pour Docusaurus v2, où vous téléchargez les sources v2, et fusionnez la branche Crowdin vers main une fois prête.

Use Git instead of Crowdin​

Il est possible de s'éloigner de Crowdin et d'ajouter à la place les fichiers de traduction à Git.

Utilisez Crowdin CLI pour télécharger les fichiers traduits v1 et mettez ces fichiers traduits au bon endroit du système de fichiers Docusaurus v2.