Add i18n to your project
This section is the set of walkthroughs for a project that speaks one language today. Start here. Each page below takes one kind of project from setup to the first translated files. Get started covers what the tool is, install options, and providers and models. You can open a walkthrough without reading those pages first.
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, checks the result, and writes catalogs or pages |
Make the text visible: t() in app code, your site framework's i18n, or a language-list marker in a README | Caches every translation and reuses it on the next run |
| Load the files and check one language | Shows progress, and lets you review wording in the Translation Dashboard |
The walkthroughs say which source edits are yours. Coding-agent prompts are included where those edits are mechanical. The CLI writes the catalogs and the translated files. It does not install i18next or your site framework's i18n.
Shared setup
Every walkthrough follows the same order. The page you pick fills in the details.
- Install the CLI and set your provider's API key. Ollama needs no key. Installation and Provider and API key.
- Run
initwith the template that page names. This writesai-i18n-tools.config.json. - Prepare the project so the tool can see the text.
- Run
ai-i18n-tools sync, thenai-i18n-tools status. - Load the output, check one target language, and rerun
syncwhen the source changes. The cache sends only new or changed text to the model.
Pages in this section
| You have | Page | What that page covers |
|---|---|---|
| A JS/TS app (React, Next.js, Node, CLI) whose buttons and messages are still plain text | Add i18n to a JS/TS app | Install i18next, add the bootstrap, wrap literals in t(), then extract and translate-ui |
| A Python app (Streamlit, FastAPI, Flask, Django, gettext) | Add i18n to a Python app | Wrap t() or _(), or keep GNU gettext. The CLI can run from a standalone executable with no Node.js install |
| A documentation or marketing site (VitePress, Starlight, Docusaurus, Nextra, Fumadocs, Astro, plain HTML) | Add i18n to a website or docs site | Enable the framework's own language routes, then translate pages and theme labels |
| A repository README and other Markdown files, usually next to an app | Add i18n to your README and Markdown docs | One file per language (translated-docs/README.de.md) and a language row in the README. init --with-readme adds that block to any template |
| More than one of the above in one repository | Combining pipelines | One config and one sync. The usual pair is app UI strings plus the README |
| Intlayer dictionaries, and you want to keep Intlayer | Translating Intlayer in place | translate-intlayer fills missing and stale leaves inside *.content.ts |
| Intlayer dictionaries, and you are moving off Intlayer | Migrating from Intlayer | migrate-intlayer seeds catalogs from the dictionaries and rewrites safe call sites to t() |
An app that also has a README uses the app page and the README page together. A site that also has a README uses the website page, and init … --with-readme for the README block.
Where to go deeper
The walkthroughs stop once the first language is wired. The reference pages take over from there:
- UI strings, Documents, JSON, and SVG for one pipeline at a time.
- Integrations for framework shell strings (navigation, sidebar, theme).
- Quick start for the command list and recommended
package.jsonscripts. - LLM providers for presets and API keys.
- AI Models for the ranked shortlist and the fallback chain.