Skip to content

Documents ​

Référence pour translate-docs, le pipeline pour les pages Markdown, MDX, .astro et HTML simples listées dans les blocs de configuration docs[]. Le champ contentPaths de chaque bloc liste les fichiers ou dossiers à traduire. Ces fichiers sont écrits en sourceLocale, qui peut être n'importe quelle langue. L'anglais dans les exemples n'est qu'un échantillon. Vous ajoutez des langues à un site pour la première fois ? Commencez par Ajouter l'i18n à un site web ou de documentation. Un fichier README de dépôt et d'autres fichiers Markdown, généralement à côté d'une application : Ajouter l'i18n à votre README et à vos documents Markdown. Les pages HTML simples (un fichier par locale) sont décrites dans Pages HTML.

Les chaînes de l'interface du framework (barre de navigation, barre latérale, thème) sont traduites en une seule passe, et non par un pipeline distinct. Les guides des frameworks dans le tableau ci-dessous expliquent comment chacun d'eux procède : docusaurusCatalogDir pour Docusaurus, docsOutput.vitepressThemeCatalog pour VitePress, docs[].nextraDictionaryPath pour Nextra, docsOutput.fumadocsUiCatalog pour Fumadocs. Les libellés de la barre latérale de Nextra _meta.ts et Fumadocs meta.json sont collectés automatiquement. Astro Starlight fournit des chaînes d'interface utilisateur intégrées pour de nombreuses locales, et les surcharges facultatives peuvent utiliser jsonPathTemplate sur un bloc docs[].

Pour les images PNG et autres images matricielles intégrées dans le markdown, voir Images et captures d'écran. translate-docs ne traduit que le texte alternatif ; il ne copie pas les fichiers matriciels.

Pour un bloc sélecteur de langue facultatif dans README ou les documents, définissez docsOutput.style sur "flat" - voir Sélecteur de langue.

Les fichiers SVG sont traduits via translate-svg lorsque features.translateSVG est activé - pas via docs[] / contentPaths.

Les paquets JSON d'interface utilisateur imbriqués arbitraires, sans rapport avec les chaînes de l'habillage/thème d'un framework de documentation, appartiennent au pipeline JSON, et non à docs[].

Chaque bloc d'interface utilisateur inclut son strings.json comme suggestions de glossaire pour la documentation par défaut (uiGlossary, true par défaut). translate-docs réutilise ces traductions comme suggestions dans les invites LLM lorsque des termes correspondants apparaissent dans un segment. Définissez uiGlossary sur false pour un catalogue qui doit être exclu des invites de document. L'option glossary.userGlossary ajoute des surcharges CSV pour les termes du produit (partagées avec translate-ui et proofread-ui). Les abréviations compactes des libellés d'interface utilisées pour s'adapter aux colonnes étroites (par exemple Size → Tam) restent disponibles pour la traduction de l'interface, mais sont omises des suggestions du glossaire de documentation. Générez un CSV de démarrage avec glossary-generate, modifiez les lignes dans l'onglet Glossaire du tableau de bord de traduction, ou consultez Configuration — glossary et Glossaire.

Substitutions de modèle par locale ​

translate-docs et l'étape de documentation de sync résolvent les modèles par locale cible : d'abord localeModels(locale) lorsqu'il est configuré, puis la chaîne globale translationModels du fournisseur. Utilisez cette option lorsqu'une langue spécifique nécessite un modèle différent de votre liste de secours par défaut - par exemple, en préférant Gemini pour la documentation pt-BR lorsque la chaîne globale a des difficultés avec le portugais. Consultez Modèles d'IA et Configuration - localeModels.

Quel guide lire ​

Votre configurationCommencez ici
Site Docusaurusinit -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
Site VitePressinit -t ui-vitepress + vitepressThemeCatalog pour le thème - VitePress
Site Nextrainit -t ui-nextra + nextraDictionaryPath pour le dictionnaire (la barre latérale _meta.ts est automatique) - Nextra
Site Fumadocsinit -t ui-fumadocs + fumadocsUiCatalog pour l'interface utilisateur (la barre latérale meta.json est automatique) - Fumadocs
Astro Starlightinit -t ui-starlight - Astro Starlight
Pages HTML brutesinit -t docs-plain-html - Pages HTML
Documents plats (README, journaux de modifications, etc.)Ajouter l'i18n à votre README et à vos documents Markdown — init -t docs-markdown ou --with-readme. Mise en page : Mises en page de sortie, sélecteur de langue
Où les fichiers traduits atterrissentDispositions de sortie
Liens #anchor entre pagesLiens d'ancrage
Réécriture d'URL de liens et d'actifs (regexAdjustments)Réécriture de liens
Captures d'écran dans la documentationImages et captures d'écran
Terminologie du produit et cohérence interface/docConfiguration — glossary, Glossaire
Drapeaux et cache translate-docsOptions CLI

Étape 1 : Initialisation pour la documentation ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai

Pour les sites de documentation Astro Starlight :

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference

Pour les sites de documentation VitePress :

bash
ai-i18n-tools init -t ui-vitepress -P anthropic

Définissez docsOutput.vitepressThemeCatalog pour les chaînes de navigation/barre latérale/pied de page - voir Intégration VitePress.

Pour les sites de documentation Nextra :

bash
ai-i18n-tools init -t ui-nextra -P gemini

Définissez docs[].nextraDictionaryPath pour les chaînes du dictionnaire de thème - voir Intégration Nextra. Les étiquettes de la barre latérale _meta.ts sont collectées automatiquement.

Pour les sites de documentation Fumadocs :

bash
ai-i18n-tools init -t ui-fumadocs -P groq

Définissez docsOutput.fumadocsUiCatalog pour les remplacements d'interface utilisateur - voir Intégration Fumadocs. Les étiquettes de la barre latérale meta.json sont collectées automatiquement.

Pour une interface utilisateur Astro simple (sans Starlight) :

bash
ai-i18n-tools init -t ui-astro-website -P ollama

Ce modèle permet uniquement l'extraction de l'interface utilisateur. Pour la traduction HTML des pages, définissez également features.translateDocs et ajoutez un bloc docs[] (voir Pages de site web Astro (analyse et remplacement)). La configuration examples/astro-website montre les deux pipelines ensemble.

Modifiez le fichier ai-i18n-tools.config.json généré :

  • provider et providers — init -P <provider> structure ce préréglage ; définissez sa clé d'API avant translate-docs ou sync (Ollama ne nécessite aucune clé). Consultez Fournisseur et clé d'API, Fournisseurs de LLM et Modèles d'IA.
  • sourceLocale - langue source (doit correspondre à defaultLocale dans docusaurus.config.js).
  • targetLocales - tableau de codes de locale BCP-47 (p. ex. ["de", "fr", "es"]).
  • cacheDir - répertoire de cache SQLite partagé pour tous les pipelines (et répertoire de journalisation par défaut pour --write-logs).
  • docs - tableau de blocs de documentation. Chaque bloc a un description facultatif, contentPaths (chaîne ou tableau ; fichier, répertoire ou glob), outputDir, docusaurusCatalogDir facultatif, docsOutput, segmentSplitting facultatif, translateFrontmatterFields, protectAttributes, protectKeys, targetLocales, addFrontmatter, etc.
  • docs[].description - courte note facultative pour les mainteneurs. Lorsqu'elle est définie, elle apparaît dans le titre translate-docs et dans les en-têtes de section status.
  • docs[].contentPaths - sources markdown/MDX/.astro (et docusaurusCatalogDir facultatif pour le JSON shell de Docusaurus).
  • docs[].outputDir - racine de sortie traduite pour ce bloc.
  • docs[].docsOutput.style - "nested" (par défaut), "flat", "doc-system", ou alias "docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs" (voir Mises en page de sortie).
  • ui[].uiGlossary - lorsque true (valeur par défaut), le strings.json de ce bloc fournit des suggestions de terminologie pour les segments de document (voir Configuration — ui).
  • glossary.userGlossary - CSV facultatif pour les traductions fixes des termes du produit ; également utilisé par les pipelines d'interface et modifiable dans l'onglet Glossaire du tableau de bord.

Principal contre secondaire : Concentrez-vous sur contentPaths pour les pages localisées. Définissez docusaurusCatalogDir lorsque vous avez également besoin du JSON du shell Docusaurus depuis write-translations. Omettez docusaurusCatalogDir si vous traduisez uniquement les pages.

Étape 2 : Traduire les documents ​

bash
ai-i18n-tools translate-docs

Ceci traduit tous les fichiers de chaque bloc docs[] contentPaths (et le JSON du catalogue Docusaurus lorsque docusaurusCatalogDir est défini) dans toutes les locales de documentation effectives. Les segments déjà traduits sont servis à partir du cache SQLite – seuls les segments nouveaux ou modifiés sont envoyés au LLM.

Pour traduire une seule langue :

bash
ai-i18n-tools translate-docs --locale de

Pour vérifier ce qui doit être traduit :

bash
ai-i18n-tools status

Pour les drapeaux, le comportement du cache et le format d'invite par lots, consultez Options CLI.

Markdown complexe et échecs de contrôle qualité ​

translate-docs vérifie que chaque segment traduit préserve la structure Markdown (y compris l'emphase analysée à partir du document) et que les jetons d'espace réservé internes sont restaurés correctement. Les paragraphes qui empilent de nombreuses étendues bold autour de `inline code`, imbriquent des apostrophes inversées dans du gras (par exemple, des littéraux de modèle tels que `fetch(\`/locales/${code}.json\`)`), ou entrelacent du gras et du code dans une longue phrase sont fragiles : certaines langues nécessitent un ordre des mots différent, ce qui peut modifier la façon dont ** et ` s'alignent après la traduction et déclencher des erreurs CLI telles que AST mismatch.

Après la restauration, translate-docs rejette également les segments où les espaces réservés des balises HTML ont été réutilisés ou supprimés (de sorte que les balises restaurées ne correspondent plus à la carte source) ou où le modèle a inventé des jetons à double accolade restants qui n'étaient pas dans la source (par exemple, un jeton de style glossaire inventé). Les vérifications avant la restauration exigent le même multiensemble de jetons {{…}} et la même sous-séquence ordonnée de jetons structurels ({{HTM_N}}, marqueurs d'avertissement) ; les jetons de contenu tels que {{ILC_N}}, {{URL_N}} et les marqueurs d'emphase comme {{SE}} peuvent se déplacer avec l'ordre naturel des mots lorsque chaque identifiant/type correspond toujours. Ces échecs utilisent le même chemin de secours du modèle que les jetons internes officiels restants.

Si vous rencontrez ce type d'échec de validation, préférez simplifier le texte source – divisez le paragraphe, déplacez un exemple dans un bloc de code clôturé, ou décrivez la même idée avec moins de paires gras/code superposées – plutôt que de vous attendre à ce que chaque modèle et locale reproduise parfaitement le balisage en ligne dense.

Lorsque les modèles tentés pour un segment échouent avec une AST mismatch, translate-docs peut automatiquement diviser ce segment en parties plus petites (point médian de la liste en premier, puis éléments de liste individuels ou morceaux de paragraphe plus courts), réessayer chaque partie à partir du premier modèle, et regrouper le résultat sous la clé de cache du segment d'origine. La même erreur de qualité à trois reprises arrête prématurément la liste des modèles ; une erreur différente permet de continuer. Ceci est activé par défaut (segmentSplitting.qualityRetrySplit) ; définissez-le sur false pour arrêter après la fin de la liste des modèles. Le résumé de l'exécution signale Quality split retries lorsque ce mécanisme de secours s'exécute.

Pour voir quels segments ont échoué, à quelle fréquence, et les messages de qualité/erreur stockés, utilisez l'onglet Échecs du tableau de bord de traduction (Tableau de bord de traduction → Échecs).

Publié sous licence MIT.