CLI and x18n check

The x18n CLI is for humans, CI and agents. Every command prints human output by default, and the JSON contract with --json. The CLI reference lists every command and option.

Run x18n with no command to see the status of the project and the main commands.

x18n check

x18n check runs every check on every project and reports the diagnostics. It is to i18n what tsc --noEmit is to types:

x18n check

src/App.vue:17:15
 ERROR  "app.titel" is not defined in en.  missing-key
16 │   <main>
17 │     <p>{{ $t('app.titel') }}</p>
   │               ~~~~~~~~~
18 │   </main>

src/locales/de.json:8:6
 WARNING  "nav.about" is empty in de.  empty-translation
7 │   "nav": {
8 │     "about": ""
  │      ~~~~~
9 │   }

✖ 1 error  ⚠ 1 warning  2 files

Each problem starts with the path, the line and the column. The next line has the severity, the message and the check id. A code frame follows, with one line of context on each side. The last line counts the errors, the warnings and the files. Paths are relative to the current directory, so editors and terminals can open them.

Options

To change the severity of a check for every run, use checks in the config. See Checks.

Exit codes

Exit codes lists the codes of every command.

Reporters

A reporter turns diagnostics into text. Pick one or more with --reporter:

--reporter and --output are repeatable. The first --output belongs to the first --reporter, the second to the second, and so on. A reporter without an --output prints to stdout:

x18n check --reporter markdown --output summary.md --reporter pretty

This command writes the markdown report to summary.md and prints the pretty output. See CI for workflow examples.

Read keys and usages

A key glob uses * inside one segment and ** across segments: x18n keys "pages.**".

List commands page their output. --limit <n> sets the page size. The output ends with a --cursor value for the next page, and the JSON output has it as nextCursor:

x18n keys --missing de --limit 50
x18n keys --missing de --limit 50 --cursor 50

Change keys

Do not edit locale files by hand. These commands keep the format, the indent, the key style and the order of each file, and they check placeholders:

A rename or delete of a parent key changes every key under it. x18n rename pages screens moves pages.home.title to screens.home.title, and updates prefix usages such as t(`pages.${id}.title`). A rename to a key that exists stops with X18N4002.

x18n apply refuses values whose placeholders differ from the source value, and writes nothing. It lists the rejected values and exits with code 1. Fix them, or pass --force to write them anyway.

Every command that writes files accepts --dry-run. It prints the changes as a small diff and writes nothing:

x18n rename app.title app.heading --dry-run

edit src/locales/de.json
-     "title": "Meine App",
+     "heading": "Meine App",
edit src/locales/en.json
-     "title": "My App",
+     "heading": "My App",
edit src/App.vue
- const title = t('app.title')
+ const title = t('app.heading')

If a change needs a decision, such as the file for a new key, x18n asks in a terminal. --yes accepts the default answers. See Plan and decision.

Extract hard strings

x18n extract finds hard-coded strings in source files and turns them into keys. Each candidate has a proposed key, a message and the replacement code.

• x18n extract --list prints the candidates.
• In a terminal, x18n extract asks for each string: accept the proposed key, type another key, skip it, or stop.
• x18n extract --yes extracts every candidate with its proposed key.
• x18n extract --plan plan.json writes the candidates to a file. Edit the keys, remove the items that you do not want, then run x18n extract --apply plan.json.

Pass files or globs to limit the search: x18n extract src/components/**. Files that users never see are never scanned: tests, fixtures, mocks, stories, configs and type declarations, by the conventions of common languages. For example *.test.ts, *_test.go, test_*.py, *_spec.rb, *Test.java, *.stories.tsx, vite.config.ts, *.d.ts, and directories such as test/, tests/, spec/, e2e/, fixtures/ and __tests__/. Control comments, in any comment syntax, skip more:

The same rules apply to the hard-string check. The extract options of the config set the key style and the strings to ignore. The presets add the replacement code for their library. See Extraction templates.

Global options

Output rules

• Results go to stdout. Logs and progress go to stderr, so x18n keys > keys.txt works.
• Colors appear only in a terminal. x18n honors NO_COLOR and FORCE_COLOR.
• With --json, stdout is one JSON document, also when the command fails.