Skip to main content
Glama

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.

PyPI license

pip install kaeris-mcp && claude mcp add kaeris-i18n kaeris-mcp
  • Three 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 with verify=True translates 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.lock as 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?

kaeris_scan_repo

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

kaeris_status

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 kaeris check --json)

No

kaeris_list_missing_keys

The exact missing/broken keys (with source text) for one target locale, so an agent knows exactly what to fix

No

kaeris_list_languages

List all supported target languages

Yes, free (no quota)

kaeris_translate

Translate inline strings → per-language results, with QA (placeholder-loss & UI-overflow flags; verify=True back-translates to check meaning)

Yes

kaeris_translate_file

Translate a file on disk (JSON/YAML/.strings/.xcstrings/.po/ARB/XML/CSV/XLIFF/.properties/.resx/.ftl/Markdown), optional incremental — reproducible via kaeris.lock

Yes

kaeris_add_language

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-mcp

Or run it with Docker

docker build -t kaeris-mcp .
docker run -i --rm -v "$PWD:/work" -w /work kaeris-mcp

The 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-mcp

Restart the client; the KAERIS tools appear automatically.

Auth & tiers (all optional)

Env var

Purpose

KAERIS_API_KEY

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

KAERIS_OPENROUTER_KEY

OpenRouter key for Lifetime/BYOK — no monthly volume cap

KAERIS_API_URL

Override the API base URL

KAERIS_NO_UPDATE_CHECK

Set to 1 to turn off the once-a-day "new version available" line (stderr only; already off in CI)

KAERIS_NO_CTA

Set to 1 to drop the pricing link from the error a tool returns when a run is refused on a plan limit

No key is required to try it — the free demo works out of the box.

Example prompts

  • "Translate the strings in locales/en.json into 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 tools
kaeris_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

    A4.6/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-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
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      5
      MIT