@babelize/mcp

MCP (Model Context Protocol) server for Babelize. It lets AI coding agents (Claude Code, Cursor, Codex, or any MCP client) make your app global-ready from the editor.

The four local workflow tools run the same Babelize engine as npx babelize translate, on your machine, against your working tree. You don't need a Babelize account: bring your own LLM key, or use a Babelize API key for hosted translation. The older cloud project management tools are still available for projects on babelize.co.

Local workflow

The loop an agent follows is analyze → translate → check (or review) → fix → repeat. React, Next.js, Django and static HTML are supported; Vue and React Native (Expo and bare) are in beta.

Responses are compact: a short summary plus one line of JSON with capped lists (limit, default 15) and paths relative to the project. path arguments must stay inside the workspace. The workspace is --workspace / BABELIZE_WORKSPACE if set, otherwise the folders your client exposes as MCP roots, otherwise the server's working directory if it is a project (a git repo or a package.json). / and your home directory are never used. babelize_translate runs one at a time per project.

Translation keys

babelize_translate reads keys from the MCP server's environment. Keys are never tool arguments, and the server never prints them.

The first BYOK key found wins, then the Babelize key. An agent can pick one explicitly with provider (and model for BYOK).

Setup

Claude Code

claude mcp add babelize -e ANTHROPIC_API_KEY=sk-ant-... -- npx -y @babelize/mcp

Or share it with your team through .mcp.json in the repo. ${VAR} is expanded from your shell, so no key is committed:

{
  "mcpServers": {
    "babelize": {
      "command": "npx",
      "args": ["-y", "@babelize/mcp"],
      "env": { "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" }
    }
  }
}

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "babelize": {
      "command": "npx",
      "args": ["-y", "@babelize/mcp", "--workspace", "${workspaceFolder}"],
      "env": { "OPENAI_API_KEY": "${env:OPENAI_API_KEY}" }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.babelize]
command = "npx"
args = ["-y", "@babelize/mcp"]
env = { ANTHROPIC_API_KEY = "sk-ant-..." }

If the local tools report the wrong folder, add "--workspace", "/path/to/your/app" to args.

Claude Desktop, opencode and other clients

Run npx -y @babelize/mcp as a stdio server and set one of the key env vars above. If the client doesn't start the server in your project folder (Claude Desktop doesn't), pass --workspace /path/to/your/app.

{
  "mcpServers": {
    "babelize": {
      "command": "npx",
      "args": ["-y", "@babelize/mcp", "--workspace", "/path/to/your/app"],
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}

Example prompts

Make this app global-ready in German and Japanese.

The agent runs babelize_analyze → babelize_translate {to: ["de","ja"]} → babelize_check, then reports what changed. The make-global-ready MCP prompt contains the same instructions.

What would it take to localize this app? Don't change anything.

babelize_analyze reports what translation would extract and wire up, and what it can't. To preview the actual diff, use babelize_translate with dryRun: true (this one does call the translator).

I edited the French strings. Anything broken before I commit?

babelize_review checks only the changed entries for lost placeholders, ICU and plural errors, untranslated text, and stale translations.

Add Korean too.

babelize_translate {to: ["ko"]} keeps de/ja, and the lockfile means only Korean is translated.

Cloud project management tools

These tools manage projects on babelize.co and need a Babelize API key (BABELIZE_API_KEY, --api-key or .babelize/config.json). The two scan tools are low-level helpers that need no key.

Scanning (low-level, no API key required)

Scanned strings are flagged with is_icu: true when they contain ICU MessageFormat syntax ({count, plural, ...}, select, selectordinal).

Projects

Translation Runs

Languages

Analysis

Translation Quality

Translation memory is owner-scoped. The babelize_tm_* tools take a project_id to select the API route, but owners read and write their entire memory, which is shared across all projects they own (members see only entries from projects they belong to).

Team & Deploy

Account

Configuration

The cloud API settings are resolved in this order:

1. CLI args: --api-key, --api-url
2. Environment variables: BABELIZE_API_KEY, BABELIZE_API_URL
3. Local config file: .babelize/config.json in the current working directory

The local tools also read .babelize/config.json in the project for sourceLocale and an optional glossary, which babelize_translate applies and babelize_check and babelize_review check:

{
  "sourceLocale": "en",
  "glossary": {
    "neverTranslate": ["Babelize"],
    "alwaysTranslateAs": [{ "term": "workspace", "translations": { "de": "Arbeitsbereich" } }]
  }
}

Options

Set BABELIZE_API_URL to the origin only — do not include the /api suffix (e.g. http://localhost:3001), otherwise requests go to /api/api.

Cloud workflow examples

Translate a GitHub project in one command

Ask your AI agent:

"Translate my-project to French and Spanish."

The agent will:

1. babelize_project_list — find your project
2. babelize_project_language_add — add French + Spanish
3. babelize_run_and_wait — start + wait for completion
4. babelize_project_download — download the translated ZIP

Translate local code without GitHub

"Scan my local project and translate it to German."

1. babelize_scan — find all hardcoded strings (no API key needed)
2. babelize_translate {to: ["de"]} — translate on your machine and write the result into the working tree (no cloud project needed)

For a cloud project without GitHub, run babelize init --source zip in the project directory. It uploads the project as a ZIP. babelize_project_create creates GitHub projects only.

Check translation quality

"Review the translation quality for my project."

1. babelize_tm_get — check translation memory entries
2. babelize_glossary_get — review glossary for consistent terminology
3. babelize_babel_get — inspect detailed run logs
4. babelize_glossary_set — add missing glossary entries for consistent translations

Audit i18n readiness

"Scan my codebase for i18n issues."

Use babelize_analyze (local, no key). It covers what babelize_scan and babelize_engine_analyze do, and runs the real extraction and injection in dry-run mode.

Links

• Website
• Docs
• npm