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 configuration | Commencez ici |
|---|---|
| Site Docusaurus | init -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus |
| Site VitePress | init -t ui-vitepress + vitepressThemeCatalog pour le thème - VitePress |
| Site Nextra | init -t ui-nextra + nextraDictionaryPath pour le dictionnaire (la barre latérale _meta.ts est automatique) - Nextra |
| Site Fumadocs | init -t ui-fumadocs + fumadocsUiCatalog pour l'interface utilisateur (la barre latérale meta.json est automatique) - Fumadocs |
| Astro Starlight | init -t ui-starlight - Astro Starlight |
| Pages HTML brutes | init -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 atterrissent | Dispositions de sortie |
Liens #anchor entre pages | Liens d'ancrage |
Réécriture d'URL de liens et d'actifs (regexAdjustments) | Réécriture de liens |
| Captures d'écran dans la documentation | Images et captures d'écran |
| Terminologie du produit et cohérence interface/doc | Configuration — glossary, Glossaire |
Drapeaux et cache translate-docs | Options CLI |
Étape 1 : Initialisation pour la documentation
ai-i18n-tools init -t ui-docusaurus -P openaiPour les sites de documentation Astro Starlight :
ai-i18n-tools init -t ui-starlight -P cheaperinferencePour les sites de documentation VitePress :
ai-i18n-tools init -t ui-vitepress -P anthropicDé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 :
ai-i18n-tools init -t ui-nextra -P geminiDé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 :
ai-i18n-tools init -t ui-fumadocs -P groqDé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) :
ai-i18n-tools init -t ui-astro-website -P ollamaCe 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é :
provideretproviders—init -P <provider>structure ce préréglage ; définissez sa clé d'API avanttranslate-docsousync(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 àdefaultLocaledansdocusaurus.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 undescriptionfacultatif,contentPaths(chaîne ou tableau ; fichier, répertoire ou glob),outputDir,docusaurusCatalogDirfacultatif,docsOutput,segmentSplittingfacultatif,translateFrontmatterFields,protectAttributes,protectKeys,targetLocales,addFrontmatter, etc.docs[].description- courte note facultative pour les mainteneurs. Lorsqu'elle est définie, elle apparaît dans le titretranslate-docset dans les en-têtes de sectionstatus.docs[].contentPaths- sources markdown/MDX/.astro(etdocusaurusCatalogDirfacultatif 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- lorsquetrue(valeur par défaut), lestrings.jsonde 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
ai-i18n-tools translate-docsCeci 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 :
ai-i18n-tools translate-docs --locale dePour vérifier ce qui doit être traduit :
ai-i18n-tools statusPour 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).