i18n-locale-mcp
# i18n-locale-mcp
A zero-dependency [MCP](https://modelcontextprotocol.io) server that gives any AI agent a
**localization QA toolkit**. Deterministic, offline-capable, and safe to run in CI.
Works with Claude Desktop, Cursor, Dify, AutoGPT, and any MCP-compatible client.
## Why
Shipping a product in 20 locales is easy; shipping it *correctly* is not. Agents and devs
constantly produce `1,234` in German, `03/25` in French, missing `{name}` placeholders, or
untranslated brand terms. This server catches those deterministically — no API key needed.
## Tools
| Tool | What it does | Network |
|:--|:--|:--|
| `list_locales` | Locale formatting rules (quotes, separators, dates, RTL, formality) for 20 locales | none |
| `pseudo_localize` | Accented + expanded pseudolocale to catch hard-coded strings & truncation | none |
| `i18n_lint` | Number/date separators, quote style, CJK punctuation, RTL bidi, placeholder parity, length budget | none |
| `glossary_apply` | Enforce terminology + protect brand terms across targets | none |
| `localize` | Translate to N locales, then lint — **or** emit structured translation jobs if no provider is set | optional |
`localize` **never fabricates translations**: without a provider configured it returns
machine-readable translation jobs (source + rules + placeholders) for you to execute.
## Install
```bash
git clone <repo> && cd i18n-mcp
node index.js --list-tools # sanity check
node test/smoke.mjs # 11 deterministic checks
```
Requires Node.js >= 18. No dependencies.
## Use with an MCP client
Add to `claude_desktop_config.json` (or Cursor / Dify MCP settings):
```json
{
"mcpServers": {
"i18n": {
"command": "node",
"args": ["/absolute/path/to/i18n-mcp/index.js"]
}
}
}
```
### Optional: enable live translation
Set an OpenAI-compatible endpoint and `localize` will translate before linting:
```bash
export I18N_LLM_BASE_URL="https://api.openai.com/v1"
export I18N_LLM_API_KEY="sk-..."
export I18N_LLM_MODEL="gpt-4o-mini" # optional
```
Without these, `localize` returns `providerMode: "jobs"` and does zero network calls.
## Examples
### Pseudolocalize (find hard-coded UI strings)
```js
pseudoLocalize("Save changes") // 【Såvé çhångéš~~~~~~~~~】
```
### Lint a translation
```json
{ "text": "Gesamt: 1,234 EUR", "locale": "de-DE" }
```
→ `NUMBER_GROUP_SEP` error: German expects `.` as thousands separator.
### Programmatic API
```js
import { pseudoLocalize, lint, glossaryApply, localize } from "i18n-locale-mcp";
lint("Cherchez 03/25/2026", "fr-FR"); // DATE_ORDER error
glossaryApply([{ source: "Save", target: "Enregistrer" }],
[{ key: "btn.save", text: "Save" }]); // TERM_UNTRANSLATED
await localize("Hello {name}", ["de-DE", "ja-JP"]); // lint-ready output
```
## CLI
```bash
node index.js # run MCP server on stdio
node index.js --list-tools # list tools
node index.js --version
```
## License
MIT
TDQS
Scored across 5 tools
Each tool has a distinct primary purpose, but localize overlaps slightly with i18n_lint and glossary_apply because it performs post-processing. The descriptions clarify when to use each, so confusion is limited.
All names use snake_case, which is consistent, but the structural pattern varies: list_locales and pseudo_localize are verb-like, i18n_lint and glossary_apply are noun-first, and localize is a bare verb. This is mostly predictable with minor deviations.
Five tools is well-scoped for a focused i18n localization toolkit. Each tool earns its place by covering a specific stage of the localization workflow.
The surface covers locale inspection, pseudolocalization, linting, glossary enforcement, and translation, which is strong lifecycle coverage. Minor gaps exist around configuring translation providers or extracting strings from source files, but agents can work around these.