Let AI agents manage your translations

The Translatize MCP server gives AI agents – Claude Code, Cursor, Claude Desktop, and any other Model Context Protocol client – direct, branch-scoped access to your translations. It runs over stdio and exposes 28 tools and 2 workflow prompts to read and write keys with context, translate, run QA checks, publish over-the-air releases and manage git-like branches.

The agent workflow

With a create-own token, an agent can take a translation change from start to finish inside the conversation – and never touch main without your say-so.

1. Step 1

   Ship a feature – on its own branch

   You build a feature with your AI agent. Before touching a single string, the agent forks a translation branch off the base with create_branch. Your main branch stays untouched the whole time.

   create_branch
2. Step 2

   Add the new keys with context

   The agent writes the feature's new source strings to the branch in one batched call with upsert_labels, each with its context: what the UI element is, a character limit when the layout has one, the path:line it came from, and doNotTranslate for product names and codes. The base branch never sees a half-finished change.

   upsert_labelsset_label_context
3. Step 3

   Translate the missing values

   On any plan, the agent translates them itself: get_missing_translations returns each key with an empty target value, get_glossary and find_translation_memory keep the wording consistent with what the project already uses, and upsert_labels writes the result back. On a Professional or Agency plan it can instead hand the work to Translatize's platform AI with auto_translate and watch the job with translation_job_status.

   get_missing_translationsfind_translation_memoryauto_translatetranslation_job_status
4. Step 4

   Run QA until it is clean

   The agent calls run_qa, fixes every error it reports (a rewritten value or repaired placeholders), runs it again, and finishes with check_merge_gate to see whether the merge would be refused.

   run_qaget_qa_issuescheck_merge_gate
5. Step 5

   Mark for review – and ask you

   The agent marks the touched keys with set_labels_status, then calls review_changes for a diff and a platformUrl. It stops and asks: “review here in the chat, or on Translatize?” – and waits for your approval before going any further.

   set_labels_statusreview_changes
6. Step 6

   You approve – it merges and cleans up

   Once you approve, the agent folds the branch into the base with merge_branch (checking get_merge_conflicts first when needed), then removes the working branch with delete_branch. The change lands on main only after your sign-off – and merging into main needs an admin-role token, otherwise you merge in the app.

   merge_branchdelete_branch

Setup

The server ships on npm as @translatize/mcp (version 0.2.0) with the binary translatize-mcp, and is listed in the MCP Registry as com.translatize/mcp. Point your client at npx -y @translatize/mcp and pass a token – no global install needed. It needs Node.js 18.17 or newer.

Claude Code

Register the server once; Claude Code launches it on demand with npx. Drop the -e flag if TRANSLATIZE_API_TOKEN is already exported in your shell. For the server plus ready-made skills, install the Claude Code plugin instead.

claude mcp add translatize -e TRANSLATIZE_API_TOKEN=mcni_xxx -- npx -y @translatize/mcp

Cursor

Add the server to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "translatize": {
      "command": "npx",
      "args": ["-y", "@translatize/mcp"],
      "env": {
        "TRANSLATIZE_API_TOKEN": "mcni_xxx"
      }
    }
  }
}

Any MCP client (Claude Desktop, etc.)

The same mcpServers block works for any client that speaks MCP over stdio – for Claude Desktop, put it in claude_desktop_config.json. For a pinned install, run npm i -g @translatize/mcp and set "command": "translatize-mcp" with "args": [].

{
  "mcpServers": {
    "translatize": {
      "command": "npx",
      "args": ["-y", "@translatize/mcp"],
      "env": {
        "TRANSLATIZE_API_TOKEN": "mcni_xxx",
        "TRANSLATIZE_API_URL": "https://api.translatize.com/v1"
      }
    }
  }
}

Claude Code plugin

The Translatize plugin for Claude Code bundles the MCP server with two skills, so Claude knows when to use the tools without being told. The plugin reads your token from TRANSLATIZE_API_TOKEN in the environment Claude Code runs in, so the token never lives in the plugin. Its directory, claude-plugin, is in the public Translatize/integrations repository. Clone it, export the token and start Claude Code with the plugin:

git clone https://github.com/Translatize/integrations.git
export TRANSLATIZE_API_TOKEN=mcni_xxx
claude --plugin-dir ./integrations/claude-plugin

Run /mcp in the session to check that the translatize server is connected. Then ask something like “Localize the checkout page into Latvian and German”.

Other coding agents can follow the same rules from your repository. This CLI command writes them into a marked section of AGENTS.md (and CLAUDE.md, when it exists):

npx @translatize/cli init --agents

How it works

Every token is bound to one project and one base branch, and carries a branch scope. Call get_project_info (or list_branches) to see the base branch, the scope, and which branches the token may write to.

Branch scope

fixed (the default) – the token can only read and write its one base branch. create-own – the token may additionally create branches (always forked from the base), read/write/export the branches it created, and compare, merge, and delete those back into the base. Apart from its base branch, it can never touch a branch it did not create. The label and translation tools take an optional branch argument naming any branch in that allowed set; omit it to act on the base branch, and naming a branch outside the set fails with branch_not_allowed.

Environment variables

Tool catalog

Twenty-eight tools in seven groups. Every label and translation tool accepts an optional branch argument (default: the token's base branch). When a call fails, the tool returns the API error code and a short remedy, so the agent can react without the session breaking. merge_branch, delete_branch and publish_release are marked as destructive, so clients that confirm risky calls will ask you first. The same operations are available over REST – see the Integration API reference.

Workflow prompts

Two prompts package the whole workflow. In Claude Code they appear as /mcp__translatize__localize_repo and /mcp__translatize__prepare_branch_for_merge.