# Lingui CLI

The `@lingui/cli` tool provides the `lingui` command which allows you to extract messages from source files into message catalogs, check them, and compile these catalogs for production use.

## Installation[​](#installation "Direct link to Installation")

1. Install `@lingui/cli` as a development dependency:

   * npm
   * Yarn
   * pnpm

   ```
   npm install --save-dev @lingui/cli
   ```

   ```
   yarn add --dev @lingui/cli
   ```

   ```
   pnpm add --save-dev @lingui/cli
   ```

2. Add the following scripts to your `package.json`:

   package.json

   ```
   {

     "scripts": {

       "extract": "lingui extract",

       "compile": "lingui compile"

     }

   }
   ```

tip

If you use TypeScript, you can add the `--typescript` flag to the `compile` script to produce compiled message catalogs with TypeScript types:

package.json

```
{

  "scripts": {

    "compile": "lingui compile --typescript"

  }

}
```

## Global Options[​](#global-options "Direct link to Global Options")

### `--config <config>`[​](#--config-config "Direct link to --config-config")

Path to the configuration file. If not set, the default file is loaded as described in the [Configuration](https://lingui.dev/ref/conf.md) reference.

## Commands[​](#commands "Direct link to Commands")

### `extract`[​](#extract "Direct link to extract")

```
lingui extract [files...]

        [--clean]

        [--overwrite]

        [--format <format>]

        [--locale <locale, [...]>]

        [--convert-from <format>]

        [--verbose]

        [--watch [--debounce <delay>]]

        [--workers <n>]
```

The `extract` command scans source files to locate and extract messages, generating separate message catalogs for each language.

This process involves:

1. Extracting messages from files based on the `include` and `exclude` settings in the [`catalogs`](https://lingui.dev/ref/conf.md#catalogs) section of the configuration file.
2. Merging the newly extracted messages with any existing message catalogs.
3. Updating and saving the message catalogs.
4. Printing extraction statistics for each language, including the total number of messages and any missing translations.

tip

Refer to the [Message Extraction](https://lingui.dev/guides/message-extraction.md) guide to learn more about this process and the options available.

#### `files`[​](#extract-files "Direct link to extract-files")

Filter source paths to extract messages only from specific files. For example:

```
lingui extract src/components
```

This command extracts messages from files within the `src/components/**/*` path. You can also pass multiple paths for extraction.

This feature is useful when you want to extract messages from files that are staged for commit. For example, you can use husky to automatically extract messages from staged files before committing:

package.json

```
{

  "husky": {

    "hooks": {

      "pre-commit": "lingui extract $(git diff --name-only --staged)"

    }

  }

}
```

#### `--clean`[​](#extract-clean "Direct link to extract-clean")

By default, the extract command merges messages extracted from source files with existing message catalogs, ensuring that translated messages are preserved and not accidentally lost.

However, over time, some messages may be removed from the source code. You can use the following option to clean up your message catalogs and remove obsolete messages.

#### `--overwrite`[​](#extract-overwrite "Direct link to extract-overwrite")

Update translations for [`sourceLocale`](https://lingui.dev/ref/conf.md#sourcelocale) from source.

#### `--format <format>`[​](#extract-format "Direct link to extract-format")

Extract message catalogs to the specified file format (see the [`format`](https://lingui.dev/ref/conf.md#format) option for more details).

#### `--locale <locale, [...]>`[​](#extract-locale "Direct link to extract-locale")

Extract data for the specified locales only.

#### `--convert-from <format>`[​](#extract-convert-from "Direct link to extract-convert-from")

Convert message catalogs from the previous format (see the [`format`](https://lingui.dev/ref/conf.md#format) option for more details).

#### `--verbose`[​](#extract-verbose "Direct link to extract-verbose")

Print additional information.

#### `--watch`[​](#extract-watch "Direct link to extract-watch")

Enable watch mode to monitor changes in files located in the paths specified in the configuration file or in the command itself. Note that this feature is intended for development use only, as it does not remove obsolete translations.

#### `--debounce <delay>`[​](#extract-debounce "Direct link to extract-debounce")

Delay the extraction by `<delay>` milliseconds, bundling multiple file changes together.

#### `--workers`[​](#extract-workers "Direct link to extract-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

Worker threads can significantly improve performance on large projects. However, on small projects they may provide little benefit or even be slightly slower due to thread startup overhead.

A larger worker pool also increases memory usage. Adjust this value for your project to achieve the best performance.

### `extract-template`[​](#extract-template "Direct link to extract-template")

```
lingui extract-template [--verbose]
```

This command extracts messages from your source files and generates a `.pot` template file. Any artifacts created by this command can be safely ignored in version control.

If your message catalogs are not synchronized with the source and some messages are missing, the application will fallback to the template file. Running this command before building the application is recommended to ensure all messages are accounted for.

#### `--verbose`[​](#extract-template-verbose "Direct link to extract-template-verbose")

Print additional information.

### `compile`[​](#compile "Direct link to compile")

```
lingui compile

    [--strict]

    [--format <format>]

    [--verbose]

    [--typescript]

    [--namespace <namespace>]

    [--watch [--debounce <delay>]]

    [--workers <n>]

    [--output-prefix <prefix>]
```

Once you have all the catalogs ready and translated, you can use this command to compile all the catalogs into minified JS/TS files. It compiles message catalogs located in the [`path`](https://lingui.dev/ref/conf.md#catalogs) directory and generates minified JavaScript files. The resulting file is a string that is parsed into a plain JS object using `JSON.parse`.

The output looks like this:

```
export const messages = JSON.parse(`{

// object with keys (translation ids) and values (translations)

}`);
```

Messages added to the compiled file are collected in a specific order:

1. Translated messages from the specified locale.
2. Translated messages from the fallback locale for the specified locale.
3. Translated message from default fallback locale.
4. Message key.

It is also possible to merge the translated catalogs into a single file per locale by specifying [`catalogsMergePath`](https://lingui.dev/ref/conf.md#catalogsmergepath) in the configuration.

tip

The compiled files can be safely ignored by your version control system, since these files must be created each time you deploy to production. We recommend you to create the compiled catalogs in CI as part of your deployment process. Always remember to **use compiled catalogs** in deployments.

.gitignore

```
your_locale_folder/**/*.js
```

#### `--overwrite`[​](#compile-overwrite "Direct link to compile-overwrite")

Overwrite source locale translations from source.

#### `--strict`[​](#compile-strict "Direct link to compile-strict")

Fail if the compiled catalog still has missing translations after `fallbackLocales` are applied, or if message compilation produces errors.

This preserves the default validation behavior used by Lingui 6. The compiled output uses the normal fallback resolution behavior regardless of strict mode, although catalogs for locales that fail strict validation may not be emitted.

#### `--format <format>`[​](#compile-format "Direct link to compile-format")

Format of message catalogs (see the [`format`](https://lingui.dev/ref/conf.md#format) option for more details).

#### `--verbose`[​](#compile-verbose "Direct link to compile-verbose")

Print additional information.

#### `--namespace`[​](#compile-namespace "Direct link to compile-namespace")

Specify the namespace for compiled message catalogs (see also [`compileNamespace`](https://lingui.dev/ref/conf.md#compilenamespace) for global configuration).

#### `--typescript`[​](#compile-typescript "Direct link to compile-typescript")

Is the same as using [`compileNamespace`](https://lingui.dev/ref/conf.md#compilenamespace) with the value "ts". Generates a `{compiledFile}.ts` file and the exported object is typed using TS.

#### `--watch`[​](#compile-watch "Direct link to compile-watch")

Watch mode. Watches only for changes in locale files in your defined locale catalogs. For example, `locales\en\messages.po`.

#### `--debounce <delay>`[​](#compile-debounce "Direct link to compile-debounce")

Delays compilation by `<delay>` milliseconds to avoid multiple compilations for subsequent file changes.

#### `--workers`[​](#compile-workers "Direct link to compile-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

Worker threads can significantly improve performance on large projects. However, on small projects they may provide little benefit or even be slightly slower due to thread startup overhead.

A larger worker pool also increases memory usage. Adjust this value for your project to achieve the best performance.

#### `--output-prefix <prefix>`[​](#compile-output-prefix "Direct link to compile-output-prefix")

Adds a custom string to the beginning of compiled message catalogs (a header/prefix). By default, Lingui adds `/*eslint-disable*/` to prevent linters from reporting issues in generated files.

Use this option for other tools that rely on header directives (e.g., different linters, coverage tools, or formatters). Provide the full prefix exactly as it should appear in the output.

**Default value:** `/*eslint-disable*/`

**Examples:**

```
# For Oxlint

lingui compile --output-prefix "/*oxlint-disable*/"



# For Biome

lingui compile --output-prefix "/*biome-ignore lint: auto-generated*/"



# For no prefix at all

lingui compile --output-prefix ""
```

The generated file header will look like:

```
/*your-prefix-here*/ export const messages = JSON.parse("{}");
```

### `check`[​](#check "Direct link to check")

```
lingui check <command>
```

The `check` command is a namespace for validation subcommands. Running `lingui check` without a subcommand prints help and exits without running any validation.

These subcommands are useful in CI when you want to fail fast on stale catalogs or missing translations but do not need compilation artifacts yet.

#### `sync`[​](#sync "Direct link to sync")

```
lingui check sync

    [--locale <locale, [...]>]

    [--clean]

    [--overwrite]

    [--verbose]

    [--workers <n>]
```

Checks whether locale catalogs are synchronized with the current source code. It fails if the expected catalog differs from the existing catalog.

This validation checks locale catalogs only. It does not validate `.pot` / template freshness.

#### `missing`[​](#missing "Direct link to missing")

```
lingui check missing

    [--locale <locale, [...]>]

    [--mode <resolved|catalog>]

    [--verbose]

    [--workers <n>]
```

Checks whether locale catalogs have missing translations. By default, this validation uses `resolved` mode, which matches `lingui compile --strict`: translations are considered missing only if they are still missing after `fallbackLocales` are applied.

Use `--mode catalog` to fail when the target locale catalog itself has missing translations before `fallbackLocales` are applied. This command performs validation without compiling catalogs.

#### `sync --locale <locale, [...]>`[​](#check-sync-locale "Direct link to check-sync-locale")

Only check the specified locales when running `lingui check sync`.

#### `sync --clean`[​](#check-sync-clean "Direct link to check-sync-clean")

Before comparing catalogs, remove obsolete messages from the expected catalog. Existing obsolete messages are still reported as out of sync.

#### `sync --overwrite`[​](#check-sync-overwrite "Direct link to check-sync-overwrite")

When running the `sync` validation, mirror `lingui extract --overwrite`. Source locale translations are expected to be overwritten from source messages.

#### `sync --verbose`[​](#check-sync-verbose "Direct link to check-sync-verbose")

Print detailed findings for each failing `sync` validation.

#### `sync --workers`[​](#check-sync-workers "Direct link to check-sync-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

#### `missing --locale <locale, [...]>`[​](#check-missing-locale "Direct link to check-missing-locale")

Only check the specified locales when running `lingui check missing`.

#### `missing --mode <resolved|catalog>`[​](#check-missing-mode "Direct link to check-missing-mode")

Controls how missing translations are detected when running `lingui check missing`.

* `resolved` (default): fail only if a translation is still missing after `fallbackLocales` are applied.
* `catalog`: fail if the target locale catalog itself has missing translations before `fallbackLocales` are applied.

#### `missing --verbose`[​](#check-missing-verbose "Direct link to check-missing-verbose")

Print detailed findings for each failing `missing` validation.

#### `missing --workers`[​](#check-missing-workers "Direct link to check-missing-workers")

Number of worker threads to use (default: CPU count - 1, capped at 8; on 1-2 core machines, all cores). Pass `--workers 1` to disable worker threads and run everything in a single process

## Configuring the Source Locale[​](#configuring-the-source-locale "Direct link to Configuring the Source Locale")

One limitation of checking for missing translations is that the English message catalog typically does not require translations since our source code is in English. This issue can be resolved by configuring the [`sourceLocale`](https://lingui.dev/ref/conf.md#sourcelocale) in the configuration file.

## Compiling Catalogs in CI[​](#compiling-catalogs-in-ci "Direct link to Compiling Catalogs in CI")

If you're using CI, it's a good idea to add the `compile` command to your build process. Alternatively, you can also use a [Webpack loader](https://lingui.dev/ref/loader.md), [Vite plugin](https://lingui.dev/ref/vite-plugin.md) or [Metro transformer](https://lingui.dev/ref/metro-transformer.md).

Depending on your localization setup, you might also want to run the `extract` command in CI and upload the extracted messages to a [translation service](https://lingui.dev/tools/introduction.md).

## See Also[​](#see-also "Direct link to See Also")

* [Lingui Configuration](https://lingui.dev/ref/conf.md)
* [Message Extraction](https://lingui.dev/guides/message-extraction.md)
* [Catalog Formats](https://lingui.dev/ref/catalog-formats.md)
* [Custom Extractor](https://lingui.dev/guides/custom-extractor.md)