localize.dev

Docs / Agents / Claude Code

Localize an app with Claude Code

Add the localize.dev MCP server and after-edit hook to Claude Code, so new UI text gets translation keys and translations while Claude writes the code.

How it works

Claude Code can write i18n code, but it doesn't know which strings it missed or what your other languages need. With the localize.dev MCP server it calls localize on the files it changed: the text gets keys, the code is rewritten to your i18n library and the new messages are translated into every language the app ships.

npx localize-dev init --agent adds the server to .mcp.json and an after-edit hook to .claude/settings.json. After each edit the hook scans the file Claude touched, and when it finds text that isn't translated it tells Claude to call localize, so nobody has to remember to ask.

Set it up

First run npx localize-dev login in your terminal. It signs you in through the browser and saves a key, which the server reads, so the config below carries none.

  1. Run claude mcp add in your repository.
  2. Restart the agent, or reload its MCP servers, so it starts localize.
  3. Open your repository and ask it something like the prompt below.
terminal
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
Or install the plugin
claude plugin marketplace add ufortstephen/localize-dev
claude plugin install localize-dev@uselocalize

What you get

Where the server goes
.mcp.json
Server
localize-dev mcp, started with npx on your machine
Key
The one npx localize-dev login saved
What init --agent adds
The server in .mcp.json, the after-edit hook in .claude/settings.json and the AGENTS.md section

Good to know

  • The plugin is the other way in. It adds the server and a skill that tells Claude when to use it, and leaves the repository alone.
  • The hook runs npx localize-dev hook after Edit, MultiEdit and Write. It only scans, so it needs no key and uses none of your allowance. Set LOCALIZE_DEV_HOOK=off to pause it.
  • Claude Code reads CLAUDE.md, not AGENTS.md. When the repository has no CLAUDE.md, init --agent creates one that imports AGENTS.md, so both agents follow the same instructions.

Try it

Ask something like this. The agent should call the localize tool.

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

Keep it translated

Text the agent leaves hardcoded still gets caught: npx localize-dev check in CI fails a pull request that adds untranslated copy, and it needs no key.

npx localize-dev check

All agents and the tool reference are on the MCP server page.