# MCP localization with TransLocale

Bring translations from your AI assistant into TransLocale. Validate and review wording, then publish compatible updates to your app. Hosted AI translation is optional.

Canonical page: https://translocale.io/docs/mcp

## 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.

Remote MCP server:

```text
https://translocale.io/mcp/authorized
```

- [Set up an assistant connection](https://translocale.io/settings/assistants)

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.

Install for your assistant:

```bash
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.

Starter prompt:

```text
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.

validate_translations input:

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

- [Try the source file checker](https://translocale.io/app)

## Bring your agent’s translations

Your agent can generate translations with its own model. Read the project context and source catalog, preserve the framework’s placeholders and plural rules, then use validate_translations to check the resulting files. This route does not require start_translation or a TransLocale translation allowance.

Use import_catalogs to preview source and target files mapped to the intended catalog and configured languages. Inspect conflicts and validation results, then apply the returned plan hash within the requested scope. Imported wording stays unreviewed unless approval was explicitly requested. Use edit_catalog_translation to review and approve saved wording before preparing a release.

Use your agent’s model:

```text
Translate the French catalog using your own model and our project glossary. Validate it, then preview importing it into TransLocale. Show me the wording and conflicts before applying. Do not start a TransLocale translation job or publish a release.
```

- [Connect your app and publish updates](https://translocale.io/docs#deliver-updates-to-your-app)

## Optional: use TransLocale’s AI 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 first:

```text
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](https://translocale.io/docs#translate-a-project)
- [Current pricing and allowances](https://translocale.io/pricing)

## 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](https://translocale.io/integrations/flutter#ota)
- [DartNative setup](https://translocale.io/integrations/dartnative)

## 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.

Check public MCP discovery:

```bash
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.