x18n

Reviews

Comment on messages, approve them, request changes and suggest values, in a file that travels with the branch.

A review is a comment on one message: one key in one locale. The comments on a message form its thread. A review has one of four types:

TypeUse it to
commentAsk or note something.
approveSay that the current value is right.
request-changeSay that the value is wrong, and why.
suggestionPropose a better value. Someone then applies it, or resolves it.

The CLI, the VS Code extension, the UI and agents all read and write the same reviews.

The review file

Reviews live in .x18n/reviews.yml. Commit it: reviews then travel with the branch and show in pull requests.

.x18n/reviews.yml
# yaml-language-server: $schema=https://x18n.dev/schema/reviews.json
x18n: 1
threads:
  auth:login.title:
    de:
      - id: r8f2k1
        type: request-change
        author:
          name: Ada
          email: ada@example.com
        time: 2026-10-15T09:12:00.000Z
        text: Too formal, use "Anmelden".
      - id: k3m9q2
        type: suggestion
        time: 2026-10-15T09:13:00.000Z
        suggestion: Anmelden
  • Keys and locales are sorted, so edits from two branches merge well.
  • Each review has a short random id. Commands such as x18n review resolve <id> take it.
  • A resolved review stays in the file with resolved: true.
  • An approval records the value it approved. When the value changes later, the approval is stale, and the thread shows "approved, changed since".
  • When x18n renames a key, its threads move with it. When x18n deletes a key, its threads go too.

State of a thread

The open comments decide the state of a thread. The last open approval or change request wins: an approval after a change request clears it. Without one, an open suggestion makes the thread "suggestion", and an open comment makes it "comments". A thread whose comments are all resolved has no state.

The review-changes-requested check reports each message whose state is "changes requested". Its quick fix resolves the request.

Fresh translations

When the project has a review file, every value that x18n writes into a target locale also records a hash of the source value in the sources section. While the source value stays the same, the translation is up to date, even when git says it is older than the source. See stale-translation. x18n review mark-fresh <key> records the current source value without a change, for a translation that is still right after the source changed.

Who writes a review

The author is review.author in the config, else the git user.name and user.email. The CLI also takes --author "Name <email>".

x18n.config.ts
import { defineConfig } from '@x18n/core'

export default defineConfig({
  review: {
    // A different file, or `enabled: false` to turn reviews off.
    file: '.x18n/reviews.yml',
    author: { name: 'Translation team' },
  },
})

Coming from i18n-ally

x18n migrate i18n-ally converts .vscode/i18n-ally-reviews.yml into .x18n/reviews.yml. See Migration.

Monorepos

One root config with projects, each project with its own locales and its own config.

CLI and x18n check

Check locale files like tsc, read and change keys from the terminal, and pick a reporter for CI.