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.
Chemins d'accĂšs au systĂšme de fichiers diffĂ©rentsâ
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>;
Le CLI write-translations
fonctionne toujours pour extraire les traductions de votre code.
Les traductions de code sont maintenant ajoutées à i18n/[locale]/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.
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 :
- Migrer votre site Docusaurus v1 vers v2 sans les traductions
- Se familiariser avec le nouveau systĂšme i18n de Docusaurus v2
- Faire fonctionner Crowdin pour votre site v2, en utilisant un nouveau projet Crowdin non traduit et le tutoriel Crowdin
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.
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
ouslug
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.
Utilisez mdx-code-block
autour des éléments Markdown problématiques : Crowdin est moins susceptible de tout gùcher avec des blocs de code.
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.
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.
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.
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.