Getting started

x18n needs Node.js 22 or later. Run the commands in this page in the root directory of your project.

Try it without a config

x18n works without a config file. It reads i18n-ally settings when the project has them, detects the i18n library from package.json (including the workspace packages of a monorepo), and looks for locale files in directories such as locales, i18n, lang or messages.

1. Show what x18n found:

   pnpx @x18n/cli

   The output lists the locales with their coverage, and the counts of resources, keys and usages.

2. Check the project:

   pnpx @x18n/cli check

x18n check prints each problem with its file, line and column:

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:4:6
 ERROR  "app.greeting" in de has different placeholders than en: missing name.  placeholder-mismatch
3 │     "title": "Spielwiese",
4 │     "greeting": "Hallo",
  │      ~~~~~~~~
5 │     "footer": "Gemacht mit x18n"

src/locales/en.json:18:4
 WARNING  "unused" is not used.  unused-key
17 │   "app.save": "Save",
18 │   "unused": "Nobody uses me",
   │    ~~~~~~
19 │   "app.title": "Welcome back"

✖ 2 errors  ⚠ 1 warning  3 files

The command exits with code 1 when it finds errors. Warnings do not fail it. See Checks for every check.

If x18n finds the wrong files, or none, run pnpx @x18n/cli doctor. It shows the detected presets, the resources that each locale finder found, and the source files that each scanner read.

Install

Add x18n to the dev dependencies of the project:

pnpm add -D @x18n/cli

npm install -D @x18n/cli

yarn add -D @x18n/cli

The TS config imports defineConfig from x18n, so the package must be installed in the project before you write an x18n.config.ts.

Write a config

x18n init detects the setup and writes x18n.config.ts:

pnpx @x18n/cli init

import { defineConfig } from '@x18n/core'

// Detected presets: vue-i18n. They apply automatically.
export default defineConfig({
  sourceLocale: 'en',
  resources: [
    {
      pattern: 'src/locales/{locale}.{ext}',
    },
  ],
})

A project that has no package.json, such as a PHP or Ruby project, can use YAML or JSON instead. These files need no installed package:

pnpx @x18n/cli init --format yml

x18n init refuses to replace an existing config. Pass --force to replace it. See Configuration for every way to change the setup.

Run the check in CI

Add a script to package.json:

{
  "scripts": {
    "i18n:check": "x18n check"
  }
}

Then run pnpm i18n:check (or npm run i18n:check) in your CI. CI shows a GitHub Actions workflow that puts the problems on the lines of a pull request.

Next steps

• Concepts: the names that x18n uses, such as resource, key and usage.
• CLI and x18n check: read, add, rename and delete keys from the terminal.
• VS Code: see translations in place in the editor.
• Agent workflows: let a coding agent translate and clean up messages.
• Migration from i18n-ally: convert existing i18n-ally settings.