Aller au contenu principal
Version : 3.0.1

i18n - Utilisation de Crowdin

Le systÚme i18n de Docusaurus est indépendant de tout logiciel de traduction.

Vous pouvez intégrer Docusaurus avec les outils et le SaaS de votre choix, à condition de placer les fichiers de traduction au bon endroit.

Nous documentons l'utilisation de Crowdin, comme un exemple d'intégration possible.

attention

Ceci n'est pas une recommandation de Crowdin comme choix unique pour traduire un site Docusaurus, mais il est utilisé avec succÚs par Facebook pour traduire des projets de documentation tels que Jest, Docusaurus et ReasonML.

Consultez la documentation de Crowdin et l'assistance de Crowdin pour obtenir de l'aide.

astuce

Utilisez cette discussion GitHub pilotée par la communauté pour discuter de tout ce qui concerne Docusaurus + Crowdin.

Vue d'ensemble de Crowdin​

Crowdin est un service de traduction SaaS qui propose un plan gratuit pour les projets open-source.

Nous recommandons le flux de travail de traduction suivant :

  • DĂ©versez les sources vers Crowdin (fichiers non traduits)
  • Utilisez Crowdin pour traduire le contenu
  • TĂ©lĂ©chargez les traductions depuis Crowdin (fichiers de traduction localisĂ©s)

Crowdin fournit une CLI pour déverser des sources et télécharger des traductions, vous permettant d'automatiser le processus de traduction.

Le fichier de configuration crowdin.yml est pratique pour Docusaurus, et permet de télécharger les fichiers de traduction localisés à l'emplacement prévu (dans i18n/[locale]/..).

Lisez la documentation officielle pour en savoir plus sur les fonctionnalités avancées et les différents flux de travail de traduction.

Tutoriel Crowdin​

Il s'agit d'une présentation de l'utilisation de Crowdin pour traduire en français un site web Docusaurus anglais nouvellement initialisé, et suppose que vous avez déjà suivi le tutoriel i18n.

Le rĂ©sultat final peut ĂȘtre vu sur docusaurus-crowdin-example.netlify.app (dĂ©pĂŽt).

PrĂ©parez le site Docusaurus​

Initialisez un nouveau site Docusaurus :

npx create-docusaurus@latest website classic

Ajoutez la configuration du site pour la langue française :

docusaurus.config.js
export default {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
themeConfig: {
navbar: {
items: [
// ...
{
type: 'localeDropdown',
position: 'left',
},
// ...
],
},
},
// ...
};

Traduisez la page d'accueil :

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

export default function Home() {
return (
<Layout>
<h1 style={{margin: 20}}>
<Translate description="The homepage main heading">
Welcome to my Docusaurus translated site!
</Translate>
</h1>
</Layout>
);
}

CrĂ©ez un projet Crowdin​

Inscrivez-vous sur Crowdin, et créez un projet.

Utiliser l'anglais comme langue source et le français comme langue cible.

Créer un projet Crowdin en anglais comme langue source, et en français comme langue cible

Votre projet est créé, mais il est vide pour le moment. Nous allons déverser les fichiers à traduire dans les prochaines étapes.

CrĂ©ez la configuration Crowdin​

Cette configuration (doc) fournit une cartographie pour que le CLI de Crowdin comprenne :

  • OĂč trouver les fichiers source Ă  dĂ©verser (JSON et Markdown)
  • OĂč tĂ©lĂ©charger les fichiers aprĂšs traduction (dans i18n/[locale])

CrĂ©ez crowdin.yml dans website :

crowdin.yml
project_id: '123456'
api_token_env: CROWDIN_PERSONAL_TOKEN
preserve_hierarchy: true
files:
# JSON translation files
- source: /i18n/en/**/*
translation: /i18n/%two_letters_code%/**/%original_file_name%
# Docs Markdown files
- source: /docs/**/*
translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
# Blog Markdown files
- source: /blog/**/*
translation: /i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%

Crowdin a sa propre syntaxe pour déclarer les chemins source/traduction :

  • **/* : tout ce qui est dans un sous-dossier
  • %two_letters_code% : la variante de 2 lettres des langues cibles Crowdin (fr dans notre cas)
  • **/%original_file_name% : les traductions prĂ©serveront la hiĂ©rarchie des dossiers/fichiers d'origine
info

Les avertissements de Crowdin CLI ne sont pas toujours faciles Ă  comprendre.

Nous vous conseillons :

  • modifier une chose Ă  la fois
  • re-dĂ©verser les sources aprĂšs tout changement de configuration
  • utiliser des chemins commençant par / (./ ne fonctionne pas)
  • Ă©viter les pratiques de globalisation sophistiquĂ©es comme /docs/**/*.(md|mdx) (ne fonctionne pas)

Jeton d'accùs​

L'attribut api_token_env définit le nom de la variable env lu par le CLI Crowdin.

Vous pouvez obtenir un Personal Access Token sur votre page de profil personnel.

astuce

Vous pouvez conserver la valeur par défaut CROWDIN_PERSONAL_TOKEN et définir cette variable d'environnement sur votre ordinateur et sur le serveur CI avec le jeton d'accÚs généré.

attention

Un jeton d'accĂšs personnel accorde un accĂšs en lecture et Ă©criture Ă  tous vos projets Crowdin.

Vous ne devez pas le « commiter Â» et il peut ĂȘtre judicieux de crĂ©er un profil Crowdin dĂ©diĂ© Ă  votre entreprise au lieu d'utiliser un compte personnel.

Autres champs de configuration​

  • project_id : peut ĂȘtre codĂ© en dur et se trouve sur https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api
  • prĂ©serve_hierarchy : prĂ©serve la hiĂ©rarchie des dossiers sur l'interface utilisateur Crowdin au lieu de tout aplanir

Installez la CLI de Crowdin​

Ce tutoriel utilise le CLI de la version 3.5.2, mais nous nous attendons Ă  ce que les versions 3.x continuent Ă  fonctionner.

Installez Crowdin CLI en tant que paquet npm sur votre site Docusaurus :

npm install @crowdin/cli@3

Ajoutez un script crowdin :

package.json
{
"scripts": {
// ...
"write-translations": "docusaurus write-translations",
"crowdin": "crowdin"
}
}

Vérifiez que vous pouvez exécuter le CLI de Crowdin :

npm run crowdin -- --version

DĂ©finissez la variable d'environnement CROWDIN_PERSONAL_TOKEN sur votre ordinateur, pour permettre au CLI de s'authentifier avec l'API Crowdin.

astuce

Temporairement, vous pouvez coder en dur votre jeton personnel dans crowdin.yml avec api_token: 'MY-TOKEN'.

DĂ©versez les sources​

GĂ©nĂ©rer les fichiers de traduction JSON pour la langue par dĂ©faut dans website/i18n/en :

npm run write-translations

DĂ©verser tous les fichiers de traduction JSON et Markdown :

npm run crowdin upload

CLI de Crowdin téléchargeant les fichiers sources de Docusaurus

Vos fichiers sources sont maintenant visibles sur l'interface Crowdin : https://crowdin.com/project/<MY_PROJECT_NAME>/settings#files

Interface utilisateur de Crowdin montrant les fichiers sources de Docusaurus

Traduisez les sources​

Sur https://crowdin.com/project/<MY_PROJECT_NAME>, cliquez sur la langue cible : « French Â».

L&#39;interface utilisateur de Crowdin affichant les fichiers de traduction en français

Traduisez des fichiers Markdown.

Interface utilisateur de Crowdin pour traduire un fichier Markdown

astuce

Utilisez Hide String pour vous assurer que les traducteurs ne traduisent pas des choses qui ne devraient pas l'ĂȘtre :

  • Front matter : id, slug, tags ...
  • Admonitions : :::, :::note, :::tip ...

Interface utilisateur de Crowdin avec chaßne masquée

Traduisez des fichiers JSON.

Interface utilisateur de Crowdin pour traduire un fichier JSON

info

L'attribut description des fichiers de traduction JSON est visible sur Crowdin pour aider Ă  traduire les chaĂźnes.

astuce

Pré-traduisez votre site, et corrigez les erreurs de pré-traduction manuellement (activez d'abord la mémoire de traduction globale dans les paramÚtres).

Utilisez d'abord la fonction Hide String, car Crowdin pré-traduit les choses de maniÚre trop optimiste.

TĂ©lĂ©chargez les traductions​

Utilisez Crowdin CLI pour télécharger les fichiers JSON et Markdown traduits.

npm run crowdin download

Le contenu traduit doit ĂȘtre tĂ©lĂ©chargĂ© dans i18n/fr.

Démarrez votre site dans la langue française :

npm run start -- --locale fr

Assurez-vous que votre site web est maintenant traduit en français à l'adresse http://localhost:3000/fr/.

Automatisez avec le CI​

Nous allons configurer le CI pour télécharger les traductions de Crowdin au moment de la construction et les conserver en dehors de Git.

Ajoutez website/i18n dans .gitignore.

DĂ©finissez la variable d'environnement CROWDIN_PERSONAL_TOKEN sur votre CI.

CrĂ©er un script npm pour sync (synchroniser) Crowdin (extraire des sources, dĂ©verser des sources, tĂ©lĂ©charger des traductions) :

package.json
{
"scripts": {
"crowdin:sync": "docusaurus write-translations && crowdin upload && crowdin download"
}
}

Appelez le script npm run crowdin:sync dans votre CI, juste avant de construire le site Docusaurus.

astuce

Pour conserver des déploiments d'aperçus rapides : ne déversez pas les traductions, et utilisez npm run build -- --locale en pour les branches de fonctionnalités.

attention

Crowdin ne supporte pas bien plusieurs déversements/téléchargements simultanés : il est préférable d'ajouter des traductions uniquement à votre déploiement de production, et de continuer à déployer des aperçus non traduits.

Sujets avancĂ©s de Crowdin​

MDX​

attention

Faites particuliĂšrement attention aux fragments JSX dans les documents MDX !

Crowdin ne prend pas en charge officiellement MDX, mais ils ont ajouté le support pour l'extension .mdx et interprÚtent ces fichiers comme du Markdown (au lieu du texte brut).

Problùmes MDX​

Crowdin pense que la syntaxe JSX est du HTML intégré, et qu'elle peut se mélanger avec le balisage JSX lorsque vous téléchargez les traductions, ce qui conduit à un site qui ne se construit pas en raison d'un JSX invalide.

Les fragments JSX simples utilisant des props simples de type chaĂźne comme <Username name="Sebastien"/> fonctionneront bien; les fragments JSX plus complexes utilisant des props de type objet/tableau comme <User person={{name: "Sebastien"}}/> sont plus susceptibles d'Ă©chouer en raison d'une syntaxe qui ne ressemble pas Ă  celle du HTML.

Solutions MDX​

Nous recommandons d'extraire le code JSX complexe intĂ©grĂ© en tant que composants autonomes distincts. Nous avons Ă©galement ajoutĂ© une syntaxe d'Ă©chappement mdx-code-block :

# Comment déployer Docusaurus

Pour dĂ©ployer Docusaurus, exĂ©cutez la commande suivante :

````mdx-code-block

import Tabs from '@theme/Tabs';

import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="bash" label="Bash">

```bash
GIT_USER=<GITHUB_USERNAME> yarn deploy
```

</TabItem>
<TabItem value="windows" label="Windows">

```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
```

</TabItem>
</Tabs>
````

Ceci va :

  • ĂȘtre interprĂ©tĂ© par Crowdin comme des blocs de code (et ne pas se mĂ©langer avec le balisage au tĂ©lĂ©chargement)
  • ĂȘtre interprĂ©tĂ© par Docusaurus comme du JSX normal (comme s'il n'Ă©tait enveloppĂ© par aucun bloc de code)
  • malheureusement, il n'est pas possible d'utiliser les outils MDX (coloration syntaxique des IDE, Prettier...)

Gestion de version de Docs​

Configurez les fichiers de traduction du dossier website/versioned_docs.

Lors de la création d'une nouvelle version, les chaßnes sources seront généralement similaires à la version actuelle (website/docs) et vous ne voulez pas traduire la nouvelle version de docs encore et encore.

Crowdin fournit un paramÚtre Duplicate Strings (chaßnes de caractÚres dupliquées).

RĂ©glage d&#39;option Crowdin Duplicate Strings

Nous vous recommandons d'utiliser Hide, mais le réglage idéal dépend de la différence entre vos versions.

attention

Ne pas utiliser Hide conduit à une quantité beaucoup plus importante de source strings (chaßnes de caractÚres) dans les quotas, et affectera la tarification.

Plugins multi-instance​

Vous devez configurer les fichiers de traduction pour chaque instance de plugin.

Si vous avez une instance du plugin docs avec id=ios, vous devrez configurer ces fichiers sources Ă©galement

  • website/ios
  • website/ios_versioned_docs (si versionnĂ©)

Maintenance de votre site​

Parfois, vous allez supprimer ou renommer un fichier source sur Git, et Crowdin affichera des avertissements CLI :

CLI de Crowdin : avertissement sur le chargement de la traduction

Lorsque vos sources sont remaniĂ©es, vous devez utiliser l'interface utilisateur Crowdin pour mettre Ă  jour vos fichiers Crowdin manuellement :

Interface utilisateur de Crowdin : renommage d&#39;un fichier

IntĂ©grations VCS (Git)​

Crowdin a plusieurs intégrations VCS pour GitHub, GitLab, Bitbucket.

TL;DR

Nous recommandons de les Ă©viter.

Il aurait pu ĂȘtre utile de pouvoir Ă©diter les traductions Ă  la fois dans Git et Crowdin, et d'avoir une synchronisation bidirectionnelle entre les 2 systĂšmes.

En pratique, cela n'a pas fonctionné de maniÚre trÚs fiable pour plusieurs raisons :

  • La synchronisation Crowdin -> Git fonctionne bien (avec une pull request)
  • La synchronisation Git -> Crowdin est manuelle (vous devez appuyer sur un bouton)
  • L'heuristique utilisĂ©e par Crowdin pour faire correspondre les traductions Markdown existantes aux sources Markdown existantes n'est pas fiable Ă  100%, et vous devez vĂ©rifier le rĂ©sultat sur l'interface Crowdin aprĂšs toute synchronisation Ă  partir de Git
  • 2 utilisateurs Ă©ditant simultanĂ©ment sur Git et Crowdin peuvent entraĂźner une perte de traduction
  • Il faut que le fichier crowdin.yml soit Ă  la racine du dĂ©pĂŽt

Traduction dans le contexte​

Crowdin dispose d'une fonction de localisation dans le contexte.

attention

Malheureusement, cela ne fonctionne pas encore pour des raisons techniques, mais nous avons bon espoir que cela puisse ĂȘtre rĂ©solu.

Crowdin remplace les chaßnes Markdown par des ID techniques tels que crowdin:id12345, mais il le fait de maniÚre trop agressive, y compris les chaßnes cachées, et s'embrouille avec le frontmatter du Markdown, les admonitions, le JSX...

Traduisez les URL de modification​

Quand l'utilisateur navigue sur une page à /fr/doc1, le bouton de modification liera par défaut le doc non localisé website/docs/doc1.md.

Vous pouvez préférer que le bouton de modification renvoie plutÎt vers l'interface Crowdin, et vous pouvez utiliser la fonction editUrl pour personnaliser les URL de modification en fonction de la localisation.

docusaurus.config.js
const DefaultLocale = 'en';

export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
editUrl: ({locale, versionDocsDirPath, docPath}) => {
// Lien vers Crowdin pour les docs françaises
if (locale !== DefaultLocale) {
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
}
// Lien vers GitHub pour les docs anglaises
return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`;
},
},
blog: {
editUrl: ({locale, blogDirPath, blogPath}) => {
if (locale !== DefaultLocale) {
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
}
return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
},
},
},
],
],
};
remarque

Il est actuellement impossible de créer un lien vers un fichier spécifique dans Crowdin.

Exemple de configuration​

Le fichier de configuration Docusaurus est un bon exemple d'utilisation de la gestion de version et de la multi-instance :

crowdin.yml
project_id: '428890'
api_token_env: CROWDIN_PERSONAL_TOKEN
preserve_hierarchy: true
languages_mapping: &languages_mapping
two_letters_code:
pt-BR: pt-BR
files:
- source: /website/i18n/en/**/*
translation: /website/i18n/%two_letters_code%/**/%original_file_name%
languages_mapping: *languages_mapping
- source: /website/docs/**/*
translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
languages_mapping: *languages_mapping
- source: /website/community/**/*
translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%
languages_mapping: *languages_mapping
- source: /website/versioned_docs/**/*
translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
languages_mapping: *languages_mapping
- source: /website/blog/**/*
translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
languages_mapping: *languages_mapping
- source: /website/src/pages/**/*
translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%
ignore: [/**/*.js, /**/*.jsx, /**/*.ts, /**/*.tsx, /**/*.css]
languages_mapping: *languages_mapping