lint
Find texts in your code that are not wrapped in t(), and placeholders that do not match the translation.
Analyzes your source code for internationalization issues. Can run without a config file.
npx i18next-cli lint
What it checks:
-
Hardcoded strings (error): user-facing text in JSX elements and attributes that isn't wrapped in
t()/<Trans>. -
Interpolation parameters (error): mismatches between
{{placeholders}}in a translation and the params passed tot()(missing or unused), also for selector calls liket($ => $.user.greeting, { name }). The placeholders come from the primary language's translation of the key in the namespace of the call (useTranslation('home'),t('home:greeting'),{ ns: 'home' }, akeyPrefix), every plural form included; a key without a translation is checked as written. Toggle withlint.checkInterpolationParams(default:true). Variables yourinterpolation.defaultVariablesfills in at runtime go intolint.defaultVariables(e.g.['appName']) and are not reported as missing; a dotted placeholder like{{user.name}}counts when its rootuseris listed. Withextract.messageFormat: 'icu'or'mf2'the arguments come from the ICU or MF2 parser ({name},{$name}), so plurals likeone {{count} row}are not read as{{…}}interpolation. -
ICU / MF2 messages (error, only with
extract.messageFormat: 'icu'or'mf2'): every value in the translation files of all locales is parsed. The linter reports, with file, key and line (JSON files):- syntax errors with the parser's message, e.g.
greeting: ICU syntax error: EXPECT_ARGUMENT_CLOSING_BRACE at column 7 - argument names that differ from the primary language (a renamed or missing
{name}).#in a plural is not an argument - plural categories of
pluralandselectordinal(MF2:.matchon:numberor:integer) that do not fit the locale. Allowed are the locale's CLDR categories, required areotherplus every category a whole number below one million selects. Soruneedsone,fewandmany, whilefr,es,itandptmay leave outmany(only from 1,000,000) andcsitsmany(fractions only), andzeroin English is reported as unused. Exact selectors like=0are always allowed, and they count for a category that selects only a few small numbers when they cover them all:=1coversonein English, but not in Russian, whereoneis also 21, 31 and so on. For a localeIntldoes not know onlyotheris required. A language code with_(ru_RU,pt_BR) is read asru-RU,pt-BR. - (warning, MF2 only) whitespace at the start or end of a pattern that differs from the primary language:
{{ {$count} files}}shows the space in the app.
Empty values count as untranslated and are skipped. See ICU and MF2 messages.
- syntax errors with the parser's message, e.g.
-
Placeholders across locales (warning by default, i18next format): every translation file is compared with the primary language, so a translation that renamed or dropped a placeholder is reported with file, key and line (JSON files), e.g.
greeting: missing {{name}}, unexpected {{nom}} (compared with "en"). Compared are:- interpolations by name, read like i18next does:
{{name}},{{ name }},{{- name}}and{{name, uppercase}}are allname, so a format may differ per language. A custominterpolationPrefix/interpolationSuffixis read - nested
$t(key)references - tags, in any order: the numbered ones of
<Trans>(<0>…</0>,<1/>) and named ones like<bold>from itscomponents, which react-i18next shows as text when a translation renames them. The basic HTML react-i18next keeps as is (extract.transKeepBasicHtmlNodesFor, defaultbr,strong,i,p) is not compared: a language may add or drop it
Plural forms are compared as a group (the union over
_zero,_one,_other, ...), since{{count}}may be left out of_oneor_zeroand a language has forms the primary language lacks (ru_few). A partly translated plural is checked for unexpected placeholders only. Keys only one side has and empty values are skipped (statusreports them). Configure withlint.checkTranslationPlaceholders:'warn'/true(default),'error'(fails the run),'off'/false. Withextract.messageFormat: 'icu'or'mf2'the ICU / MF2 check above runs instead. - interpolations by name, read like i18next does:
-
<Trans>tags against the children (warning by default):<Trans>numbers its children, text included, so the{' '}a formatter inserts at a line break shifts every later index. InHello{' '}<Bold>world</Bold>the{' '}is<1>and<Bold>is<2>, and a translationHello <1>world</1>rendersHello. The tags of the primary language's translation of every<Trans>with children (context and plural forms included) are resolved like react-i18next does at runtime, and a tag that does not render what it wraps is reported, e.g.reminder:disclosure: <1> points to the text " ", which replaces its content:- a tag with content on a text child, which renders that text instead
- a tag past the last child, which loses its markup
- an empty tag (
<2/>) on an element with text, which renders the element without its text - a tag with content on a
<br/>(or another void element), which makes React throw
A tag on an interpolation object (
<1>{{count}}</1>) is fine: react-i18next renders its content. A tag on an expression ({link}) is not checked: its value is known only at runtime. A<Trans>withcomponentsis skipped. Only the primary language is checked; in the i18next format the placeholder check above compares the tags of the other languages with it. Configure withlint.checkTransIndices:'warn'/true(default),'error'(fails the run),'off'/false. -
String concatenation (warning by default): translated strings glued together with
+, or a sentence split across multiple adjacent translations (<Trans>components and/or{t()}expressions rendered as siblings). This breaks in languages that reorder or inflect the pieces; use a single key with placeholders instead. Configure withlint.checkConcatenation:'warn'/true(default) reports it without failing the run,'error'makes it fail (exit non-zero, useful for CI), and'off'/falsedisables it.jsx// ⚠️ Flagged: word order can't be translated t('greeting') + ', ' + name <p><Trans>Hello</Trans> and <Trans>World</Trans></p> <p><Trans>new</Trans>{t('cat')}</p> // ✅ Preferred: one key, placeholders t('greeting', { name }) // "Hello, {{name}}" <Trans i18nKey="greeting">Hello {{name}}</Trans> -
Punctuation concatenation (off by default): punctuation glued onto a translation, e.g.
<label><Trans>Email</Trans>:</label>or<div>- <Trans>item</Trans></div>. Punctuation spacing and form differ across languages (French needs a narrow no-break space before:, CJK uses fullwidth:, RTL reorders), so it belongs inside the translation or in semantic markup (a real<ul>/<li>for bullets). This is opt-in, since keeping punctuation out of a translation is often deliberate. Enable withlint.checkPunctuationConcatenation:'warn','error', or'off'/false(default).jsx// ⚠️ Flagged when enabled <label><Trans>Email</Trans>:</label> <div>- <Trans>item</Trans></div> // ✅ Preferred <label><Trans i18nKey="emailLabel">Email:</Trans></label> <ul><li><Trans>item</Trans></li></ul>The linter exits non-zero only when it finds errors; a run with only warnings succeeds. Individual spots can be excused with the
i18next-instrument-ignoredirective.
Baseline: fail only on new issues. To adopt lint in CI on a codebase that already has issues, record them once and commit the file:
npx i18next-cli lint --update-baseline
This writes i18next-lint-baseline.json (another path: lint.baseline) with the issues per file. While the file exists, lint reports and fails only on issues it does not hold, and prints how many existing ones it left out. An issue is identified by its file, type and text, not its line, so moving code keeps it in the baseline, while one more identical hardcoded string in the same file is new. When issues get fixed, lint says how many entries no longer occur; run --update-baseline again to drop them. This is the same approach as ESLint's bulk suppressions.
To suppress warnings for code you intentionally aren't translating yet, use the i18next-instrument-ignore directive: the same comment recognized by the instrument command.