Skip to content

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 ​

bash
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:

text
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.mdx

Configure one docs[] block:

json
{
  "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.

  • locales in the Starlight config, including a root entry when English should be unprefixed (label and required lang).
  • defaultLocale: 'root' when the default language is that root locale. Omit defaultLocale only if Starlight's default already matches.
  • English pages stay in src/content/docs/; translate-docs writes src/content/docs/<locale>/.
  • targetLocales aligned with the non-root locale keys (watch case: Starlight directory keys are often lowercase, such as pt-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:

PipelineUse forCommandsOutput
Page HTMLHeadings, paragraphs, nav labels, inline arrays in the template bodytranslate-docssrc/pages/{locale}/index.astro per locale
UI strings (t())Frontmatter data, tab labels, shared arraysextract → translate-uipublic/locales/{locale}.json (source-language string as key)

Quick start ​

bash
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 dev

Scaffold UI extraction with init -t ui-astro-website -P ollama, then merge in a docs[] block when you also translate page HTML:

json
{
  "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 ​

ProjectUse casePort
examples/astro-docsStarlight documentation3050
examples/astro-websitePlain 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.

Released under the MIT License.