AI Localization Agent

AI Localization Agent adds professional localization. Instead of loading large i18n files into the AI's context, it translates them server-side via MCP (the ai-l10n-mcp package, built on the ai-l10n SDK and CLI), saving tokens and keeping the agent focused on coding. It preserves file formats, placeholders, and existing translations, supports 165 languages, applies persistent glossaries and custom linguistic instructions, and translates only changed strings for fast, production-ready localization.

MCP server that gives AI agents access to l10n.dev — aprofessionallocalization servicepurpose-built for software i18n files.

Create a free account and get your API key athttps://l10n.dev/ws/api-keys

{ "mcpServers": { "l10n": { "command": "npx", "args": ["-y", "ai-l10n-mcp"], "env": { "L10N_API_KEY": "your-api-key-here" } } } }

OpenCustomizein Cursor to add and manage MCP servers. For a file-based setup, create one of these configs:

- ~/.cursor/mcp.jsonfor a user-wide setup
- .cursor/mcp.jsonin your project for a workspace-specific setup

{ "mcpServers": { "l10n": { "type": "stdio", "command": "npx", "args": ["-y", "ai-l10n-mcp"], "env": { "L10N_API_KEY": "your-api-key-here" } } } }

In Windsurf, open theMCPspanel in Cascade, or go toDevin Settings > Cascade > MCP Servers. If you need to add it manually, edit~/.codeium/windsurf/mcp_config.jsonand add:

{ "mcpServers": { "l10n": { "command": "npx", "args": ["-y", "ai-l10n-mcp"], "env": { "L10N_API_KEY": "your-api-key-here" } } } }

Open the Command Palette and select MCP: Open User Configuration. Alternatively, create a.vscode/mcp.jsonfile in your workspace or user settings. Add:

{ "servers": { "l10n": { "type": "stdio", "command": "npx", "args": ["-y", "ai-l10n-mcp"], "env": { "L10N_API_KEY": "your-api-key-here" } } } }

Add to~/.codex/config.tomlfor a user-wide setup, or.codex/config.tomlin a trusted project:

[mcp_servers.l10n] command = "npx" args = ["-y", "ai-l10n-mcp"] [mcp_servers.l10n.env] L10N_API_KEY = "your-api-key-here"

codex mcp add l10n --env L10N_API_KEY=your-api-key-here -- npx -y ai-l10n-mcp

claude mcp add --env L10N_API_KEY=your-api-key-here --transport stdio l10n -- npx -y ai-l10n-mcp

For a shared project setup, Claude Code can also store MCP servers in a.mcp.jsonfile at your project root.

Both tools detect language codes in language-code folders (locales/en/common.json, reported asfolder-based) and in file names (file-based) — whether the name is the code itself (locales/en.json) or holds it alongside other parts (app_en.arb,locales/emails.en.json,locales/en-US.common.json,messages_en_US.properties). For naming conventions that are not recognized, passlanguageCodeRegex, a regex containing a(?<language>...)group, e.g.^emails\.(?<language>[\w-]+)\.json$. The text around the group is reused for target files, soemails.en.jsonproducesemails.ru-RU.json.

Guides through checking and configuring linguistic instructions and glossaries for optimal translation quality. Invoke it at the start of a new project or when reviewing l10n.dev settings.

- sourceLanguage— source language code (default:en)
- targetLanguages— comma-separated target language codes (e.g.es,fr,de)

Scans the project for i18n source files (usingl10n_detect_project_structure), checks linguistic instructions, glossary, and balance, then interactively sets up fully automated translation via GitHub Actions or npm scripts.

For GitHub Actions, guides through four trigger options:

- A)On every push tomain— translate and commit back directly
- B)On pull requests — translate and open a PR for review
- C)On a schedule — translate nightly or on a cron
- D)Manual trigger only —workflow_dispatch

Writesai-l10n.config.jsonand.github/workflows/translate.yml(or updatespackage.jsonscripts), then tells you where to add the API key and what happens on the next trigger.

- sourceLanguage— source language code (default:en)
- targetLanguages— comma-separated target language codes (e.g.es,fr,de)

User:"Translate my app to Spanish and French"
- Calll10n_list_instructions— finds no instruction fores/frlanguage pairs
- Ask:"No instruction found for Spanish/French — would you like to set a tone/style rule before translating? (e.g. formal, casual, keep brand terms untranslated)"
- User says:"Tone should be informal, it's for a food app in Latin America"
- Calll10n_create_instructionwith the style rule
- Calll10n_list_glossaries— finds no active glossary fores/fr
- Ask:"No glossary found for Spanish/French — enable glossary generation for this run? It saves key terms for consistent future translations."
- User says:"Yes"
- Detect thates.jsonandfr.jsonalready exist — ask:"Target files already exist — enable incremental mode to skip unchanged strings and save quota?"
- User says:"Yes"
- Calll10n_translate_filewithsourceFile,targetLanguages: ["es", "fr"],instruction,generateGlossary: true,translateOnlyNewStrings: true
- Report results

For JSON-based formats, enabletranslateOnlyNewStrings: trueto skip strings that are already translated. A hash of each source string (not content itself) is stored on the l10n.dev server for change detection — only added or changed strings are translating, saving your character quota.

Note:First translation it translates only added strings, because hash table is empty to detect changed strings.

For CI/CD automation and command-line usage, see:

- ai-l10n CLI— translate files from the terminal or CI pipelines
- GitHub Action— auto-translate on push, PR, or manual trigger

- Free tier— 10,000 characters free every month, no credit card required.
- Pay-as-you-go— Affordable character-based pricing with no subscription required.
- Current packages— Visitl10n.dev/#pricingfor up-to-date pricing.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB