Aller au contenu principal

Workflow de Maintenance des Traductions

Pour les commandes de documentation générale (build, deploy, screenshots, génération README), voir Documentation Tools.

Vue d'ensemble​

La documentation utilise Docusaurus i18n avec l'anglais comme locale par défaut. La documentation source se trouve dans docs/ ; les traductions sont écrites sous i18n/{locale}/. Locales prises en charge : en-GB (par défaut), fr, de, es, pt-BR, hi-Latn, zh-Hans.

Traduction IA pour l'interface utilisateur de l'application, le markdown/JSON Docusaurus et les ressources SVG est gérée par ai-i18n-tools depuis la racine du dépôt, configurée dans ai-i18n-tools.config.json (pas à l'intérieur de documentation/). Définissez OPENROUTER_API_KEY lors de l'exécution des commandes de traduction.

Quand la documentation française change​

  1. Modifier la source dans documentation/docs/ (anglais uniquement).
  2. Chaînes d'interface Docusaurus (libellés du thème, barre de navigation, etc.) : si nécessaire, exécutez pnpm write-translations dans documentation/ pour que i18n/en/*.json récupère les nouvelles clés.
  3. Identifiants de titres : pnpm write-heading-ids (à partir de documentation/).
  4. Traduire depuis la racine du dépôt (ou utilisez les raccourcis ci-dessous depuis documentation/) :
    • pnpm i18n:extract — actualiser src/locales/strings.json depuis t('…') dans l'application Next.js.
    • pnpm i18n:translate:docs — traduire les fichiers markdown/JSON en documentation/i18n/ selon la configuration.
    • pnpm i18n:translate:svg — traduire les fichiers SVG situés dans documentation/static/img selon la configuration.
    • Ou exécutez tout : pnpm i18n:translate.
  5. Construire : cd documentation && pnpm build (toutes les langues).

Depuis l'intérieur de documentation/, les mêmes flux sont connectés comme pnpm translate → racine i18n:translate, plus pnpm translate:docs, translate:ui, translate:svg, translate:status, i18n:extract, i18n:sync.

Glossaire​

  • Terminologie de l'interface pour la documentation est pilotée par glossary.uiGlossary dans ai-i18n-tools.config.json, pointant vers src/locales/strings.json (le catalogue produit par pnpm i18n:extract).
  • Remplacements se trouvent dans documentation/glossary-user.csv (glossary.userGlossary dans la configuration). Consultez la documentation du glossaire ai-i18n-tools pour le format des colonnes.
  • Générer un modèle CSV : pnpm i18n:glossary-generate (racine).

Cache​

Le cache de traduction pour ai-i18n-tools se trouve dans .translation-cache/ à la racine du dépôt (cacheDir dans ai-i18n-tools.config.json). Il est ignoré par git. Utilisez pnpm i18n:status et les options --force / cache de l'interface en ligne de commande selon la documentation ai-i18n-tools lorsque vous avez besoin d'un rafraîchissement complet.

Identifiants de titres et ancres​

Utilisez des identifiants explicites afin que les liens restent stables entre les langues :

## This is a heading \{#this-is-a-heading}
cd documentation
pnpm write-heading-ids

Listes d'ignorance​

Utilisez .translate-ignore à la racine du dépôt (même principe que .gitignore) pour indiquer les chemins que le traducteur de documentation doit ignorer, si vous en ajoutez un pour votre flux de travail.

Thème JSON Docusaurus​

pnpm write-translations extrait les chaînes d'interface Docusaurus dans documentation/i18n/en/. L'étape ai-i18n-tools translate-docs (avec markdownOutput.style: "docusaurus") remplit les JSON traduits sous chaque langue à côté du markdown, selon ai-i18n-tools.config.json.

Dépannage​

  • OPENROUTER_API_KEY non défini — exportez-la ou ajoutez-la à .env.local à la racine du dépôt.
  • Modèle / qualité — ajustez openrouter.translationModels et les options associées dans ai-i18n-tools.config.json.
  • Glossaire — modifiez documentation/glossary-user.csv ou régénérez les chaînes d'interface, puis relancez extract + translate.

Ajout d'une nouvelle langue​

  1. Ajoutez la langue à la configuration Docusaurus i18n.locales et localeConfigs dans documentation/docusaurus.config.ts.
  2. Ajoutez la même langue à targetLocales dans ai-i18n-tools.config.json (racine du dépôt).
  3. Exécutez pnpm i18n:generate-ui-languages à la racine, puis les commandes pnpm i18n:extract / traduire selon les besoins.