Docusaurus

Le paquet translate-projects-docusaurus traduit les pages de documentation, le blog, les pages React (code.json) et les textes du thème d'un site Docusaurus, puis les écrit dans la structure i18n/ que Docusaurus comprend déjà.

Prérequis

• Node.js 20 ou supérieur.
• Un site Docusaurus 3 avec le script write-translations dans package.json (inclus dans le modèle officiel).
• Un projet et un jeton API de Translate Projects. Consultez Premiers pas.

1. Installe le paquet

Terminal

npm i -D translate-projects-docusaurus

2. Activez les langues dans Docusaurus

Ajoutez les langues dans docusaurus.config.js ainsi que le sélecteur de langue dans la barre de navigation :

docusaurus.config.js

export default {
  i18n: {
    defaultLocale: 'es',
    locales: ['es', 'en', 'pt-BR', 'fr'],
    localeConfigs: {
      es: { label: 'Español' },
      en: { label: 'English' },
      'pt-BR': { label: 'Português (Brasil)' },
      fr: { label: 'Français' },
    },
  },
  themeConfig: {
    navbar: {
      items: [{ type: 'localeDropdown', position: 'right' }],
    },
  },
};

3. Écris tes textes dans le dossier translate/

Déplace tes dossiers docs/ et blog/ dans translate/. Désormais, tu modifies uniquement translate/ : le paquet génère docs/, blog/ et i18n/ à chaque exécution.

Terminal

mkdir translate
mv docs blog translate/

Structure

translate/
├── docs/
│   └── intro.md
└── blog/
    └── 2025-01-01-bienvenida.md

Entoure de doubles accolades chaque texte que tu veux traduire. Ce qui n'est pas marqué (code, liens, noms) est copié tel quel :

translate/docs/intro.md

---
title: {{Primeros pasos}}
---

# {{Bienvenido a mi proyecto}}

{{Este párrafo se traduce.}} [{{Ver ejemplo}}](https://example.com)

• Écris le texte collé aux accolades, sans espaces au début ni à la fin.
• Pour écrire des accolades littérales (par exemple les variables i18next dans un bloc de code), place une barre oblique inverse devant. Elles ne sont pas envoyées à la traduction et la barre oblique disparaît dans le résultat : \{{lng}} → {{lng}}.
• En dehors des blocs de code, MDX n'admet pas les accolades isolées : ne laissez pas de doubles accolades non fermées.

4. Configurer la traduction

Créez translate.config.mjs à la racine du site. Le jeton API est lu à partir de la variable d'environnement TRANSLATE_PROJECTS_API_KEY:

translate.config.mjs

export default {
  sourceLang: 'es', // Langue de base : la langue par défaut du projet
  targetLangs: ['en', 'pt-BR', 'fr'], // Langues à générer
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
};

Et le script dans package.json:

package.json

{
  "scripts": {
    "translate": "translate-projects-docusaurus"
  }
}

Options

Option	Par défaut	Description
sourceLang	—	Langue de base (obligatoire).
targetLangs	—	Langues à générer (obligatoire).
apiKey	—	Token API du projet.
force	false	Ignore le cache et retraduit tout (identique à --force).
docs	{ enable: true, baseDir: './translate/docs', outputDir: './docs' }	Documentation.
blog	{ enable: true, baseDir: './translate/blog', outputDir: './blog' }	Blog. Désactive-le si ton site n'a pas de blog.
react	{ enable: true }	Textes de tes pages React (i18n/<lang>/code.json).
theme	{ enable: true, ignoreKeys: [] }	Textes du thème (barre de navigation et pied de page). Dans ignoreKeys, indique les clés qui ne doivent pas être traduites.
config	{ outputDir: './i18n' }	Dossier i18n de Docusaurus.

5. Traduis

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

Compile ensuite le site avec toutes les langues :

Terminal

npm run build
npm run serve

Fichiers générés

Origine	Langue de base	Autres langues
translate/docs/**	docs/**	i18n/<lang>/docusaurus-plugin-content-docs/current/**
translate/blog/**	blog/**	i18n/<lang>/docusaurus-plugin-content-blog/**
i18n/<base>/code.json	—	i18n/<lang>/code.json
i18n/<base>/docusaurus-theme-classic/*.json	—	i18n/<lang>/docusaurus-theme-classic/*.json

Les images et autres fichiers non textuels sont copiés dans chaque langue. Si tu déploies depuis le dépôt, inclus docs/, blog/ et i18n/ dans le déploiement ou exécute la traduction avant le build.

Aperçu pendant la rédaction

Le mode --dev surveille translate/ et met à jour la langue de base instantanément, sans appeler l'API :

Terminal 1

npx docusaurus start --locale es

Terminal 2

npx translate-projects-docusaurus --dev

Cache et --force

Seuls les fichiers modifiés sont traduits ; une deuxième exécution sans modifications ne traduit rien. Pour tout retraduire :

Terminal

npx translate-projects-docusaurus --force

Plus de détails dans Cache et erreurs.

Erreurs courantes

• Jeton invalide (401): vérifiez TRANSLATE_PROJECTS_API_KEY. Aucun fichier n'est écrit ni supprimé.
• Clé d'IA manquante (MISSING_API_KEY): configure le fournisseur, le modèle et la clé dans le projet. En attendant, les textes restent dans la langue de base.
• Traduction partielle: les textes manquants restent dans la langue de base, la commande se termine avec le code 1 et ils seront demandés à nouveau lors de l'exécution suivante.
• Le build échoue avec Invalid translation file: il existe un fichier JSON vide ou corrompu dans i18n/. Supprimez-le et exécutez npm run write-translations -- --locale <lang>.
• Des doubles accolades apparaissent sur la page traduite: le texte contenait des espaces à l'intérieur des accolades ou il s'agissait d'accolades littérales sans \.

Gratuit

🚀 Automatisez vos traductions gratuitement

Translate Projects est gratuit. Vous créez votre projet, connectez la clé de votre fournisseur d'IA et ne lui payez que ce que vous dépensez.

• Sans forfaits ni carte de crédit: Toutes les fonctionnalités sont disponibles dès le premier jour.
• Utilisez votre propre IA: Claude, OpenAI, DeepSeek ou Gemini. Votre clé est stockée chiffrée.
• Réseau de traductions partagé: Si un texte a déjà été traduit, vous le recevez instantanément sans dépenser votre clé.
• Panneau d'administration: Vérifiez et modifiez toutes vos traductions depuis un seul endroit.

Créer un compte gratuitement →

Support

Nous sommes là pour vous aider

Si vous avez des questions, besoin d'aide ou souhaitez contribuer, n'hésitez pas à me contacter. Je suis à votre disposition pour vous soutenir dans tout ce dont vous avez besoin.

• Site web: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

Soutenez le projet

Si ce projet vous a été utile, je vous invite à m'offrir un café. Votre soutien m'aide à continuer de m'améliorer et à créer du contenu de valeur. Merci d'être là ! ☕