eslint-plugin-lingui-typescript

ESLint rules for Lingui that read TypeScript types instead of guessing. Your whitelist goes away.

Documentation

The whitelist treadmill

Every i18n linter that relies on pattern matching hits the same wall. It can't tell a CSS class from a button label, or a DOM event name from an error message. So you add them to the whitelist. Then someone calls document.createElement("div") and that gets flagged too. More entries. A new team member joins, hits the same false positives, adds the same entries.

// Pattern-based linters flag all of these as "missing translation"
document.createElement("div")                    // It's a DOM tag name
element.addEventListener("click", handler)       // It's an event name
fetch(url, { mode: "cors" })                     // It's a typed option
const status: "idle" | "loading" = "idle"        // It's a string literal union
<Box className="flex items-center" />            // It's a CSS class

The list grows. The problem stays.

When your linter reads types

A string flowing into keyof HTMLElementTagNameMap isn't user text. A variable typed as "idle" | "loading" | "error" doesn't need translation. TypeScript has had this information all along — this plugin reads it directly.

// TypeScript already has the context — this plugin uses it
document.createElement("div")                           // keyof HTMLElementTagNameMap
element.addEventListener("click", handler)              // keyof GlobalEventHandlersEventMap
fetch(url, { mode: "cors" })                            // RequestMode
date.toLocaleDateString("de-DE", { weekday: "long" })  // Intl.DateTimeFormatOptions

type Status = "idle" | "loading" | "error"
const status: Status = "loading"                        // String literal union

// Styling props and utility patterns — recognized out of the box
<Box containerClassName="flex items-center" />          // *ClassName, *Color, *Style
<Link rel="noopener noreferrer" />                      // Link rel attribute
<div className={clsx("px-4", "py-2")} />               // className utilities (clsx, cn)
<Calendar classNames={{ day: "bg-white" }} />           // Nested classNames objects
const colorClasses = { active: "bg-green-100" }         // *Classes, *Colors, *Styles
const successUrl = "Checkout redirect destination"      // *Url, *Slug, *Email names
const price = "1,00€"                                   // No letters = not user-facing
const letterSpacing = "-0.02em"                         // CSS numeric unit value
if (status === "active") {}                             // Binary comparison
if (error.message.includes("User not found")) {}        // String search on string receiver
const code = error.message.replace("User not found", "E_USER_NOT_FOUND") // replace(searchValue)
el.style.filter = "brightness(0.85)"                    // Direct style assignments
const data = { "United States": info }                  // Object keys (always structural)

// These actually need translation — and get reported
const message = "Welcome to our app"
<button>Save changes</button>

Macro verification works the same way. The plugin checks that t, Trans, and friends actually come from @lingui/* packages through TypeScript's symbol resolution:

import { t } from "@lingui/macro"
const label = t`Save`              // Recognized as Lingui

const t = (key: string) => map[key]
const label = t("save")            // Not confused with Lingui

Getting started

Requirements

• Node.js >= 24, ESLint >= 9, TypeScript >= 5
• typescript-eslint with type-aware linting enabled

Install

npm install --save-dev eslint-plugin-lingui-typescript

Configure

Add the recommended config to eslint.config.ts:

import eslint from "@eslint/js"
import tseslint from "typescript-eslint"
import linguiPlugin from "eslint-plugin-lingui-typescript"

export default [
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  linguiPlugin.configs["flat/recommended"],
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  }
]

Or pick individual rules:

{
  plugins: {
    "lingui-ts": linguiPlugin
  },
  rules: {
    "lingui-ts/no-unlocalized-strings": "error",
    "lingui-ts/no-single-variables-to-translate": "error"
  }
}

That's it. DOM APIs, Intl methods, string literal unions, technical property/variable suffixes, comparisons, numeric strings, and string-search checks — all handled from the first run.

OXLint support

This plugin works with OXLint via its JavaScript plugin system. Eight of nine rules run natively in OXLint — no code changes, no wrapper, no adapter.

Add to your .oxlintrc.json:

{
  "jsPlugins": ["eslint-plugin-lingui-typescript"],
  "rules": {
    "lingui-typescript/no-nested-macros": "error",
    "lingui-typescript/no-single-variables-to-translate": "error",
    "lingui-typescript/no-single-tag-to-translate": "error",
    "lingui-typescript/t-call-in-function": "warn",
    "lingui-typescript/no-expression-in-message": "warn",
    "lingui-typescript/consistent-plural-format": "warn",
    "lingui-typescript/prefer-trans-in-jsx": "warn",
    "lingui-typescript/text-restrictions": ["error", { "rules": [] }]
  }
}

The only rule not supported in OXLint is no-unlocalized-strings — it uses TypeScript's type checker at runtime to distinguish UI text from technical strings. As OXLint's type-aware linting matures, this rule will follow.

Dual setup — run OXLint for speed, ESLint for full coverage:

oxlint . && eslint .

Rules

Rule	Description	Recommended	Fixable	OXLint
no-unlocalized-strings	Catches user-visible strings not wrapped in Lingui macros. Uses TypeScript types to skip technical strings automatically.	error	✅	*1
no-single-variables-to-translate	Prevents messages with only variables and no text — translators need context.	error	—	✅
no-single-tag-to-translate	Prevents <Trans> wrapping a single JSX element without surrounding text.	error	—	✅
no-nested-macros	Prevents nesting Lingui macros inside each other — nested macros produce broken catalogs.	error	—	✅
no-expression-in-message	Keeps expressions simple inside messages. Complex logic goes into named variables.	warn	—	✅
t-call-in-function	Keeps t macro calls inside functions where i18n is initialized.	warn	—	✅
consistent-plural-format	Enforces consistent plural format — either # hash or ${var} template literals.	warn	✅	✅
prefer-trans-in-jsx	Prefers <Trans> over {t`...`} in JSX for consistency.	warn	✅	✅
text-restrictions	Enforces project-specific text patterns and restrictions. Requires configuration.	—	—	✅

*1 Requires TypeScript's type checker to distinguish UI text from technical strings. OXLint's type-aware linting is in alpha — once stable, this rule will be supported too.

Branded types for edge cases

Automatic detection covers most strings, but some cases need a hint — custom loggers, analytics events, internal keys. The plugin exports branded types for exactly this:

import { unlocalized } from "eslint-plugin-lingui-typescript/types"

const logger = unlocalized({
  debug: (...args: unknown[]) => console.debug(...args),
  info: (...args: unknown[]) => console.info(...args),
  error: (...args: unknown[]) => console.error(...args),
})

logger.info("Server started on port", 3000)  // Not flagged
logger.error("Connection failed:", error)    // Not flagged

Type	Use case
UnlocalizedFunction<T>	Wrap functions/objects to ignore all string arguments
unlocalized(value)	Helper for automatic type inference
UnlocalizedText	Generic technical strings
UnlocalizedLog	Logger message parameters
UnlocalizedStyle	Style values (colors, fonts, spacing)
UnlocalizedClassName	CSS class names
UnlocalizedEvent	Analytics/tracking event names
UnlocalizedKey	Storage keys, query keys
UnlocalizedRecord<K>	Key-value maps (Record<K, UnlocalizedText>)

As the plugin gets smarter, some brands become unnecessary. Enable reportUnnecessaryBrands to find the ones you can remove:

"lingui-ts/no-unlocalized-strings": ["error", { "reportUnnecessaryBrands": true }]

Full details in the no-unlocalized-strings docs.

Coming from eslint-plugin-lingui?

Drop-in alternative to eslint-plugin-lingui. Rule names are compatible.

What's different

	eslint-plugin-lingui	This plugin
How it works	Heuristics + manual whitelists	TypeScript type system
String literal unions	Manual whitelist	Auto-detected
DOM API strings	Manual whitelist	Auto-detected
Intl method arguments	Manual whitelist	Auto-detected
Styling props	Manual whitelist	Auto-detected
Styling constants	Manual whitelist	Auto-detected
Object keys	Manual whitelist	Auto-ignored
Numeric strings	Manual whitelist	Auto-detected
Custom ignores	ignoreFunctions only	ignoreFunctions, ignoreProperties, ignoreNames, branded types (unlocalized())
Macro verification	Name-based	Package-origin verification
ESLint	v8 legacy config	v9 flat config

Migration

1. npm uninstall eslint-plugin-lingui
2. npm install --save-dev eslint-plugin-lingui-typescript
3. Switch to flat config:

   import linguiPlugin from "eslint-plugin-lingui-typescript"
   export default [
     // ...
     linguiPlugin.configs["flat/recommended"]
   ]

4. Change rule prefix from lingui/ to lingui-ts/
5. Review your ignore lists — most entries are no longer needed

Options mapping for no-unlocalized-strings

Original	This plugin	Notes
useTsTypes	—	Always on
ignore (regex array)	ignorePattern (single regex)	Simplified
ignoreFunctions	ignoreFunctions	Console/Error auto-detected
ignoreNames (regex)	ignoreNames	Plain strings only
—	ignoreProperties	New: JSX attributes and object properties
ignoreMethodsOnTypes	—	Handled by TypeScript

Contributing

Contributions welcome. See the Contributing Guide and Code of Conduct.

Related

• Lingui — The i18n library this plugin is built for
• eslint-plugin-lingui — The official Lingui ESLint plugin
• typescript-eslint — Makes type-aware linting possible
• OXLint — High-performance linter with JS plugin support

License

MIT

---

Built by Sebastian Software