Translate and review prompts

x18n does not call machine translation services. Instead, it writes a translate prompt: plain markdown that describes the work, built from the state of the project. You paste it into an LLM, or an agent follows it. Then x18n checks the results.

Translate prompt

x18n prompt translate --to de

The prompt holds the messages that are missing or empty in de, 50 at a time. A shortened example:

# Translate 2 messages from en to de (German)

## Rules

- Keep every placeholder exactly as written (`{name}`, `@:key`); do not translate their names.
- Keep markup tags and their attributes as they are.
- Match the tone and wording of the existing messages in the target locale.
- Do not translate glossary terms marked "do not translate".
- de uses the plural categories one, other.

## Existing de messages (style reference)

- `app.title`: "My App" → "Meine App"
- `nav.home`: "Home" → "Start"

## Messages

### `nav.about`

- Source: "About"
- Used in `src/App.vue:14`:

  ```
        <a>{{ t('nav.home') }}</a>
        <a v-t="'nav.about'" />
      </nav>
  ```

### `pages.about.title`

- Source: "About us"
- Used in `src/App.vue:16`:

  ```
      </nav>
      <p>{{ $t(`pages.${page}.title`) }}</p>
      <p>{{ $t('app.titel') }}</p>
  ```

## How to write results

- Write a JSON file `{ "de": { "<key>": "<translation>" } }` and run `x18n apply <file> --json`, or run `x18n set <key> --locale de --value <text>` per key.
- Then run `x18n check --only placeholder-mismatch,invalid-syntax --locale de --json` and fix the reported keys.

The parts of the prompt are:

• Rules: the placeholder syntaxes of the project, markup, tone, and the glossary. Presets add notes for their library, for example the plural suffixes of i18next.
• Glossary: the entries of the glossary config, with their translation in the target locale.
• Style reference: up to five existing messages of the target locale, as examples of its tone.
• Messages: the key, the source value, its placeholders, and the code around up to two usages. The code helps with short words such as "Open" or "Save", whose meaning depends on where they appear.
• How to write results: the commands that write and check the translations.

When more messages remain, the prompt says how many, and gives the command for the next batch with --cursor.

Options

Review prompt

x18n prompt review --locale de

The review prompt holds the messages that de already has. It asks the agent to check the meaning, the placeholders, the glossary terms, the tone and the length of each one, and to fix wrong translations with x18n set. Each item shows the source value, its placeholders and the current translation. The prompt accepts the same options as the translate prompt, with --locale in place of --to.

Check the results

Prompts ask for results in the shape that x18n apply reads:

{
  "de": {
    "pages.about.title": "Über uns"
  }
}

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

x18n apply writes nothing if a value drops or adds a placeholder. It lists the problems and exits with code 1. The check then finds syntax errors, such as an ICU plural without an other case.

Where prompts appear

The same builder makes the prompt on every surface:

• the CLI: x18n prompt translate and x18n prompt review,
• the MCP tool x18n_translate_prompt,
• the "Copy translate prompt" button on the locale and key pages of the UI,
• the "Copy Translate Prompt" command and the hover link in VS Code,
• the x18n/translatePrompt request of the language server.

A plugin can add rules and notes with the translatePrompt hook. See Capabilities.