Astro integration
Use ai-i18n-tools with Astro in two common setups: Astro Starlight documentation sites and plain Astro marketing or app sites. Both use Documents (translate-docs) for page content; plain Astro sites often combine that with UI strings (extract / translate-ui) for t() strings in frontmatter and shared data.
See also UI strings, Documents, and the runnable examples below.
Astro Starlight
Use init -t ui-starlight and docsOutput.style: "astro-starlight" for Astro Starlight documentation sites. The preset is an alias for doc-system with an empty localeSubpath — translated pages land under src/content/docs/<locale>/ beside the source-locale tree. sourceLocale can be any language.
Quick start
ai-i18n-tools init -t ui-starlight -P cheaperinference
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync # or: ai-i18n-tools sync
pnpm dev # Starlight dev server (project-specific script)Page layout
English markdown and MDX live at the Starlight content root (typically src/content/docs/). Translated copies are written beside the source tree:
src/content/docs/quick-start.md → src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx → src/content/docs/fr/guide/setup.mdxConfigure one docs[] block:
{
"contentPaths": ["src/content/docs/"],
"outputDir": "src/content/docs",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/content/docs"
}
}Point contentPaths at the .md / .mdx files and directories written in sourceLocale. That language can be any language. Set docsRoot to the same folder Starlight uses as its content root.
Starlight UI overrides can use src/content/i18n/en.json with jsonPathTemplate in a separate docs[] block when needed — see Documents — initialise for documentation.
Starlight ships built-in UI strings for many locales (nav labels, search placeholder, table of contents, and so on). There is no separate shell/theme pipeline to configure — use translate-docs for page content only. For other frameworks, see Framework shell translation.
Explicit sidebar labels, the site title, and social[].label in astro.config.mjs are English literals this tool does not translate. Prefer slug entries so the label comes from the page's translated frontmatter (title). A group or an external link that needs its own wording uses Starlight's per-locale translations map (label for the default locale, translations['pt-BR'] for the others). social[].label has no translations field in the current Starlight schema; it stays as written. See Starlight sidebar and examples/astro-docs/astro.config.mjs, which uses slug entries.
Enable i18n in an existing site
First-time setup uses the prompt on Add i18n to a website or docs site. The checklist below is the same work by hand.
localesin the Starlight config, including arootentry when English should be unprefixed (labeland requiredlang).defaultLocale: 'root'when the default language is that root locale. OmitdefaultLocaleonly if Starlight's default already matches.- English pages stay in
src/content/docs/;translate-docswritessrc/content/docs/<locale>/. targetLocalesaligned with the non-root locale keys (watch case: Starlight directory keys are often lowercase, such aspt-br).
Example project
examples/astro-docs — English sources at src/content/docs/, committed translations under src/content/docs/<locale>/, RTL locale (ar), and glossary-driven translation. Run pnpm dev on port 3050.
Plain Astro (marketing and app sites)
For static Astro marketing or app sites (not Starlight), combine Astro built-in i18n routing with ai-i18n-tools. First-time setup uses the prompt on Add i18n to a website or docs site. The reference implementation is examples/astro-website: English at /, target locales at /{locale}/.
Most teams use a hybrid of two pipelines on the same page:
| Pipeline | Use for | Commands | Output |
|---|---|---|---|
| Page HTML | Headings, paragraphs, nav labels, inline arrays in the template body | translate-docs | src/pages/{locale}/index.astro per locale |
UI strings (t()) | Frontmatter data, tab labels, shared arrays | extract → translate-ui | public/locales/{locale}.json (source-language string as key) |
Quick start
ai-i18n-tools init -t ui-astro-website -P ollama
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm devScaffold UI extraction with init -t ui-astro-website -P ollama, then merge in a docs[] block when you also translate page HTML:
{
"features": {
"translateUIStrings": true,
"translateDocs": true
},
"ui": {
"sourceRoots": ["src/"],
"stringsJson": "public/locales/strings.json",
"flatOutputDir": "public/locales/"
},
"docs": [{
"contentPaths": ["src/pages/index.astro"],
"outputDir": "src/pages",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/pages"
},
"addFrontmatter": false
}]
}Keep three lists aligned when you add or remove a language: targetLocales in ai-i18n-tools.config.json, i18n.locales in astro.config.mjs (Astro uses lowercase route codes such as pt-br), and ui-languages.json (via generate-ui-languages). Flat bundle filenames use config casing (pt-BR.json); map Astro's pt-br route to that file via your manifest code field.
Resolve t('…') at build time by looking up the source-language literal as the key — see examples/astro-website/src/i18n/t.ts. sourceLocale can be any language. The example uses English. You do not need ai-i18n-tools/runtime or i18next for a static site unless you add client islands that switch language after load.
Example project
examples/astro-website — hybrid landing page with HTML via translate-docs and screenshot tab labels via t() + translate-ui.
Example projects
| Project | Use case | Port |
|---|---|---|
| examples/astro-docs | Starlight documentation | 3050 |
| examples/astro-website | Plain Astro marketing site (HTML + t() hybrid) | (see README) |
Compare examples/astro-docs with examples/docusaurus-docs — similar tutorial content, Docusaurus output style instead of Starlight.