MCP localization with TransLocale

Connect your assistant

Add this remote MCP server URL to your assistant. Sign in in the browser, choose a project, and approve the access you need. The client must support remote HTTP MCP, OAuth browser sign-in, and token renewal. Clients that cannot register automatically can use a client ID from assistant setup.

https://translocale.io/mcp/authorized

• Set up an assistant connection

An existing project credential can connect to https://translocale.io/mcp with an Authorization: Bearer header. Keep authoring credentials in trusted developer tools or CI, outside browser and mobile application bundles. Public planning and validation tools on that endpoint do not require a project credential.

Optional: install the Codex or Claude Code skill

Run one command from your application directory. The skill helps the assistant choose a framework package and inspect local catalogs. Connecting the assistant to MCP is a separate step; local setup and checks work without it.

npm exec --package=@translocale/cli -- translocale skills install --agent codex --api https://translocale.io
# Or, for Claude Code:
npm exec --package=@translocale/cli -- translocale skills install --agent claude --api https://translocale.io

Add --global to install for your user. Existing customized skills are preserved. Use skills status, skills update, and skills remove with the same agent and scope; customized updates or removal require --backup.

Check files before translating

Start with read-only checks. plan_translation inspects a source file, validate_translations compares supplied source and target files, and catalog_health reports supplied catalog issues. These tools do not change files or start paid translation jobs. Freshness checks need the relevant source snapshots; missing snapshots produce an unknown freshness result.

Use TransLocale to inspect my source and French catalogs. Report missing keys and placeholder mismatches. Do not translate, edit files, or publish anything.

For a small flat JSON comparison, ask your assistant to call validate_translations with the following input. The target changes the name placeholder to firstName; correct it to name before accepting the translation.

{
  "source": "{\"welcome\":\"Hello, {name}\"}",
  "target": "{\"welcome\":\"Bonjour, {firstName}\"}",
  "format": "json"
}

• Try the source file checker

Plan and approve a capped translation

Use plan_project_translation to inspect a saved project’s proposed job and estimated usage. Confirm the source, target languages, and maximum character allowance before start_translation. The start request needs translation permission and an explicit maxCharacters cap. Use the project version returned by the plan as expectedProjectVersion.

Plan translating my selected catalog into French. Show the character estimate and any issues. Wait for my approval before starting a job, with a cap of 1,000 characters.

Review generated wording before exporting a saved revision. For an uncertain start response, retry the same idempotency key and exact request instead of creating a second job. Discovery, normal builds, and validation should not initiate translation.

• Translation and review workflow
• Current pricing and allowances

Review before publishing wording

MCP supports create_release, get_release_channel, update_release_channel, and get_release_channel_history. An owner with write access can preview a release or channel change and apply its returned plan hash after approval. Test wording in Preview before promoting it to Production. New keys or changed placeholders require a compatible application build.

• Flutter OTA setup
• DartNative setup

Connection and permission troubleshooting

If the assistant requests a client ID, register its callback through assistant setup. A 401 response from the authorized endpoint before sign-in is the OAuth challenge. If an existing connection stops working, check its project permissions and sign in again; signing out of the authorizing browser session ends its access.

npm exec --package=@translocale/cli -- translocale doctor --mcp --api https://translocale.io --json

doctor --mcp checks public connection discovery; it does not prove the assistant is signed in. CLI credentials and assistant OAuth are separate. Use the same selected project for planning and translation. A read-only connection cannot start jobs or publish releases.