Agent workflows

Coding agents are first-class users of x18n. An agent uses the same CLI as a human, with --json. It never edits locale files by hand, and it checks its own work with x18n check.

An agent can work with x18n in three ways:

• The CLI with --json. Every command prints the JSON contract.
• The MCP server, with tools for the same tasks.
• The shipped skills, which teach an agent to set up x18n, fix what x18n check reports, and run the loops on this page.

Rules for agents

• Do not edit locale files directly. Use x18n set, x18n apply, x18n rename and x18n delete. They keep the format, the key style, the order and the placeholders of each file.
• Before you use a key in code, find out whether it exists: x18n get <key> --json.
• Keep every placeholder of the source value, such as {name}, {{count}}, %s or @:key.
• Read the JSON output, not the human output.
• For renames and deletes, run with --dry-run first and read the plan.

The JSON output

Every command prints one document with the same envelope:

{
  "x18n": 2,
  "command": "keys",
  "data": {},
  "diagnostics": [],
  "errors": []
}

data holds the result. errors holds the errors, each with its code in name, the reason in why, a fix and a docs link. The exit code tells the agent what to do next:

Check the project

x18n status --json
x18n check --json

x18n status lists the projects, the locales with their coverage and the counts of diagnostics. x18n check lists every diagnostic.

Add a key while coding

x18n get settings.title --json
x18n set settings.title --value "Settings" --json

Without --locale, x18n set writes the source locale. Then use the key in code, for example t('settings.title'). To see which locales still lack keys, run x18n keys --missing de --json --limit 50.

Translate missing messages

x18n prompt translate --to de --limit 50

The translate prompt lists the messages to translate, with rules and context. The agent writes the results as { "de": { "<key>": "<translation>" } } to a file, then applies and checks them:

x18n apply translations.json --json
x18n check --only placeholder-mismatch,invalid-syntax --locale de --json

x18n apply refuses values whose placeholders differ from the source value, and lists them in data.rejected. The agent fixes them and applies again. If the prompt says that more keys remain, the agent continues with --cursor <nextCursor>.

Review translations

x18n prompt review --locale de --limit 50

The review prompt asks the agent to compare existing translations with the source and the glossary. The agent fixes wrong values with x18n set <key> --locale de --value <text> --json, and lists what it changed.

Clean up

x18n keys --unused --json
x18n delete old.key --dry-run --json
x18n delete old.key --json

A key with a prefix usage is not unused, so x18n keys --unused does not list keys that computed keys can reach.

Rename keys

x18n rename home.title home.heading --dry-run --json
x18n rename home.title home.heading --json
x18n rename pages screens --json

A rename changes every locale and every usage in code. A rename of a parent key, such as pages, moves every key under it. A rename to a key that exists stops with exit code 1.

Extract hard-coded strings

x18n extract --list --json
x18n extract --plan extract-plan.json
x18n extract --apply extract-plan.json --json

The agent edits the keys in the plan file, and removes the items it does not want, before it applies the plan.

Large projects

List commands take --limit and return nextCursor. Pass it as --cursor to get the next page. This keeps the output of a large project small enough for the context of an agent:

x18n keys --json --limit 100
x18n keys --json --limit 100 --cursor 100

In a monorepo, x18n status --json lists several projects. Pass --project <name> to commands that write files.