Stop Feeding Your AI Agent Massive i18n Files: Use MCP Instead

Large localization files waste tokens, pollute your AI agent’s context window, and increase costs. Learn how an MCP server lets GitHub Copilot, Cursor, Claude Code, Codex, and Windsurf fetch only the data they need.

Connecting your AI agent to the ai-l10n MCP server turns it into a professional localization tool. Instead of pasting raw i18n file content into context, the agent calls l10n.dev as a dedicated translation engine — with format guarantees, persistent glossaries, custom style instructions, and token-efficient output.

Why Connect Your AI Agent to a Localization MCP?

The naive approach — pasting your i18n file into the chat — breaks down fast. Here’s what changes when your agent uses a professional localization engine instead:

• Large files handled server-side — the agent never needs to load raw file contents into its context window.
• Format preservation guaranteed — placeholders, keys, and structure survive translation verbatim, validated after every call.
• Persistent glossaries — key terms stay consistent across all files, all chunks, and all future sessions.
• Token-efficient — the agent sends only a file path; only metadata is returned.
• Incremental translation — only new or changed strings are translated, protecting your existing translations.
• Production-ready output — no post-editing required.
• Supports 165 languages — context-aware translations using dedicated AI.

Professional Localization Features for Your AI Agent

The ai-l10n MCP server adds capabilities your AI agent cannot replicate on its own:

📖 AI Glossary Generation

Ask the agent to generate a glossary from your source content before translating. The glossary is saved to your l10n.dev account and automatically applied to every subsequent file and every chunk — ensuring consistent terminology across your entire application, indefinitely.

✏️ Custom Style & Tone Rules

Create linguistic instructions per language pair — for example, “Use informal tone, targeting Latin American Spanish” or “Always keep brand terms in English.” Instructions persist in your account and are applied automatically on every translation call, without repeating yourself each session.

💾 Token-Efficient Translation

Without the MCP, translating a large i18n file means loading the entire file into the agent’s context window — expensive and often truncated. With the MCP, the agent sends only a file path and receives only metadata in return. The entire translation is processed server-side, keeping your context window free.

🛡️ Format Preservation Guaranteed

The server validates that the output format matches the source after every translation — preserving JSON structure, Flutter ARB metadata, YAML keys, PO catalogs, XLIFF segments, and all placeholder syntax. Validation happens server-side before results are returned.

⚡ Incremental Updates

Enable hash-based change detection to skip strings that have already been translated. Only new or modified strings are sent for translation, saving your character quota and protecting existing translations from being overwritten.

Getting Started

Get Your API Key

Create a free account and get your API key at l10n.dev/ws/keys. You can set the key as an environment variable in your agent config (shown below), or ask your agent to store it once with the l10n_set_api_key tool — which saves it to ~/.ai-l10n/config.json for automatic use.

Configure Your AI Agent

Choose your agent below and add the MCP server configuration. All agents use the same npm package — only the config format differs.

Claude Desktop

Open Settings → Developer → Edit Config. Claude Desktop will open the correct MCP config file for your installation. Add the l10n server block:

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

Cursor

Open Customize in Cursor to manage MCP servers, or add the config manually. Use ~/.cursor/mcp.json for a user-wide setup or .cursor/mcp.json in 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"
      }
    }
  }
}

Windsurf

Open the MCPs panel in Cascade, or go to Devin Settings → Cascade → MCP Servers. For manual setup, edit ~/.codeium/windsurf/mcp_config.json:

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

GitHub Copilot (VS Code)

Open the Command Palette and select MCP: Open User Configuration, or create a .vscode/mcp.json file in your workspace:

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

OpenAI Codex

Add to ~/.codex/config.toml for a user-wide setup, or .codex/config.toml in a trusted project:

[mcp_servers.l10n]
command = "npx"
args = ["-y", "ai-l10n-mcp"]

[mcp_servers.l10n.env]
L10N_API_KEY = "your-api-key-here"

Or add it directly from the terminal:

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

Example: Translating Your App with an AI Agent

Once the MCP is connected, your agent proactively checks for instructions and glossaries before translating. Here’s what a typical session looks like when you say: “Translate my app to Spanish and French”:

1. Agent calls l10n_list_instructions — finds no instruction for es/fr language pairs
2. Agent asks: “No instruction found for Spanish/French — would you like to set a tone/style rule before translating?”
3. You say: “Informal tone, food app for Latin America”
4. Agent calls l10n_create_instruction with the style rule
5. Agent calls l10n_list_glossaries — finds no active glossary for es/fr
6. Agent asks: “No glossary found — enable glossary generation for consistent terminology?”
7. You say: “Yes”
8. Agent detects target files already exist — asks: “Enable incremental mode to skip unchanged strings?”
9. You say: “Yes”
10. Agent calls l10n_translate_file with instructions, glossary generation, and incremental mode enabled
11. Agent reports results — production-ready translations, no post-editing needed

Project Setup Prompt

The MCP includes a built-in l10n_project_setup prompt that guides your agent through checking and configuring linguistic instructions and glossaries for optimal translation quality. Run it at the start of every new project or when reviewing your localization settings.

“Run the l10n_project_setup prompt” or “Set up l10n.dev for this project”

Automation Setup Prompt

The MCP includes a built-in l10n_automation_setup prompt that guides your agent through configuring automated translation of your i18n files. Run it once to set up automatic translation for all future commits, eliminating the need to manually trigger translations.

“Run the l10n_automation_setup prompt” or “Set up automatic localization for this project”

Best Practices

• Use Glossary: Enable glossary generation or use an existing glossary. Ask AI to add the existing glossary to your project. This ensures consistent terminology from the very first translation.
• Set Tone Instructions Per Language: Different markets have different expectations. Set instructions per language pair — formal tone for German business software, informal for Spanish consumer apps.
• Use Incremental Mode for Updates: Always enable incremental translation when target files already exist. This protects your current translations and saves your character quota.
• Store Your API Key Securely: Use the environment variable in your agent’s MCP config for shared or CI/CD setups. For personal use, ask the agent to store it once with l10n_set_api_key.
• Use the Project Setup Prompt: Run l10n_project_setup at the start of each new project to make sure instructions and glossaries are configured before translating.
• Use the Automation Setup Prompt: Reduce Manual Effort & Speed Up Releases. Automate translation of your i18n files with the ai-l10n CLI or VS Code extension. This eliminates the need to manually trigger translations, and ensures consistent formatting, glossary application, and style instructions across all files.

Adding the ai-l10n MCP server to your AI agent transforms a fragile, token-heavy workflow into professional-grade localization. Persistent glossaries, custom tone instructions, format guarantees, and incremental updates give your agent capabilities it cannot replicate on its own. Thanks!