localize.dev

Docs / Agents / Codex

Localize an app with Codex

Add localize.dev to ~/.codex/config.toml so OpenAI Codex can find hardcoded UI text, give it keys and translate it, in the CLI and the IDE extension.

How it works

Codex reads MCP servers from ~/.codex/config.toml, and the CLI and the IDE extension share that file. Add the [mcp_servers.localize] table once and both can call localize.dev's tools.

Codex follows AGENTS.md. npx localize-dev init --agent adds a section there that tells it to call localize after changing UI text and to run npx localize-dev check --changed before it finishes.

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. Add the [mcp_servers.localize] table to ~/.codex/config.toml.
  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.
~/.codex/config.toml
[mcp_servers.localize]
command = "npx"
args = ["-y", "localize-dev", "mcp"]

What you get

Where the server goes
~/.codex/config.toml
Server
localize-dev mcp, started with npx on your machine
Key
The one npx localize-dev login saved
What init --agent adds
The AGENTS.md section with the instructions. Add the server by hand, as above.

Good to know

  • The config file is TOML, not JSON: command and args go under [mcp_servers.localize].
  • Codex gets no after-edit hook. The AGENTS.md section and a check in CI catch text it leaves hardcoded.
  • Start with a read-only prompt: ask Codex to run check before you open a pull request. check and config need no key and never use your allowance.

Try it

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

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

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.