MCP tools

x18n mcp (stdio) and x18n ui (HTTP at /__mcp) serve these tools. MCP explains how to connect an agent.

Each tool takes one object. A ? after a field name marks an optional field. The safety level tells the agent what a call does: read changes nothing, action writes files, destructive can remove data and asks for confirm: true.

x18n_status

Safety: read

Overview of the i18n project: locales with translation coverage, counts of keys, resources and usages, diagnostics by check, and detected presets. Call it first to learn project names, the source locale and locale codes.

x18n_keys

Safety: read

List message keys, paged. Filter by missing locale (keys to translate), unused (keys no code uses), namespace or a key glob. Pass values: true to get the value per locale. Continue with cursor: nextCursor.

x18n_get

Safety: read

One key: its value in every locale with file and line, locales where it is missing, usages in code with a few lines of context, and diagnostics. Check a key with it before creating or renaming one.

x18n_usages

Safety: read

Usages in code, paged: of one key (usages with a computed key under a prefix of it are marked possible), of one file (path), or all. Each usage has file, line, column and a code snippet.

x18n_check

Safety: read

Run the checks (missing translations, placeholder mismatches, invalid syntax, unused and undefined keys, ...) and return diagnostics, paged. After writing messages, call it with only: ["placeholder-mismatch", "invalid-syntax"] and fix what it reports.

x18n_translate_prompt

Safety: read

Instructions for translating missing messages into a locale: rules, glossary, style examples and the items with usage context, as markdown. Follow it, then write the results with x18n_set_messages. It says how many items remain and the cursor for the next batch.

x18n_set_messages

Safety: action

Set many messages at once: messages is { "<locale>": { "<key>": "<value>" } }, the same shape as x18n apply. Files keep their format, key style and order. When a value drops or adds placeholders compared to the source value, nothing is written and problems lists them (applied: false); fix the values, or pass force: true.

x18n_rename_key

Safety: destructive

Rename a key (or every key under a parent) in all locales, and its usages in code unless usages: false. Without confirm it returns the plan (files to change, decisions, warnings); call again with confirm: true to apply it.

x18n_delete_key

Safety: destructive

Delete a key (or every key under a parent) in all locales, or only in locales. Code is not changed. Without confirm it returns the plan; call again with confirm: true to apply it.

x18n_extract_plan

Safety: read

Find hard-coded strings in source files and propose a key, a message and a code replacement for each. Review the items (edit keys, drop items you do not want), then pass them to x18n_extract_apply.

x18n_extract_apply

Safety: action

Apply extraction items from x18n_extract_plan: adds the messages to the source locale and rewrites the code. Fails when a file changed since the plan was made; plan again then.