MCP Server for Localization: How AI Agents Manage Translations

MCP Server for Localization: How AI Agents Manage Translations

The way developers handle internationalization is undergoing a fundamental shift. With the rise of AI coding agents like Cursor, Claude Code, Windsurf, and Zed, the question is no longer whether AI will help manage translations — it's how. The answer lies in a new open standard: the Model Context Protocol (MCP).

In this guide, we'll explore what MCP is, why it matters for localization, and how you can set up an MCP server that lets AI agents create, update, and publish translations — all without leaving your IDE.

What Is MCP and Why It Matters for i18n

The Model Context Protocol (MCP) is an open standard created by Anthropic that allows AI models to interact with external tools and data sources through a unified interface. Think of it as a USB-C port for AI — a single protocol that connects any AI agent to any external service.

For localization, MCP is transformative because it bridges the gap between:

• AI coding agents that understand your codebase, context, and intent
• Translation management systems (TMS) that store, organize, and deliver translations

Without MCP, developers must context-switch between their IDE, a translation dashboard, JSON files, and review workflows. With MCP, the AI agent handles all of this in a single conversation.

Key Benefits for i18n Teams

The Problem: AI Agents Can't Use Translation Tools Natively

Modern AI coding agents are remarkably capable at writing code, but they have a critical limitation: they can't interact with external services by default. When a developer asks an AI agent to "add a new translation key for the login button," the agent faces a wall.

What Typically Goes Wrong

1. File-based hacks: The agent edits JSON translation files directly, bypassing the TMS entirely. This creates sync issues, overwrites other translators' work, and breaks CI/CD pipelines.

2. Hallucinated translations: Without access to existing translation memory or glossaries, the agent guesses at translations. These often contain subtle errors — wrong gender, incorrect formality level, or semantic drift.

3. No workflow awareness: The agent doesn't know about review processes, publishing gates, or namespace conventions. It might create duplicate keys in the wrong namespace or skip quality checks.

4. Context isolation: Each conversation starts fresh. The agent doesn't remember which keys were already created, what the team's naming conventions are, or which languages are active.

These problems compound at scale. One real-world incident involved an AI agent creating over 1,000 phantom keys in the wrong namespace because it used createKeys instead of updateKeys and didn't know the correct namespace. This is exactly the kind of mistake that MCP tool descriptions are designed to prevent.

The Solution: Better i18n MCP Server

Better i18n provides a purpose-built MCP server that exposes localization operations as structured tools that AI agents can call. Instead of hacking JSON files, the agent interacts with your translation management system through a well-defined API with built-in guardrails.

Architecture Overview

+-------------------------------------+
|         AI Coding Agent             |
|   (Cursor, Claude, Windsurf, Zed)   |
+----------------+--------------------+
                 | MCP Protocol (stdio)
                 v
+-------------------------------------+
|      Better i18n MCP Server         |
|  +-----------+  +----------------+  |
|  |Translation|  |    Content     |  |
|  |   Tools   |  |     Tools      |  |
|  +-----------+  +----------------+  |
+----------------+--------------------+
                 | REST API
                 v
+-------------------------------------+
|     Better i18n Cloud Platform      |
|  Translations - Content - Analytics |
+-------------------------------------+

Available Tool Categories

The MCP server exposes two sets of tools:

Translation Tools (@better-i18n/mcp):

• listKeys — Browse and filter translation keys with status info
• getTranslations — Fetch translations for specific keys and languages
• createKeys — Add new translation keys with initial values
• updateKeys — Modify existing translations
• publishTranslations — Push approved translations live
• getPendingChanges — Review unpublished changes before publishing

Content Tools (@better-i18n/mcp-content):

• listContentEntries — Browse blog posts, marketing pages, etc.
• createContentEntry — Create new content with multi-language support
• updateContentEntry — Edit existing content
• publishContentEntry — Publish content to production

Demo: 5-Step MCP Server Setup Guide

Getting the Better i18n MCP server running takes less than 5 minutes. Here's how:

Step 1: Get Your API Key

Navigate to your Better i18n dashboard and go to Settings then API Keys then Create New Key. Copy the key — you'll need it in the next step.

Step 2: Configure Your AI Agent

Add the MCP server to your agent's configuration file. Here's how it works for popular agents:

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 3: Verify the Connection

After restarting your agent, verify the tools are available:

You: "List my translation projects"

Agent: I found 2 projects:
  - my-org/web-app (12 languages, 2,847 keys)
  - my-org/mobile-app (8 languages, 1,203 keys)

Step 4: Start Managing Translations

Now you can interact with your translations naturally:

You: "Add a new key 'auth.login.welcome_message' with English value
      'Welcome back!' and German value 'Willkommen zurueck!'"

Agent: Created key 'auth.login.welcome_message' in namespace 'auth'
       - en: "Welcome back!"
       - de: "Willkommen zurueck!"
       Status: draft (unpublished)

Step 5: Review and Publish

You: "Show me all pending changes for the auth namespace"

Agent: 3 pending changes in 'auth' namespace:
  1. auth.login.welcome_message — new key (en, de)
  2. auth.login.forgot_password — updated (de)
  3. auth.signup.terms_label — new key (en)

You: "Publish all pending changes"

Agent: Published 3 changes to production.

Use Cases: Where MCP Shines for Localization

1. PR Review with Translation Awareness

When reviewing a pull request, the AI agent can automatically check whether new UI strings have corresponding translation keys:

You: "Review this PR for missing translations"

Agent: I found 3 new user-facing strings without translation keys:
  - src/components/Checkout.tsx:42 - "Processing your order..."
  - src/components/Checkout.tsx:58 - "Payment failed. Please try again."
  - src/components/Checkout.tsx:73 - "Order confirmed!"

  Shall I create translation keys for these?

2. Auto-Translation with Human Review

The agent can propose translations using AI, but the MCP workflow ensures they go through your team's review process:

You: "Translate all missing German keys in the 'checkout' namespace"

Agent: I'll propose German translations for 12 missing keys.
       These will be saved as drafts for your translators to review.

       Proposed 12 German translations (status: pending review)

3. Key Management and Cleanup

You: "Find unused translation keys in the auth namespace"

Agent: I cross-referenced auth namespace keys with your codebase:
  - auth.legacy.old_login — not referenced anywhere
  - auth.legacy.reset_v1 — not referenced anywhere
  - auth.experimental.biometric — referenced only in commented code

  Shall I archive these keys?

4. Content Localization

Beyond translation keys, the MCP server handles CMS content:

You: "Create a new blog post about our v2.0 release in English,
      then translate the title and excerpt to German and Turkish"

Agent: Created blog post "Announcing Better i18n v2.0"
       Added German translation: "Better i18n v2.0 — Jetzt verfuegbar"
       Added Turkish translation: "Better i18n v2.0 Duyurusu"
       Status: draft (ready for review)

5. Localization Analytics

You: "What's our translation coverage for the mobile app?"

Agent: Translation coverage for my-org/mobile-app:
  - English: 100% (1,203/1,203 keys)
  - German: 94% (1,131/1,203 keys) — 72 missing
  - French: 91% (1,095/1,203 keys) — 108 missing
  - Japanese: 87% (1,047/1,203 keys) — 156 missing

Technical Deep-Dive: Tool Descriptions as Guardrails

One of the most critical aspects of MCP server design is something that might seem trivial: tool descriptions. In practice, tool descriptions are the primary mechanism for preventing AI agent misuse.

Why Descriptions Matter More Than You Think

When an AI agent sees a list of available tools, the tool descriptions function as system prompts that guide the agent's behavior. A vague description leads to misuse; a precise description prevents it.

Consider this real example from Better i18n's MCP server:

Bad description (leads to agent errors):

name: "createKeys"
description: "Create new translation keys"

Good description (prevents errors):

name: "createKeys"
description: "Create NEW translation keys that don't exist yet.

IMPORTANT: Use this ONLY for brand-new keys. To modify existing
translations, use updateKeys instead.

WORKFLOW: 1. listKeys to check if key exists 2. createKeys if new,
OR updateKeys if existing.

NAMESPACE: Must match an existing namespace. Using a wrong namespace
creates duplicate keys that are hard to clean up.

REQUIRED: project, keys array with {key, namespace, translations}
OPTIONAL: tags for categorization"

Safety Mechanisms

The Better i18n MCP server implements multiple layers of safety:

1. Proactive Guardrails (Tool Descriptions)

• Step-by-step workflows documented in every tool description
• Parameter dependencies explicitly stated (e.g., "status filter REQUIRES languages parameter")
• Common misuse patterns warned against directly in the description

2. Reactive Safety Nets (Response Warnings)

{
  "result": { "created": 1 },
  "warn": "Key 'auth.login.title' already exists in namespace 'auth-v2'. Did you mean to use updateKeys?",
  "hint": "Use listKeys with namespace filter to verify the correct namespace before creating keys."
}

3. Cross-Entity Collision Detection

When a key name exists in multiple namespaces, the server warns the agent to prevent accidental duplicates.

4. Idempotency Guards

Operations like publishTranslations are safe to retry — publishing already-published translations is a no-op, not an error.

The Description-First Design Pattern

When building MCP tools for any domain, follow this pattern:

1. What could go wrong? List every way an agent might misuse the tool
2. Add proactive guardrails — Encode correct workflows in the description
3. Add reactive warnings — Return warning fields when misuse is detected
4. Test with real agents — Watch how different AI models interpret your descriptions

This pattern applies beyond localization. Any MCP server benefits from treating tool descriptions as the primary interface contract with AI agents.

Conclusion: First-Mover Advantage in AI-Native Localization

The localization industry is at an inflection point. AI coding agents are becoming the primary interface through which developers interact with external services. Teams that adopt MCP-based localization workflows today gain:

• Developer velocity: No more context-switching between IDE and TMS dashboards
• Consistency: AI agents follow the same workflows every time, reducing human error
• Scalability: One developer with an AI agent can manage translations across dozens of languages
• Quality: Built-in guardrails prevent the common mistakes that plague file-based i18n workflows

Better i18n is the first localization platform with native MCP support, purpose-built for the AI-native development era. While other platforms are still debating whether to build API integrations, Better i18n's MCP server is already in production — used daily by engineering teams managing millions of translation keys.

Get Started Today

1. Sign up for Better i18n — free tier available
2. Install the MCP server — 5-minute setup
3. Explore the features — see what's possible
4. Join the developer community — connect with other i18n developers

The future of localization is AI-native. The question isn't whether to adopt MCP — it's how soon you can start.

Want to see MCP in action? Check out our guide to using Better i18n MCP with coding agents for a hands-on tutorial with Cursor, Claude Code, Windsurf, and Zed.