What is ai-i18n-tools?

You have an app, a website, a documentation site, or a repository README in one language, and you want more languages. That language is sourceLocale, and it can be any language. English is a common example in these guides. ai-i18n-tools finds the text, translates it with the models on the LLM provider you choose, and writes the files your project already loads. It caches every result, so reruns only send new or changed text to the model.

What you do and what the tool does

You	The tool
Pick the languages, a provider, and the models to try	Extracts text, translates it, validates the result, and writes catalogs or pages
Make user-facing text visible to the tool: t() calls in app code, your framework's own i18n for a site, or a language-list marker in a README	Caches translations and reuses them on every rerun
Wire the result into the app, the site's routing, or the README's language row	Shows progress and lets you review translations in the dashboard

The tool does not rewrite your source. Coding-agent prompts are provided for the wrapping step. It does not install i18next or your site framework's i18n, and it does not build your language switcher, although runtime helpers are provided for that.

Where do I start?

The walkthroughs are grouped in Add i18n to your project, with the shared setup and a page for each kind of project. Pick a row:

You have	Start here
A JS/TS app (React, Next.js, Node, CLI) with plain text in the source	Add i18n to a JS/TS app
A Python app (Streamlit, FastAPI, Flask, Django, gettext, desktop)	Add i18n to a Python app
A website or documentation site (VitePress, Docusaurus, Starlight, Nextra, Fumadocs, Astro, plain HTML)	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
Standalone nested JSON locale files	JSON
SVG diagrams with text labels	SVG translation
Intlayer dictionaries (move off Intlayer)	Migrating from Intlayer
Intlayer dictionaries (keep Intlayer, translate in place)	Translating Intlayer in place

How it works

1. Install the CLI and set your provider's API key: Installation.
2. Run init to write ai-i18n-tools.config.json: Quick start.
3. Prepare the project: wrap strings in t(), enable your site framework's i18n, or add the language-list marker to a README.
4. Run sync. It extracts text, translates what is new, and writes the output.
5. Load the output in your app or site, add a language switcher, and rerun sync when the source changes.

Translation modes

Under the hood, the tool runs four pipelines. Your config enables the ones you need, and sync runs them in order.

• UI strings — Extract t("…") and _() calls from JS/TS and Python source (and similar markers, including GNU gettext) and write flat per-locale JSON or .po / .mo catalogs. Commands: extract, translate-ui. Guide: UI strings. Python: Python applications.
• Documents — Translate Markdown, MDX, and .astro pages listed in docs[].contentPaths. Works with VitePress, Starlight, Docusaurus, Nextra, Fumadocs, Astro, and other static doc sites, and with a repository README (docsOutput.style of flat). Command: translate-docs. Guides: Documents and Add i18n to your README and Markdown docs.
• JSON — Translate nested JSON locale bundles (theme labels, i18n overrides, app copy not in source) defined in top-level json[]. Command: translate-json. Guide: JSON.
• SVG — Translate visible text inside SVG illustrations (<text>, <title>, <desc>) and write one output file per locale. Separate from document translation. Command: translate-svg. Guide: SVG translation.

Many projects combine modes. The common pair is UI strings plus the repository README. A docs site such as VitePress is the other frequent pair. See Combining pipelines and Add i18n to your README and Markdown docs.

Examples

The repository ships runnable example projects under examples/, each with its own config, committed locale outputs, and README. Explore translated files without an API key; re-running translation needs a provider key.

If you have	Example
A JS/TS app	console-app, nextjs-app
A repository README next to an app	console-app, nextjs-app
A Python app	python-streamlit, python-fastapi, python-gettext
A docs site	docusaurus-docs, vitepress-docs, astro-docs
A website or plain HTML	astro-website, plain-html

See Examples for the full list and npx degit copy commands.

Next steps

1. Installation — install the npm package, or download the standalone executable for a Python project, and set your provider API key.
2. Quick start — scaffold a config and run your first translation.
3. LLM providers — choose a provider, API key, and -P override.
4. AI Models — rank a shortlist with suggest-models or the dashboard Models tab, and keep several models so a failed translation can try the next one.