Add i18n to a website or docs site

This page is for a documentation site (Markdown or MDX) or a marketing or static site (an Astro website or plain HTML) in one language. The tool translates your page content with the models on your LLM provider and writes one localized copy per language. Your site framework serves those copies and provides the language switcher.

For an app whose UI strings live in t() calls, use Add i18n to a JS/TS app or Add i18n to a Python app instead.

What do you have?

Your site	Init template	Start here
Astro Starlight or plain Astro	ui-starlight / hybrid UI strings	Astro
Docusaurus	ui-docusaurus	Docusaurus
VitePress	ui-vitepress	VitePress
Nextra 4 (Next.js App Router)	ui-nextra	Nextra
Fumadocs 4 (Next.js App Router)	ui-fumadocs	Fumadocs
Plain HTML pages	ui-plain-html or docs-plain-html	Plain HTML apps
No site framework, just a README and Markdown files	docs-markdown, or any template plus --with-readme	Add i18n to your README and Markdown docs

Agent prompts

• Astro Starlight: notes only. Astro t() files: JS/TS prompt (skip i18next).
• Docusaurus: notes only (<Translate> is Docusaurus's own API).
• VitePress: Theme catalog prompt.
• Nextra: Dictionary prompt and hybrid t() prompt.
• Fumadocs: UI catalog prompt.
• README and Markdown files: README prompt.

Steps

The same shape works for every framework; the details live in the framework guide linked above.

1. Install the CLI and set the API key: Installation, Provider and API key.
2. Scaffold: ai-i18n-tools init -t <template> -P <provider>.
3. Set sourceLocale, targetLocales, and docs[].contentPaths (the pages and folders written in your source language). sourceLocale can be any language. The framework guide shows the right docsOutput.style.
4. Enable your framework's own i18n so it serves and links the localized pages. Each guide has an "Enable i18n in an existing site" section: VitePress, Docusaurus, Nextra, Fumadocs, Astro.
5. Run ai-i18n-tools sync (or translate-docs), then build the site.
6. Check a localized route in the browser. The framework's own locale dropdown is the switcher. For a flat markdown file such as a README, add a link row with languageListBlock.

What gets translated

Page bodies always go through the Documents pipeline. Framework chrome (navigation, sidebar, theme labels) is handled in the same run where the framework supports it, not through the separate JSON pipeline.

Framework	Shell and theme strings	How
Docusaurus	write-translations catalog ({ message, description })	docs[].docusaurusCatalogDir plus translate-docs
VitePress	Theme, nav, and sidebar catalog	docsOutput.vitepressThemeCatalog plus translate-docs
Nextra	_meta.ts sidebar labels	Automatic with style: "nextra"
Nextra	Theme dictionary .ts	docs[].nextraDictionaryPath
Fumadocs	meta.json sidebar labels	Automatic with style: "fumadocs"
Fumadocs	UI overrides catalog	docsOutput.fumadocsUiCatalog
Astro Starlight	Built-in UI strings in many locales	Pages only

Images and screenshots are not translated by translate-docs. For locale-specific files, see Images and screenshots.

Plain HTML

Two options, depending on how the page should behave:

• One page that switches language in the browser: mark the text with data-i18n* attributes and use the UI strings runtime (ui-plain-html). See Plain HTML apps.
• One translated HTML file per locale: use the Documents pipeline (docs-plain-html). See HTML pages.

A file belongs to one path.

Not your case?

• App UI strings: Add i18n to a JS/TS app or Add i18n to a Python app.
• A repository README next to the site, or Markdown files and no site framework: Add i18n to your README and Markdown docs. init … --with-readme adds that block beside a site template.
• Standalone nested locale JSON: JSON.
• Translating both a site and app strings: Combining pipelines.

Reference for the shared options and per-framework differences: Integrations.