ai-i18n-tools
English (UK) · Deutsch · Español · Français · हिन्दी · 日本語 · 한국어 · Português (Brasil) · 简体中文 · 繁體中文
npm version npm downloads Node.js License: MIT CI
Linux x64 Linux arm64 macOS arm64 macOS x64 Windows x64
Translate your app, website, and docs with the models you choose on any LLM provider. One config, cached reruns.
CLI and toolkit that adds languages to JavaScript/TypeScript apps, Python apps, and documentation sites. The language you start from is sourceLocale, and it can be any language. It finds the text, translates it, and writes the files your project loads. Built-in presets cover OpenAI, Anthropic, Gemini, OpenRouter, Ollama, and any OpenAI-compatible API. Switch provider or model per project or per locale.
Works with VitePress, Starlight, Docusaurus, Nextra, Fumadocs, Astro, plain Markdown (a repository README and other .md files), and plain HTML. Python apps use t() / _() or GNU gettext (Streamlit, FastAPI, Flask, Django, and desktop toolkits). Keeps your existing i18next catalogs (namespace JSON or t() source strings). Works with Intlayer in two ways: keep Intlayer and fill its dictionaries with translate-intlayer, or move to source-string t() calls with migrate-intlayer. Intlayer stays a good fit for typed content dictionaries and translation management systems.
Features
| UI strings | Extract t("…") / _() from JS/TS/Astro and Python, or data-i18n* in one HTML file → flat per-locale JSON or GNU gettext |
| Documents | Translate Markdown, MDX, .astro, and HTML pages (one file per locale) |
| JSON | Translate nested locale bundles when copy lives outside t() calls |
| SVG | Translate illustrated SVG labels via translate-svg |
| Smart cache | Shared SQLite cache — only new or changed segments hit the model |
One sync | Runs extract → UI → SVG → docs → JSON in the right order from one config |
| Python | Standalone executable on each GitHub Release — the CLI runs with no Node.js install |
| Ranked models | suggest-models ranks the active provider's chat models and can write translationModels |
Where do I start?
| 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, desktop, scripts) | Add i18n to a Python app |
| A Django app, Flask-Babel catalogs, or an app that already uses GNU gettext | Add i18n to a Django / Python gettext app |
| A website or docs site (VitePress, Docusaurus, Starlight, Nextra, Fumadocs, Astro, plain HTML) | Add i18n to a website or docs site |
| A repository README and other Markdown files (with or without an app) | Add i18n to your README and Markdown docs |
Code that already calls t() or _() | UI strings |
| Standalone nested JSON locale files | JSON |
| SVG diagrams with text labels | SVG translation |
| Intlayer dictionaries (keep Intlayer, or move to source-string calls) | Translating Intlayer in place · Migrating from Intlayer to source-string calls |
See What is ai-i18n-tools? for how the pipelines fit together.
Install
ESM-only. Requires Node.js >=22.16.0.
pnpm add -D ai-i18n-tools
# or: npm install --save-dev ai-i18n-tools
Set an API key for the provider you pass to init (Ollama needs none):
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# or, for OpenAI: export OPENAI_API_KEY=sk-your-key-here
Configure the bare ai-i18n-tools command (direnv, PATH, package.json scripts, or npx) — see Installation.
Python, 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
The installer picks the executable for this machine, checks SHA256SUMS.txt, installs the command as ai-i18n-tools, and adds it to PATH. The binaries are not notarized or Authenticode-signed. Manual download steps: Standalone executables.
The four Python examples are in the repository and in ai-i18n-tools-python-examples.zip on the release. They are not inside the npm tarball or the executable.
Quick start
Scaffold the config for what you have, then follow the guide for your path:
| You have | Scaffold | Then follow |
|---|---|---|
| A JS/TS app | ai-i18n-tools init -P openrouter | Add i18n to a JS/TS app |
| A Python app | ai-i18n-tools init -t ui-python -P openrouter | Add i18n to a Python app |
| A Django or GNU gettext app | ai-i18n-tools init -t ui-python-django -P openrouter (or ui-python-gettext, ui-python-flask) | Add i18n to a Django / Python gettext app |
| A website or docs site | ai-i18n-tools init -t ui-vitepress -P openrouter (swap the template for your framework) | Add i18n to a website or docs site |
| A README, with or without an app | ai-i18n-tools init -P openrouter (JS/TS app + README) or init -t docs-markdown | Add i18n to your README and Markdown docs |
When the project is ready, run ai-i18n-tools sync, then ai-i18n-tools status to see what was translated.
A JS/TS app must wrap its text in t() first. Run on plain text, sync finishes without error and writes nothing useful. Your site framework must also have its own i18n routing enabled before sync.
Templates for websites: ui-starlight, ui-docusaurus, ui-vitepress, ui-nextra, ui-fumadocs, ui-astro-website, and ui-plain-html or docs-plain-html. README and Markdown only: docs-markdown. Add --with-readme to any other template to include the README block. Python gettext apps: ui-python-django, ui-python-flask, ui-python-gettext. Nested i18next JSON: ui-json-bundles. Full list: CLI setup reference.
suggest-models ranks the active provider's chat models from published benchmarks, and suggest-models --apply replaces translationModels. The same ranking is on the Models tab. Guide: AI Models. Command reference: suggest-models.
Prefer sync over chaining individual translate commands. Full walkthrough: Quick start. More than one kind of content in one project: Combining pipelines.
Documentation
- Documentation site — guides, integrations, and reference
- Installation · Quick start · LLM providers · AI Models
- UI strings · Plain HTML · Python · Documents · HTML pages · JSON · SVG
- Intlayer — translate dictionaries in place · move to source-string calls
- Integrations — VitePress, Nextra, Fumadocs, Docusaurus, Astro, and Python
- Add i18n to your project — JS/TS app · Python app · Django / gettext app · website or docs site · README and Markdown docs · Combining pipelines
- CLI reference · Configuration · Runtime helpers
- Examples — runnable demos (
npx degit …) - AI Agent Context — concise prompt /
AGENTS.mdentrypoint for consumer projects - Portable Agent Skills — one install, then a slash command per workflow:
npx skills add wsj-br/ai-i18n-tools --all -y(Node.js 22.20+); install guide
Contributing
Issues and pull requests are welcome. Maintainer workflows for this repository: AGENTS.md and dev/DEVEL.md.
License
MIT — see LICENSE.
Copyright © 2026 Waldemar Scudeller Jr.
Product names and icons belong to their respective owners and are used for identification purposes only. This software is not affiliated with or endorsed by those brands.
Note on UI and documentation translations: All interface and documentation languages except English (UK) were translated with AI using this package (ai-i18n-tools); the wording may be imprecise or contain errors.