# Translations

> Compare and edit locale message files with the Dev Tool's Translations page, or directly as JSON.

*Canonical: https://makerkit.dev/docs/tanstack-drizzle/dev-tools/translations*

---

Locale messages are plain JSON files. You can edit them directly, compare them side-by-side in the Dev Tool's **Translations** page, or manage them through the MCP server tools.

## Editing in the Dev Tool

The Dev Tool's **Translations** page (`/translations`) renders a side-by-side matrix of every translation key across your locales for a chosen namespace. Missing keys and values that differ from the base locale are highlighted, and every cell is editable — changes are debounced and written straight back to the JSON message files. Open it from the sidebar, or run `pnpm --filter dev-tool dev` and visit [http://localhost:3010/translations](http://localhost:3010/translations).

## Where Messages Live

Locale files live under the `@kit/i18n` package, one directory per locale, one JSON file per namespace:

```text
packages/i18n/src/messages/<locale>/*.json
```

For example `packages/i18n/src/messages/en/` contains `common.json`, `auth.json`, `account.json`, `billing.json`, and the other namespaces.

## Editing Translations

Edit the JSON files directly. Keys may be nested; the app reads them via the message registry in `packages/i18n/src/messages/index.ts`.

## Adding a Language

Adding a locale requires two edits in `@kit/i18n`:

1. Add the locale to the `locales` array in `packages/i18n/src/config.ts`.
2. Create the matching message files under `packages/i18n/src/messages/<locale>/` and register them in `packages/i18n/src/messages/index.ts` (the registry statically imports each locale's namespaces).

The default locale is driven by the `VITE_DEFAULT_LOCALE` env var. See [MCP Server](../installation/mcp-server) for the AI tooling below.

## MCP Translation Tools

The MCP server registers deterministic file tools for translations (implementation in `tooling/mcp-server/src/tools/translations/`):

- `kit_translations_list` — list translations across locales and namespaces
- `kit_translations_stats` — coverage statistics per locale
- `kit_translations_update` — set a single key's value
- `kit_translations_add_namespace` / `kit_translations_remove_namespace`
- `kit_translations_add_locale` / `kit_translations_remove_locale`

These tools read and write the JSON message files. They do not call any external AI service, so no `OPENAI_API_KEY` (or similar) is required. If you add a locale via the MCP tools, still register it in `packages/i18n/src/config.ts` and `messages/index.ts` for the app to load it.