kaeris-mcp
Use KAERIS MCP to audit, fix, and translate app locale files across many i18n formats and 46 languages.
Discover a repo’s locale files, base/target languages, and framework using
kaeris_scan_repo(local, no API cost).Check locale completeness and health with
kaeris_status, including missing/extra keys and placeholder mismatches.List exact missing or broken keys for one target language with
kaeris_list_missing_keys.List all supported target languages with
kaeris_list_languages.Translate inline strings with QA flags for placeholder loss and UI overflow, optionally back-translating with
verify=True.Translate locale files on disk in 13 formats, including incremental
only_newmode viakaeris.lock.Bootstrap a brand-new target locale from a source file with
kaeris_add_language.Use local-only audit tools freely; translation tools call the KAERIS API and work with free tier, API key, or OpenRouter key.
Supports scanning and translating Android string resources (strings.xml) and locale files. Includes tools for detecting Android projects and checking translation status.
Supports scanning and translating Flutter ARB localization files. Includes tools for detecting Flutter projects and managing translations.
Supports scanning and translating i18next JSON locale files. Includes tools for detecting i18next projects and incremental translation.
Supports scanning and translating iOS .strings files. Includes tools for detecting iOS projects and checking translation completeness.
Supports translation of XML locale files (e.g., Android strings.xml). Includes tools for translating with structure preservation.
Supports translation of YAML locale files. Includes tools for translating content with placeholder safety.
KAERIS MCP server
Lets Claude Desktop, Claude Code, Cursor or any MCP client check your app's locale files and translate them into 46 languages.
pip install kaeris-mcp && claude mcp add kaeris-i18n kaeris-mcpThree tools work offline with no key: find the locale files in a repo, report missing keys and broken placeholders per language, list the exact keys to fix.
Translation keeps placeholders and markup, translates only new keys with
only_new, and withverify=Truetranslates each line back to flag a changed meaning.13 formats: JSON, YAML,
.strings,.xcstrings,.po, ARB, Android XML, CSV, XLIFF,.properties,.resx, Fluent.ftl, Markdown.Same engine and
kaeris.lockas the CLI, so an agent, a teammate and CI agree on what is already translated.
Plans. No key needed to try it. Free API key: 50k characters per file, 8 languages per run. Pro $19/month with 12M characters, Team/API $79/month with 60M, Lifetime $79 once with your own OpenRouter key. See kaeris.dev/pricing.
Docs · Pricing · Discussions · Status · Security
Tools
Tool | What it does | Calls the API? |
| Discover a repo's i18n setup: locale files found, base language, target languages, framework guess (i18next/next-intl/vue-i18n/Flutter/Android/iOS/gettext/generic) | No |
| Completeness/health per target locale — missing keys, extra keys, placeholder mismatches, plus the quality detectors that gate a merge in CI: number drift, lost inline tags, broken entities/escapes, ICU/CLDR plural gaps (same verdict as | No |
| The exact missing/broken keys (with source text) for one target locale, so an agent knows exactly what to fix | No |
| List all supported target languages | Yes, free (no quota) |
| Translate inline strings → per-language results, with QA (placeholder-loss & UI-overflow flags; | Yes |
| Translate a file on disk (JSON/YAML/.strings/.xcstrings/.po/ARB/XML/CSV/XLIFF/.properties/.resx/.ftl/Markdown), optional incremental — reproducible via | Yes |
| Bootstrap a brand-new target locale by translating the whole source file into it | Yes |
The first three tools are local-only (no network call, no cost), and kaeris_list_languages is one
free API call that counts toward no limit — an agent can use all four freely to audit and
understand a repo's i18n before deciding what (if anything) to translate.
Related MCP server: i1n
Reproducible by design
kaeris_translate_file with only_new=True keeps a kaeris.lock next to your source file —
the same lock the CLI writes, so an agent and a human sharing a repo stay in sync. It records a
hash of every source string plus the settings that produced it: tone, glossary, app context, and the
model. That means:
Edit one string — only that string is re-translated; everything else stays byte-for-byte.
Change tone, glossary or context — the whole locale is re-translated, never a mix of old and new.
Change plan — every tier runs the same model (GPT-6 Luna), so upgrading does not force a re-translation. The lock records the model regardless: the day we change it, the locale is rebuilt in full instead of quietly ending up the work of two models.
Commit kaeris.lock alongside your source file so the agent, your teammates and CI all agree on
what is already done.
Install
pip install kaeris-mcpOr run it with Docker
docker build -t kaeris-mcp .
docker run -i --rm -v "$PWD:/work" -w /work kaeris-mcpThe server speaks JSON-RPC over stdin/stdout, so there is no port to expose —
-i is what keeps the conversation open. Mount your project at /work and the
repo-aware tools (scan_repo, status, list_missing_keys) read it directly;
pass -e KAERIS_API_KEY=… to use your KAERIS key.
Configure your client
Claude Desktop — add to claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"kaeris-i18n": {
"command": "kaeris-mcp",
"env": {
"KAERIS_API_KEY": "kaerisp_optional"
}
}
}
}Cursor — Settings → MCP → Add, or .cursor/mcp.json:
{ "mcpServers": { "kaeris-i18n": { "command": "kaeris-mcp" } } }Claude Code — one command:
claude mcp add kaeris-i18n kaeris-mcpRestart the client; the KAERIS tools appear automatically.
Auth & tiers (all optional)
Env var | Purpose |
| Your KAERIS key, e.g. the free API key from kaeris.dev/docs/key (50k chars/file, no account) — without one, the free 10k-char demo is used |
| OpenRouter key for Lifetime/BYOK — no monthly volume cap |
| Override the API base URL |
| Set to |
| Set to |
No key is required to try it — the free demo works out of the box.
Example prompts
"Translate the strings in
locales/en.jsoninto German, Ukrainian and Japanese.""Add French and Spanish translations for these buttons: Save, Cancel, Delete."
"Only translate the new keys I added to en.json — don't redo the whole file."
"Check this repo's i18n and tell me what's missing or broken." (scans, then reports status — no API call)
"We don't have Ukrainian yet — add it." (bootstraps a new locale via translation)
License
MIT
Available Tools
7 toolskaeris_add_languageA
Bootstrap a BRAND-NEW target locale by translating the entire source file into it and writing the result. Use this when kaeris_scan_repo/kaeris_status show a language with no locale file at all yet (in "missing_files").
This CALLS THE TRANSLATION API (same as kaeris_translate_file) — unlike kaeris_scan_repo/kaeris_status/kaeris_list_missing_keys, which are local-only and free. For an EXISTING locale that's just missing a few keys, prefer kaeris_translate_file(..., only_new=True) so you don't re-translate the whole file.
Args: source: path to the base-language locale file, e.g. "locales/en.json". lang: the new target language code to create, e.g. "de". out: output directory (default: source file's own directory). tone: "formal" or "casual" to steer register; "" (default) is neutral. icu: True if the source uses ICU MessageFormat (plurals/select), so the model preserves the syntax instead of translating it. keep: optional list of terms to NEVER translate (brand/product names). context: one line about what the app IS, e.g. "a mobile bank for teenagers" or "a wildlife documentary app". The model uses it to pick the right sense of ambiguous strings — "Bank" becomes Ufer in the second and Bank in the first. You are reading the repo, so you know this: pass it. Max 300 chars. api_key / openrouter_key: optional auth overrides (else free tier or env vars).
Returns: { "written": ["/.json"], "lang": "de", "languages": ["de"] }
Inputs: lang (required), source (required), icu, out, +5 more.
kaeris_list_languagesA
List every target language KAERIS can translate into.
Returns a mapping of language code → English name (e.g. {"es": "Spanish", ...}). Use the codes with kaeris_translate / kaeris_translate_file.
Inputs: no named parameters.
kaeris_list_missing_keysA
The exact keys missing or placeholder-broken in ONE target locale, with their source-language text, so an agent knows exactly what to translate/fix. Every supported format works (JSON offline; others via the backend /api/parse, no cost) — use kaeris_add_language or kaeris_translate to actually fill them in.
Args: source: path to the base-language locale file, e.g. "locales/en.json" or "app_en.arb". lang: the target language code to inspect, e.g. "de". out: directory containing the target locale file (default: source's own directory; expected at "/", e.g. de.json / de.arb).
Returns: { "lang": "de", "missing_file": bool, "missing": ["<dotted.key>", ...], # present in source, absent in target "missing_values": {"<dotted.key>": "", ...}, "extra": ["<dotted.key>", ...], # present in target, absent in source "placeholder_issues": [{"key","missing","added"}, ...] }
Inputs: lang (required), source (required), out.
kaeris_scan_repoA
Discover a repo's i18n setup: which locale files exist, what the base (source) language and target languages are, and which framework/convention is in use. Purely local — reads the filesystem, makes no API call.
Use this FIRST when asked to "look at/audit/fix this repo's i18n" and you don't already know the source file — it tells you where to point kaeris_status / kaeris_list_missing_keys / kaeris_add_language.
Supports i18next/react-i18next (locales//.json), next-intl (messages/.json), vue-i18n (src/locales/.json), Flutter ARB (lib/l10n/.arb), Android (res/values[-]/strings.xml), iOS (.lproj/Localizable.strings), gettext (locale//LC_MESSAGES/*.po), XLIFF (.xliff/.xlf), Java/Spring .properties, .NET RESX, plus plain .json/.yaml/.csv files anywhere else. Skips node_modules, .git, build/dist output and other noise; bounded so it's safe on large repos.
Args: path: directory to scan (default: current directory).
Returns: { "root": "", "locale_files": ["locales/en.json", "locales/de.json", ...], "base_lang": "en", # best guess, or null if none found/ambiguous "target_langs": ["de", "fr"], # languages present other than base_lang "framework": "i18next", # best guess, or null if unrecognized "file_count": 2 }
Inputs: path.
kaeris_statusA
Completeness/health check for every target locale against a source file — the "i18n firewall". Works for EVERY supported format: JSON is checked fully offline; other formats (.arb/.strings/.po/.xml/.ftl/…) are parsed by the backend /api/parse endpoint (no translation, no cost).
For each target language reports missing keys, extra/stale keys, and placeholder mismatches (e.g. "Hello {name}" -> "Bonjour" loses {name}, or "{name}" -> "{nom}" which crashes str.format()/ICU at runtime). Use this to find out what's broken before deciding whether to call kaeris_list_missing_keys (existing locale, some keys missing/broken) or kaeris_add_language (locale doesn't exist yet at all).
Args: source: path to the base-language locale file, e.g. "locales/en.json" or "lib/l10n/app_en.arb" (typically kaeris_scan_repo's base_lang file). langs: target language codes to check, e.g. ["de", "fr"]. If omitted, falls back to kaeris.json's "langs" if present, else auto-discovers sibling files next to the source. out: directory containing the target locale files (default: source's own directory; each target is expected at "/", e.g. de.json for en.json, de.arb for en.arb).
Returns: { "ok": bool, "missing": {lang: [keys]}, "extra": {lang: [keys]}, "placeholder_issues": [{"lang","key","missing","added"}, ...], "missing_files": [lang, ...], # target language has no locale file at all "source", "out_dir", "langs" }
Inputs: source (required), out, langs.
kaeris_translateA
Translate a set of UI strings into one or more languages.
Format-aware and placeholder-safe: values like "Hello, {name}" keep their placeholders intact. Non-string values are passed through unchanged.
Includes Translation QA so you can trust the output: it flags translations that dropped a placeholder or that grew long enough to risk overflowing the UI. With verify=True it also back-translates each result into back_lang so you can check the meaning is right even in a language you can't read.
Args: strings: key → source-text pairs, e.g. {"greeting": "Hello", "save": "Save"}. target_languages: language codes from kaeris_list_languages, e.g. ["es", "fr", "ja"]. keep: optional list of terms to NEVER translate — kept verbatim in every language (brand/product names), e.g. ["KAERIS", "GitHub"]. context: one line about what the app IS, e.g. "a mobile bank for teenagers" or "a wildlife documentary app". The model uses it to pick the right sense of ambiguous strings — "Bank" becomes Ufer in the second and Bank in the first. You are reading the repo, so you know this: pass it. Max 300 chars. verify: back-translate each result into back_lang to confirm meaning (uses more tokens). back_lang: language for the verify back-translation (default "en"). tone: "formal" or "casual" to steer register; "" (default) is neutral. icu: True if values may contain ICU MessageFormat (plurals/select) so the model preserves the syntax instead of translating it. reuse: optional {lang: {key: previous_translation}} translation-memory map — strings that are unchanged from a prior run are reused verbatim server-side and only new/changed strings are actually translated. api_key: optional KAERIS key (else uses the free tier or KAERIS_API_KEY env). openrouter_key: optional OpenRouter key for Lifetime/BYOK.
Returns: { "translations": { "": { "": "", ... }, ... }, "placeholder_warnings": { "": { "": ["{name}", ...] } }, # if any placeholders were lost "overflow_warnings": { "": [ {"key","src","tr","pct"}, ... ] }, # if UI-overflow risk "back_translations": { "": { "": "" } }, # only if verify=True "failed_languages": [...] # present only if some languages could not be translated }
Inputs: strings (required), target_languages (required), icu, keep, +7 more.
kaeris_translate_fileA
Translate a strings file on disk and write the results next to it.
Supports JSON, YAML, .strings, .po, ARB, Android XML, CSV, XLIFF 1.2, Java/Spring .properties, .NET RESX and Mozilla Fluent (.ftl). With only_new=True (JSON), translates just the keys missing from existing target files and merges.
Args: file_path: path to the source file, e.g. "locales/en.json". target_languages: language codes, e.g. ["de", "uk", "zh"]. out_dir: where to write outputs (default: the source file's directory). only_new: reproducible incremental mode — translate only new AND edited keys, tracked via kaeris.lock (a tone/ICU/glossary change re-translates all); unchanged stays stable. JSON only. keep: optional list of terms to NEVER translate — kept verbatim in every language (brand/product names), e.g. ["KAERIS", "GitHub"]. context: one line about what the app IS, e.g. "a mobile bank for teenagers" or "a wildlife documentary app". The model uses it to pick the right sense of ambiguous strings — "Bank" becomes Ufer in the second and Bank in the first. You are reading the repo, so you know this: pass it. Max 300 chars. verify: back-translate each result into back_lang to confirm meaning (non-incremental only). back_lang: language for the verify back-translation (default "en"). tone: "formal" or "casual" to steer register; "" (default) is neutral. icu: True if values may contain ICU MessageFormat (plurals/select) so the model preserves the syntax instead of translating it. reuse: optional {lang: {key: previous_translation}} translation-memory map — strings unchanged from a prior run are reused verbatim server-side (non-incremental only; only_new does its own client-side diffing). api_key / openrouter_key: optional auth overrides.
Returns: { "written": ["locales/de.json", ...], "languages": [...] }
Inputs: file_path (required), target_languages (required), icu, keep, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct i18n workflow stage—discovery (scan_repo), assessment (status), detailed gap analysis (list_missing_keys), file translation (translate_file), ad-hoc translation (translate), and new-locale bootstrapping (add_language). However, translate_file and add_language overlap in full-file translation, and status/list_missing_keys both report missing keys, though the descriptions clarify their intended use.
All tools share the kaeris_ prefix and lowercase underscore style, and most follow a verb_noun pattern (list_languages, scan_repo, translate_file, list_missing_keys, add_language). Two deviations: kaeris_status is a bare noun, and kaeris_translate is a bare verb, breaking the pattern slightly but remaining readable and predictable.
With 7 tools, the server is well-scoped for its translation/i18n purpose. Each tool covers a distinct functional need—listing languages, scanning repos, checking status, listing missing keys, translating strings or files, and adding languages—without unnecessary granularity.
The tool set covers the full translation lifecycle: discovery (scan_repo), health assessment (status), detailed missing-key inspection (list_missing_keys), incremental and full-file translation (translate_file), ad-hoc string translation (translate), and new-locale creation (add_language). Minor features like language deletion or per-key edits are absent but not essential for the stated purpose.
Maintenance
Related MCP Connectors
Localize iOS and Android apps: coverage, missing strings, glossary-aware AI drafts and file sync.
AI-native translation management: push translation files, translate, review and audit strings.
Localize apps from your AI assistant: translate locale files, set glossaries, connect GitHub repos.
Localize apps from your AI agent: create projects, add languages, import files, add strings, export.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI-powered translation management built for AI agents. Automate localization with regional sensitivity and zero TMS overhead. Works with Claude Code, Cursor, VS Code via MCP protocol. Supports JSON, YAML, Markdown, PO and more.MIT
- AlicenseNot gradedqualityCmaintenanceLocalization as code — push, pull, translate, and extract strings from code with AI. 7 MCP tools for type-safe i18n across 182 languages.121 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables localization of React, Next.js, and Vue apps from an AI assistant by managing projects, languages, translations, glossaries, style guides, and GitHub repository integration.MIT
- AlicenseAqualityBmaintenanceEnables AI agents, developers, and CI pipelines to run deterministic, offline localization QA — pseudolocalization, locale linting for separators/dates/placeholders/RTL, and glossary enforcement across 20 locales — without any network access or API key. When an OpenAI-compatible endpoint is configured, it can also translate into multiple locales and lint the results, or otherwise emit structured translation jobs instead of fabricating translations.5MIT