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.
- Add the [mcp_servers.localize] table to ~/.codex/config.toml.
- Restart the agent, or reload its MCP servers, so it starts localize.
- Open your repository and ask it something like the prompt below.
[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 loginsaved - What
init --agentadds - The
AGENTS.mdsection with the instructions. Add the server by hand, as above.
Good to know
- The config file is TOML, not JSON:
commandandargsgo under[mcp_servers.localize]. - Codex gets no after-edit hook. The
AGENTS.mdsection and acheckin CI catch text it leaves hardcoded. - Start with a read-only prompt: ask Codex to run
checkbefore you open a pull request.checkandconfigneed 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 checkAll agents and the tool reference are on the MCP server page.