Aller au contenu principal
Version: 2.0.0-beta.0

Sites traduits

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

Différences i18n#

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.

Différents chemins du systÚme de fichiers#

Sur Docusaurus v2, le contenu localisé se trouve généralement dans 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.

Chaque plugin a son propre sous-dossier i18n, comme : website/i18n/fr/docusaurus-plugin-content-blog

API de traduction mise Ă  jour#

Avec Docusaurus v1, vous traduisez vos pages avec <translate> :

const translate = require('../../server/translate.js').translate;
<h2>  <translate desc="la description de l'entĂȘte">    Cet entĂȘte sera traduit  </translate></h2>;

Sur Docusaurus v2, vous traduisez vos pages avec <Translate>

import Translate from '@docusaurus/Translate';
<h2>  <Translate id="header.translation.id" description="la description de l'entĂȘte">    Cet entĂȘte sera traduit  </Translate></h2>;
remarque

Le CLI write-translations fonctionne toujours pour extraire les traductions de votre code.

Les traductions de code sont maintenant ajoutées à i18n/<lang>/code.json en utilisant le format JSON Chrome i18n.

Analyseur Markdown plus strict#

Docusaurus v2 utilise MDX pour analyser les fichiers Markdown.

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.

Stratégies de migration#

Cette section vous aidera à trouver comment garder vos traductions existantes en v1 aprÚs avoir migré en v2.

Il y a plusieurs stratégies possibles pour migrer un site Docusaurus v1 en utilisant Crowdin, avec des compromis différents.

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.

Créer un nouveau projet Crowdin#

Pour éviter tout risque de casser votre site v1 en production, une stratégie possible est de dupliquer le projet original v1 de Crowdin.

info

Cette stratégie a été utilisée pour mettre à jour le site Jest.

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

  • TĂ©lĂ©chargez la mĂ©moire de traduction de votre projet original au format .tmx (https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm > View Records)
  • TĂ©lĂ©chargez la mĂ©moire de traduction dans votre nouveau projet (https://crowdin.com/project/<NEW_PROJECT>/settings#tm > View Records)
  • Reconfigurez crowdin.yml pour Docusaurus v2 selon les docs i18n
  • TĂ©lĂ©chargez les fichiers source de Docusaurus v2 avec la CLI Crowdin vers le nouveau projet
  • Marquer les chaĂźnes sensibles comme id ou slug comme « chaĂźne cachĂ©e » (hidden string) sur Crowdin
  • Dans l'onglet « Translations », cliquez sur « 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. Vous pouvez le faire en modifiant les fichiers md traduits localement, et corrigez votre site pour une locale Ă  la fois en utilisant 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
  • Tout ce qui a Ă©tĂ© rejetĂ© par l'analyseur MDX, comme utiliser des Ă©lĂ©ments HTML au lieu des Ă©lĂ©ments JSX (utiliser le terrain de jeu MDX pour le dĂ©bogage)

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

Utiliser le projet Crowdin existant#

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 master une fois prĂȘte.

Utiliser Git au lieu de 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.