Documents
Reference for translate-docs, the pipeline for Markdown, MDX, .astro, and plain HTML pages listed in docs[] config blocks. Each block's contentPaths field lists the files or folders to translate. Those files are written in sourceLocale, which can be any language. English in the examples is only a sample. Adding languages to a site for the first time? Start at Add i18n to a website or docs site. A repository README and other Markdown files, usually next to an app: Add i18n to your README and Markdown docs. Plain HTML pages (one file per locale) are described in HTML pages.
Framework shell strings (navbar, sidebar, theme) are translated in the same run, not by a separate pipeline. The framework guides in the table below say how each one does it: docusaurusCatalogDir for Docusaurus, docsOutput.vitepressThemeCatalog for VitePress, docs[].nextraDictionaryPath for Nextra, docsOutput.fumadocsUiCatalog for Fumadocs. Nextra _meta.ts and Fumadocs meta.json sidebar labels are collected automatically. Astro Starlight ships built-in UI strings for many locales, and optional overrides can use jsonPathTemplate on a docs[] block.
For PNG and other raster images embedded in markdown, see Images & Screenshots. translate-docs translates alt text only; it does not copy raster files.
For an optional language switcher block in README or docs, set docsOutput.style to "flat" - see Language switcher.
SVG files are translated via translate-svg when features.translateSVG is enabled - not through docs[] / contentPaths.
Arbitrary nested UI JSON bundles unrelated to a documentation framework's shell/theme strings belong in the JSON pipeline, not in docs[].
Each UI block includes its strings.json as glossary hints for documentation by default (uiGlossary, default true). translate-docs reuses those translations as hints in LLM prompts when matching terms appear in a segment. Set uiGlossary to false on a catalog that should stay out of document prompts. Optional glossary.userGlossary adds CSV overrides for product terms (shared with translate-ui and proofread-ui). Compact UI-label abbreviations used to fit narrow columns (for example Size → Tam) stay available for UI translation but are omitted from document glossary hints. Generate a starter CSV with glossary-generate, edit rows in the Translation Dashboard Glossary tab, or see Configuration — glossary and Glossary.
Per-locale model overrides
translate-docs and the docs step of sync resolve models per target locale: localeModels(locale) first when configured, then the provider's global translationModels chain. Use this when a specific language needs a different model than your default fallback list - for example, preferring Gemini for pt-BR documentation when the global chain struggles with Portuguese. See AI Models and Configuration - localeModels.
Which guide to read
| Your setup | Start here |
|---|---|
| Docusaurus site | init -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus |
| VitePress site | init -t ui-vitepress + vitepressThemeCatalog for theme - VitePress |
| Nextra site | init -t ui-nextra + nextraDictionaryPath for dictionary (sidebar _meta.ts is automatic) - Nextra |
| Fumadocs site | init -t ui-fumadocs + fumadocsUiCatalog for UI (sidebar meta.json is automatic) - Fumadocs |
| Astro Starlight | init -t ui-starlight - Astro Starlight |
| Plain HTML pages | init -t docs-plain-html - HTML pages |
| Flat documents (README, changelogs, etc.) | Add i18n to your README and Markdown docs — init -t docs-markdown or --with-readme. Layout: Output layouts, language switcher |
| Where translated files land | Output layouts |
Cross-page #anchor links | Anchor links |
Link and asset URL rewriting (regexAdjustments) | Link rewriting |
| Screenshots in docs | Images & Screenshots |
| Product terminology and UI/doc consistency | Configuration — glossary, Glossary |
translate-docs flags and cache | CLI options |
Step 1: Initialise for documentation
ai-i18n-tools init -t ui-docusaurus -P openaiFor Astro Starlight documentation sites:
ai-i18n-tools init -t ui-starlight -P cheaperinferenceFor VitePress documentation sites:
ai-i18n-tools init -t ui-vitepress -P anthropicSet docsOutput.vitepressThemeCatalog for nav/sidebar/footer strings - see VitePress integration.
For Nextra documentation sites:
ai-i18n-tools init -t ui-nextra -P geminiSet docs[].nextraDictionaryPath for theme dictionary strings - see Nextra integration. Sidebar _meta.ts labels are collected automatically.
For Fumadocs documentation sites:
ai-i18n-tools init -t ui-fumadocs -P groqSet docsOutput.fumadocsUiCatalog for UI overrides - see Fumadocs integration. Sidebar meta.json labels are collected automatically.
For plain Astro website UI (no Starlight):
ai-i18n-tools init -t ui-astro-website -P ollamaThat template enables UI extraction only. For page HTML translation, also set features.translateDocs and add a docs[] block (see Astro website pages (parse-and-replace)). The examples/astro-website config shows both pipelines together.
Edit the generated ai-i18n-tools.config.json:
providerandproviders—init -P <provider>scaffolds that preset; set its API key beforetranslate-docsorsync(Ollama needs no key). See Provider and API key, LLM providers, and AI Models.sourceLocale- source language (must matchdefaultLocaleindocusaurus.config.js).targetLocales- array of BCP-47 locale codes (e.g.["de", "fr", "es"]).cacheDir- shared SQLite cache directory for all pipelines (and default log directory for--write-logs).docs- array of documentation blocks. Each block has optionaldescription,contentPaths(string or array; file, directory, or glob),outputDir, optionaldocusaurusCatalogDir,docsOutput, optionalsegmentSplitting,translateFrontmatterFields,protectAttributes,protectKeys,targetLocales,addFrontmatter, etc.docs[].description- optional short note for maintainers. When set, it appears in thetranslate-docsheadline and instatussection headers.docs[].contentPaths- markdown/MDX/.astrosources (and optionaldocusaurusCatalogDirfor Docusaurus shell JSON).docs[].outputDir- translated output root for that block.docs[].docsOutput.style-"nested"(default),"flat","doc-system", or aliases"docusaurus"/"astro-starlight"/"vitepress"/"nextra"/"fumadocs"(see Output layouts).ui[].uiGlossary- whentrue(the default), that block'sstrings.jsonsupplies terminology hints for document segments (see Configuration —ui).glossary.userGlossary- optional CSV for fixed product-term translations; also used by UI pipelines and editable in the Glossary dashboard tab.
Primary vs supplementary: Focus on contentPaths for localised pages. Set docusaurusCatalogDir when you also need Docusaurus shell JSON from write-translations. Omit docusaurusCatalogDir if you only translate pages.
Step 2: Translate documents
ai-i18n-tools translate-docsThis translates all files in every docs[] block's contentPaths (and Docusaurus catalog JSON when docusaurusCatalogDir is set) to all effective documentation locales. Already-translated segments are served from the SQLite cache - only new or changed segments are sent to the LLM.
To translate a single locale:
ai-i18n-tools translate-docs --locale deTo check what needs translating:
ai-i18n-tools statusFor flags, cache behaviour, and batch prompt format, see CLI options.
Complex Markdown and failed quality checks
translate-docs checks that each translated segment preserves markdown structure (including emphasis parsed from the document) and that internal placeholder tokens restore cleanly. Paragraphs that stack many bold spans around `inline code`, nest backticks inside bold (for example template literals such as `fetch(\`/locales/${code}.json\`)`), or weave bold and code through one long sentence are fragile: some locales need different word order, which can change how ** and ` line up after translation and trigger CLI errors such as AST mismatch.
After restore, translate-docs also rejects segments where HTML tag placeholders were reused or dropped (so restored tags no longer match the source map) or where the model invented leftover double-brace tokens that were not in the source (for example a made-up glossary-style token). Pre-restore checks require the same multiset of {{…}} tokens and the same ordered subsequence of structural tokens ({{HTM_N}}, admonition markers); content tokens such as {{ILC_N}}, {{URL_N}}, and emphasis markers like {{SE}} may move with natural word order when each id / type count still matches. Those failures use the same model-fallback path as leftover official internal tokens.
If you hit that kind of validation failure, prefer simplifying the source-language text - split the paragraph, move an example into a fenced code block, or describe the same idea with fewer layered bold/code pairs - rather than expecting every model and locale to reproduce dense inline markup perfectly.
When the models tried for a segment fail with an AST mismatch, translate-docs can automatically split that segment into smaller parts (list midpoint first, then single list items or shorter paragraph chunks), retry each part from the first model, and rejoin the result under the original segment cache key. The same quality error three times stops the model list early; a different error keeps going. This is on by default (segmentSplitting.qualityRetrySplit); set it to false to stop after the model list ends. The run summary reports Quality split retries when this fallback runs.
To see which segments failed, how often, and the stored quality / error messages, use the Translation Dashboard's Failures tab (Translation Dashboard → Failures).