paraglide-messages-mcp

license: MIT node >= 20

An MCP server that turns AI agents into a parallel translation team forParaglide JS /inlang messages/{locale}.json files.

The agent calling the tools is the translator. The server makes thatsafe and fast:

Validated writes — every translation is checked against the source(placeholders, markup, plural variants) before anything lands on disk;bad items are rejected individually, never the whole batch.
One agent per locale, in parallel — the translate loop reads andwrites only the source and target locale's files, so subagents cantranslate all locales concurrently without conflicts.
Fast and offline — direct JSON file access with a stat-validatedcache; tool calls cost milliseconds regardless of project size, and nonetwork is ever needed.
Toolchain-invisible — written files are byte-compatible with themessage-format plugin's own output, and external edits (editor, compiler,git) are always picked up.

Quick start

No installation — add this to your .mcp.json (Claude Code) orclaude_desktop_config.json:

{
  "mcpServers": {
    "paraglide": {
      "command": "npx",
      "args": [
        "-y",
        "paraglide-messages-mcp",
        "--project",
        "./project.inlang",
        "--translation-style",
        "Concise product UI; informal address; keep brand terms untranslated."
      ]
    }
  }
}

--project is optional: the server finds project.inlang in the workingdirectory (or a single *.inlang directory up to one level deep) by itself.--translation-style is optional but recommended: it gives agents thelinguistic brief to use for tone, formality, and terminology instead ofderiving style from existing translations.

Then ask your agent to translate — or use the translate_project prompt totranslate every locale at once with one subagent per locale.

Tools

Tool	Purpose
`project_info`	Locales, base locale, `totalKeys` across all locales, `translatableKeys` from non-empty base messages, per-locale translated/missing counts, extra non-source keys, and the startup translation style brief when configured.
`get_translation_batch`	Next batch of untranslated messages for a locale (default 50), with source text and required placeholders.
`get_retranslation_batch`	Cursor-paged batch over already-translated messages too — refresh stale entries after source/terminology changes.
`save_translations`	Validate and persist translations for one locale; per-item results — overwrites existing values.
`list_message_keys`	Keys only, filterable by prefix and status, paginated.
`get_messages`	Full message content by keys or prefix.
`search_messages`	Find messages by text or key substring.
`delete_messages` / `rename_message`	Key management across all locales.
`remove_orphan_messages`	Delete target-locale keys that are absent from the source locale (base locale by default), optionally scoped by locale or prefix.
`add_locale` / `remove_locale`	Locale management in `settings.json`.

Prompts

Prompt	Purpose
`translate_project`	Translate every locale: the main agent uses the startup translation style brief (or asks the user for one), then fans out one subagent per locale in parallel.
`translate_locale`	Translate one locale via the batch loop.
`translate_prefix`	Same, scoped to keys starting with a prefix.
`retranslate`	Redo existing translations (stale copy, changed terminology) — by key prefix, every target locale by default, one subagent per locale.
`review_locale`	Review existing translations against the base locale and fix problems.

Read-only state is also exposed as MCP resources(paraglide://project/info, paraglide://locales/{locale}/missing,paraglide://messages/{locale}/{key}), so clients can pin it as contextwithout spending tool calls.

Agent skill

skill/paraglide-translation/ is an optional installable skill in the openAgent Skills format. The skill simply points the agent to the MCP server.

# Codex, via the skills CLI
npx skills add whazeted/paraglide-messages-mcp --skill paraglide-translation -a codex

# Or install from the skill folder URL directly
npx skills add https://github.com/whazeted/paraglide-messages-mcp/tree/main/skill/paraglide-translation -a codex

For other skills-compatible agents, replace codex with that agent'sskills CLI target name. You can list the skill before installing:

npx skills add whazeted/paraglide-messages-mcp --list

Compatibility

Requires the standard Paraglide JS setup: the inlang message formatplugin with a single message file per locale (any pathPattern location).Other inlang plugins (i18next, next-intl, ICU) and multi-file namespaces aredeliberately not supported — see COMPATIBILITY.md forthe exact criteria and reasoning.

Performance

A full 10-locale translation run over a 5,000-message project costs ~3 s ofserver time (M1 Max Mac Studio)— the pipeline is bounded by the agent's translation speed, notthe server.

Documentation

DEVELOPMENT.md — architecture, message format details,validation rules, building, testing, benchmarking, releasing
COMPATIBILITY.md — supported project setups

License

MIT

paraglide-messages-mcp