eslint-plugin-lingui

0.13.1 verified Sat Apr 25 auth: no javascript

ESLint plugin for Lingui, the internationalization (i18n) framework for JavaScript/TypeScript. Current stable version 0.13.1, released July 2024, with a steady monthly release cadence. It enforces best practices and catches common mistakes in Lingui usage: ensuring translations are called inside functions, no expressions inside message templates, no nested <Trans> components, consistent plural format, and more. Provides both recommended and custom configurations for flat and legacy ESLint configs. Key differentiator: purpose-built for Lingui, with deep integration into its macro system and JSX patterns, unlike generic i18n linters.

Common errors

error Error: Failed to load plugin 'lingui' declared in 'extends' ...: Cannot find module 'eslint-plugin-lingui' ↓

cause eslint-plugin-lingui not installed or ESLint is global and plugin is local.

fix

Install the plugin locally: npm install --save-dev eslint-plugin-lingui

error ESLint couldn't determine the plugin 'lingui' uniquely. This may be due to plugin loading outside the eslintrc. ↓

cause Both legacy and flat config are present, causing conflict.

fix

Remove .eslintrc.* and use only eslint.config.js.

error TypeError: Cannot read properties of undefined (reading 'error') ↓

cause Flat config rule severity is a string but passed as array without first element.

fix

Use 'error' string or ['error', options].

Warnings

breaking From v0.12.0, TypeScript must be installed as a peer dependency for TypeScript-project support. ↓

fix Run 'npm install --save-dev typescript' if you use TypeScript.

deprecated The legacy .eslintrc config format (extends: ['plugin:lingui/recommended']) is deprecated in favor of flat config (eslint.config.js). ↓

fix Migrate to flat config: import pluginLingui from 'eslint-plugin-lingui' and use pluginLingui.configs['flat/recommended'].

gotcha The 'no-unlocalized-strings' rule is not included in the recommended set by default; it must be explicitly configured. ↓

fix Add 'lingui/no-unlocalized-strings': 'error' to your rules.

gotcha Using the plugin with ESLint < 8.37 is not supported and may cause errors. ↓

fix Upgrade ESLint to ^8.37.0 || ^9 || ^10.

Install

npm install eslint-plugin-lingui

yarn add eslint-plugin-lingui

pnpm add eslint-plugin-lingui

Imports

pluginLingui (default import)
wrong
```
const pluginLingui = require('eslint-plugin-lingui')
```
correct
```
import pluginLingui from 'eslint-plugin-lingui'
```
ESM-only since v0.13.0? Actually the package ships both CJS and ESM. CommonJS require is valid but default import is preferred for flat config.
configs (flat/recommended)
wrong
```
pluginLingui.configs.recommended
```
correct
```
pluginLingui.configs['flat/recommended']
```
The flat config is under the 'flat/recommended' key. For legacy config, use 'plugin:lingui/recommended' in extends.
rules (e.g., t-call-in-function)
wrong
```
rules: { 'lingui/t-call-in-function': ['error'] }
```
correct
```
rules: { 'lingui/t-call-in-function': 'error' }
```
As of v0.13, rules that accept options use array syntax; simple rules use string severity. This is standard ESLint.

Quickstart

Flat ESLint config enabling recommended Lingui rules plus custom no-unlocalized-strings and text-restrictions rules.

// eslint.config.js
import pluginLingui from 'eslint-plugin-lingui';

export default [
  pluginLingui.configs['flat/recommended'],
  {
    plugins: {
      lingui: pluginLingui,
    },
    rules: {
      'lingui/no-unlocalized-strings': ['error', { ignoreNames: ['^_$'] }],
      'lingui/text-restrictions': ['warn', { patterns: ['TODO'] }],
    },
  },
];