Skip to content

Quick start ​

This page guides a single-language project to its first translated files. It is for a JS/TS app, a Python app, a .NET app, a website or documentation site, or a repository README and other Markdown files. It assumes:

  • Node.js >=22.16.0, or the standalone executable for a Python or .NET project.
  • An API key for an LLM provider, or a local Ollama install.
  • The project is in version control, so you can review what the tool writes.

Two things differ between projects: how the tool finds your text, and how your app loads the result. Pick your path below sends you to the right guide for that.

Runnable examples ​

Prefer to look at a finished project first? Copy one without cloning the repository:

bash
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync

Replace console-app with any other Node.js example. Python and .NET examples have no package.json; copy them the same way. The four Python examples are also in ai-i18n-tools-python-examples.zip on the GitHub Release, and the two .NET examples are in ai-i18n-tools-dotnet-examples.zip. The full list, with what each one shows, is on the Examples page.

Install ​

bash
pnpm add -D ai-i18n-tools

npm install --save-dev ai-i18n-tools and yarn add --dev ai-i18n-tools work too. Python and .NET projects install the standalone executable and need no Node.js. Linux and macOS: curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash. Windows PowerShell: irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex. Other install options: Installation.

Provider and API key ​

Every command that calls an LLM (translate-ui, translate-docs, translate-json, translate-svg, and sync) needs both of these:

  1. At least one provider in ai-i18n-tools.config.json: a providers.<name> block with translationModels, and a top-level provider key when more than one provider is configured. init -P <provider> scaffolds that preset. To add providers, see LLM providers. To choose the model list, see AI Models.
  2. The matching API key in your environment, or in .env / .env.local next to ai-i18n-tools.config.json when no provider API key is already set. Each built-in preset reads a named variable from the preset table, for example OPENROUTER_API_KEY with -P openrouter or OPENAI_API_KEY with -P openai. Ollama uses a local endpoint and needs no key.
bash
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

extract, status, and other commands that do not call the LLM need neither. More on environment files and PATH: Installation.

Pick your path ​

Find what you have, run the commands in its block, then continue in the linked guide.

A JS/TS app ​

Your buttons and messages are still plain text in the source, so the tool has nothing to find yet. They must be wrapped in t() first, and the app needs a small i18next setup file.

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --apply

Then follow Add i18n to a JS/TS app. It covers the wrapping step, with an agent prompt, before extract and translate-ui.

A Python app ​

bash
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --apply

Then follow Add i18n to a Python app.

A Django app, Flask with Flask-Babel catalogs, or an app that already calls gettext keeps those calls. Scaffold with ui-python-django, ui-python-flask, or ui-python-gettext instead, then follow Add i18n to a Django / Python gettext app.

A .NET app ​

bash
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --apply

Then follow Add i18n to a .NET app. An app that already uses ResourceManager or IStringLocalizer uses ui-dotnet-resx instead, then Add i18n to a .NET ResourceManager app. migrate-dotnet-i18n rewrites T($"…") into numbered {0} calls. --wrap audits unmarked XAML and C# labels. The report lists named resx keys, such as Resources.LoginButton, as suggestions and does not edit those lines.

A website or documentation site ​

Pick the template for your framework:

Your siteTemplate
Astro Starlightui-starlight
Docusaurusui-docusaurus
VitePressui-vitepress
Nextraui-nextra
Fumadocsui-fumadocs
Plain Astro websiteui-astro-website
Plain HTML pagesui-plain-html or docs-plain-html
bash
ai-i18n-tools init -t ui-vitepress -P openrouter

Then follow Add i18n to a website or docs site. Its agent prompt enables the framework's i18n routing. You run sync after reviewing that work.

A README or Markdown docs ​

Most repositories want this together with the app: the default ui-markdown template already includes a flat README block. For any other template, add --with-readme. A repository with only Markdown uses docs-markdown.

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouter

Then follow Add i18n to your README and Markdown docs. Paste the language-list marker into README.md before sync. The app path, when you have one, is still Add i18n to a JS/TS app, Add i18n to a Python app, or Add i18n to a .NET app.

Something else ​

The full template list, with every init option, is in the CLI setup reference.

Run and check ​

When your project is ready:

bash
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools status

doctor checks that the config, paths, providers, and environment are ready. It also verifies model ids with the provider unless you pass --local. sync runs every step your config enables, in order. status shows what is translated per locale. A first run on a project the tool cannot see text in finishes without error and writes nothing useful, so if status shows no strings, go back to the guide for your path.

suggest-models ranks the active provider's chat models from published benchmarks. suggest-models --apply replaces translationModels and leaves uiModels and localeModels alone. The same ranking is on the dashboard Models tab. How the ranking works, and why the list holds more than one model: AI Models. Command reference: suggest-models.

Keep it translated ​

Re-run sync whenever source text changes. A SQLite cache means only new or changed text goes to the model, so reruns are cheap. Running sync in CI keeps translations from drifting. ai-i18n-tools dashboard opens the Translation Dashboard to review and edit cached translations.

With the package installed locally, scripts resolve ai-i18n-tools from node_modules/.bin without extra shell setup. For an interactive shell, configure PATH first: see Using the CLI.

json
{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:status": "ai-i18n-tools status",
  "i18n:statistics": "ai-i18n-tools statistics",
  "i18n:dashboard": "ai-i18n-tools dashboard",
  "i18n:cleanup": "ai-i18n-tools cleanup"
}

Prefer sync over chaining the individual translate scripts. Use the single-step scripts only when you need one step in isolation.

To show the CLI output and dashboard in another language, pass -L <code> or set AI_I18N_LANG: see Tool UI language.

Translating more than one kind of content, such as app strings and a docs site together? See Combining pipelines.

Next: the guide for your path under Pick your path.

Released under the MIT License.