localize.dev

Localize an app from your coding agent: find hardcoded UI text, give it translation keys, rewrite the code to your i18n library and translate it into every language.

View on uselocalize.dev

Hosted MCP Server

npx add-mcp 'https://uselocalize.dev/api/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Localize from inside your coding agent.

localize-dev mcp gives your coding agent the same tools as the CLI. Ask for a page in Spanish, and it finds the hardcoded copy, extracts it into keys and translates it, following your glossary. Set it up with init --agent, and it does the same for each file as it writes it.

$claude mcp add localize -- npx -y localize-dev mcp

~/acme/storefrontlocalize connected

Ship the checkout page in Spanish, French and German.

localize.check(only: "strings")

2 hardcoded strings in components/Checkout.tsx.

components/Checkout.tsx:18 "Place order"
components/Checkout.tsx:24 "Discount code"

localize.localize(paths: ["components/Checkout.tsx"])

- <button>Place order</button>

+ <button>{t('checkout.place_order')}</button>

es Realizar pedido
fr Passer la commande
de Bestellung aufgeben

2 keys written, 3 languages filled in. The diff is in your working tree to review.

Tools

Five tools, the ones the CLI already has.

The agent picks the tool; each answers with structured results (files, lines, keys) it can act on.

localize

Extracts hardcoded strings into translation keys, rewrites the code to your i18n library and translates the new messages into every language. For some files only, or as a dry run first.

- <h2>Order summary</h2>

+ <h2>{t('checkout.order_summary')}</h2>

locales/es.jsonlocales/fr.jsonlocales/de.json

check

Finds UI copy still hardcoded in the code, and translations missing or out of date, each with its file and line. Changes nothing. Given the files the agent just changed, it answers in about a second.

hardcoded Checkout.tsx:18
missing fr · cart.empty
outdated de · cart.total

translate

Fills in missing translations, and redoes ones whose source text changed, in your existing locale files.

JSON
YAML
.po
.arb
strings.xml
.xcstrings

add_language

Translates every message into a new language, then adds it to localize.config.json. Without a key, nothing is changed.

"targetLocales": ["es", "fr", "ja"]

config

Your languages, locale files and i18n library, and the project's glossary, so copy the agent writes by hand follows it too.

Keep: Acme
checkout → es: pago

No key neededOn your machine, check and config work without an API key.

A session

Ask in plain words. Review the diff.

The agent decides when to call each tool. You see every call, and the result lands in your working tree.

You ask01 "Ship the checkout page in Spanish", "Add Japanese", or "Is anything left untranslated?"
It checks02 check lists the hardcoded copy and missing translations, with files and lines.
It localizes03 localize or translate writes the keys, the code changes and every language's locale file.
You review04 Read the diff like any other change, then commit it. The next check comes back clean.
Scroll to walk through a session

agent

Ship the checkout page in Spanish, French and German.

I'll check the checkout page for hardcoded copy first.

localize.check(only: "strings")

As you write

Translated before the pull request opens

One command sets up your coding agents. After that, each file an agent edits is checked for text that isn't translated, and the agent localizes it before moving on.

1 The agent writes a component with new text in it.
2 Claude Code's after-edit hook checks that one file, in about a second, with no key or model, and tells the agent which lines still have hardcoded text.
3 The agent calls localize on the file. The text gets keys and translations, so the pull request arrives with every language filled in.

Cursor, Codex and other agents get the same instructions from AGENTS.md and a Cursor rule. Add --pre-commit to also check staged files before each commit, and set LOCALIZE_DEV_HOOK=off to pause the hook.

npx localize-dev init --agent

What the agent sees after an edit

localize.dev: src/components/Promo.tsx has UI text that isn't translated yet.
  line 4: "Free shipping on orders over $50"
Call the localize tool of the localize-dev MCP server with paths ["components/Promo.tsx"]: it gives this text translation keys, rewrites the code and translates it.

Setup

Set it up in your agent.

Agents on your machine run the server from the npm package, with nothing to host. npx localize-dev init --agent sets it up for Claude Code and Cursor together with the after-edit hook. Lovable, Bolt and v0 connect to the hosted server with an API key.

First, once per machine:npx localize-dev loginCopy

Claude Code

Anthropic's coding agent in the terminal. Add the server from the repository you work in; with --scope project it's saved in.mcp.json for everyone on the team. npx localize-dev init --agent does that and adds the after-edit hook.

1Run claude mcp add in your repository.
2Restart the agent, or reload its MCP servers, so it starts localize.
3Open your repository and ask it something like the prompt below.

Try asking

“Localize src/components/Checkout.tsx into Spanish and French.”

→ localize.localize

claude mcp add localize -- npx -y localize-dev mcp

# Share it with your team through .mcp.json
claude mcp add --scope project localize -- npx -y localize-dev mcp

# Or the server, the after-edit hook and AGENTS.md in one go
npx localize-dev init --agent

Cursor

Cursor reads MCP servers from.cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project. npx localize-dev init --agent writes the project file and a rule for your UI files.

1Add localize to.cursor/mcp.json.
2Restart the agent, or reload its MCP servers, so it starts localize.
3Open your repository and ask it something like the prompt below.

Try asking

“Add Japanese to this app.”

→ localize.add_language

{
  "mcpServers": {
    "localize": {
      "command": "npx",
      "args": ["-y", "localize-dev", "mcp"]
    }
  }
}

Codex

OpenAI's Codex reads MCP servers from its config file, shared by the CLI and the IDE extension.

1Add the [mcp_servers.localize] table to ~/.codex/config.toml.
2Restart the agent, or reload its MCP servers, so it starts localize.
3Open your repository and ask it something like the prompt below.

Try asking

“Before I open the PR, check for hardcoded copy and missing translations.”

→ localize.check

[mcp_servers.localize]
command = "npx"
args = ["-y", "localize-dev", "mcp"]

GitHub Copilot in VS Code

Copilot's agent mode in VS Code reads MCP servers from.vscode/mcp.json in the workspace.

1Add localize to.vscode/mcp.json in your workspace.
2Restart the agent, or reload its MCP servers, so it starts localize.
3Open your repository and ask it something like the prompt below.

Try asking

“Translate the new keys in locales/en.json into every language.”

→ localize.translate

{
  "servers": {
    "localize": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "localize-dev", "mcp"]
    }
  }
}

Devin

Devin, formerly Windsurf, reads MCP servers from ~/.config/devin/mcp_config.json, or.devin/mcp_config.json in the project. The Devin CLI adds one with devin mcp add.

1Add localize to ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows).
2Restart the agent, or reload its MCP servers, so it starts localize.
3Open your repository and ask it something like the prompt below.

Try asking

“Do a dry run of localizing the settings page, then apply it.”

→ localize.localize

{
  "mcpServers": {
    "localize": {
      "command": "npx",
      "args": ["-y", "localize-dev", "mcp"]
    }
  }
}

Gemini CLI

Google's Gemini CLI reads MCP servers from ~/.gemini/settings.json, or.gemini/settings.json in the project.

1Add localize to the mcpServers in settings.json.
2Restart the agent, or reload its MCP servers, so it starts localize.
3Open your repository and ask it something like the prompt below.

Try asking

“Which languages does this app ship, and what's in its glossary?”

→ localize.config

{
  "mcpServers": {
    "localize": {
      "command": "npx",
      "args": ["-y", "localize-dev", "mcp"]
    }
  }
}

Lovable

Lovable's chat connectors can call any remote MCP server. Connect the hosted server with an API key, and Lovable's agent can check and translate the app it's building. The connection is yours alone and never part of the published app.

1In Connectors, choose Add custom, then MCP server, and enter the URL.
2Pick Bearer token or API key, paste your localize.dev API key and click Add server.
3Open your project and ask something like the prompt below. The agent sends the files the tool needs and writes back the files it returns.

Try asking

“Check this app for hardcoded text and tell me what isn't translated.”

→ localize.check

Connectors → Add custom → MCP server

Name            localize
URL             https://uselocalize.dev/api/mcp
Authentication  Bearer token or API key
Key             ldv_live_… (your localize.dev API key)

Bolt

Bolt adds custom MCP servers from its Connectors page. Point one at the hosted server, and Bolt's agent can localize the project open in the editor.

1Click + in the chat, open Connectors (MCP) and choose Custom MCP server. Enter the URL and set the transport to HTTP.
2Pick API key as the authentication and paste your localize.dev API key.
3Open your project and ask something like the prompt below. The agent sends the files the tool needs and writes back the files it returns.

Try asking

“Localize the pricing page into Spanish and German.”

→ localize.localize

Connectors (MCP) → Custom MCP server

Name            localize
URL             https://uselocalize.dev/api/mcp
Transport       HTTP
Authentication  API key
Key             ldv_live_… (your localize.dev API key)

v0

v0 uses custom MCP servers while it generates code. Connect the hosted server, and v0 can add languages to the app it's building and fill in their translations.

1Open + in the prompt form, choose MCPs, then Configure, and enter the URL.
2Pick Bearer Token and paste your localize.dev API key.
3Open your project and ask something like the prompt below. The agent sends the files the tool needs and writes back the files it returns.

Try asking

“Add Japanese to this app.”

→ localize.add_language

Name            localize
URL             https://uselocalize.dev/api/mcp
Authentication  Bearer Token
Key             ldv_live_… (your localize.dev API key)

Hosted server

For agents that can't run a command.

Lovable, Bolt, v0 and other builders that run in the browser can't start npx localize-dev mcp. They can connect to the hosted server instead. It has the same five tools and runs on localize.dev.

1 Add a custom MCP server with the URL https://uselocalize.dev/api/mcp.
2 If the app supports OAuth, choose it and approve the connection on localize.dev. Otherwise put your localize.dev API key in the Authorization header as a bearer token.
3 The agent sends the files a tool needs and writes back the files it returns. They sit in a temporary folder while the call runs and are deleted when it answers.

{
  "mcpServers": {
    "localize": {
      "type": "http",
      "url": "https://uselocalize.dev/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Security and privacy

Only what's needed leaves your machine.

The local server is the CLI, running on your machine, and only what needs translating goes to the API. The hosted server gets the files an agent sends and deletes them when it answers.

Runs locally
The server runs on your machine over stdio, started by your agent. There's nothing to host and no port to open.
Strings, not source
Only the extracted strings go to the API, with their file path and component as context. Whole files are never sent.
Stays in its folder
Every tool works inside the folder the server was started in. An app argument picks one app in a monorepo, never a path outside it.
Nothing committed
Changes land in your working tree. The server never commits or pushes, and tool calls run one at a time.

FAQ

Questions about the MCP server

Which agents does it work with?+

Any MCP client that starts servers over stdio: Claude Code, Cursor, Codex, GitHub Copilot in VS Code, Devin (formerly Windsurf), Gemini CLI and others. The setup is the same command: npx -y localize-dev mcp. Lovable, Bolt, v0 and other builders that run in the browser connect to the hosted server instead.

How does the agent know to localize what it writes?+

npx localize-dev init --agent tells it. The MCP server's instructions, a section in AGENTS.md and a Cursor rule ask it to call localize on the files it changes. In Claude Code, an after-edit hook also checks each file the agent edits and lists any text left untranslated, so the agent fixes it before moving on.

Does the hook use my allowance?+

No. The hook only reads the file, on your machine, with no key or model. Strings count when the agent calls localize and they're translated, as in any run.

Do I need an API key?+

On your machine, check and config don't need one. localize, translate and add_language translate through localize.dev, so they need the key from npx localize-dev login (or LOCALIZE_API_KEY). The hosted server needs a key for every call, though check and config still don't count toward your plan. Translations count toward your plan like any other run.

Do I still need the GitHub Action?+

No, they work on their own. The MCP server localizes while you build, and with init --agent each file as the agent writes it. The Action keeps every push localized and opens a pull request. They read the same localize.config.json and glossary.

Will it commit or push my code?+

The server doesn't: it writes files in your working tree and returns what it changed. What your agent does next is up to you and the agent's own permissions.

Does it work in a monorepo?+

Yes. Every tool takes an app argument, such as apps/web, and works there with that app's config and locale files.

Can I use it without running anything on my machine?+

Yes, through the hosted server at https://uselocalize.dev/api/mcp. Connect it as a Streamable HTTP server, then sign in with OAuth or send your API key as a bearer token. Every call needs a key or a sign-in, but check and config still don't count toward your plan.

Get an API key and add the server.

The free plan covers small apps, and check runs on your machine without a key.

localize.dev

Hosted MCP Server

Documentation

Localize from inside your coding agent.

Five tools, the ones the CLI already has.

localize

check

translate

add_language

config

Ask in plain words. Review the diff.

Translated before the pull request opens

Set it up in your agent.

Claude Code

Cursor

Codex

GitHub Copilot in VS Code

Devin

Gemini CLI

Lovable

Bolt

v0

For agents that can't run a command.

Only what's needed leaves your machine.

Runs locally

Strings, not source

Stays in its folder

Nothing committed

Questions about the MCP server

Get an API key and add the server.