i18next-cli 1.79.1 → 1.80.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -281,6 +281,7 @@ The primary language is checked too: any key used in your code but absent from t
281
281
  - `--namespace <ns>, -n <ns>`: Filter the report by a specific namespace.
282
282
  - `--hide-translated`: Hide already translated keys in the detailed view, showing only missing translations.
283
283
  - `status.ignoreKeys` (config): glob patterns for keys that should not be reported (and don't fail the check), e.g. keys that are intentionally left empty in some locales. Optional `ns:` prefix (`common:help.*-href`). Only affects `status`.
284
+ - `status.checkIdentical` (config, default `'warn'`): values identical to the primary language, e.g. English copied into `de` by a `defaultValue` function or a copied file, are marked `≈ (identical to en)` and counted in the summary (`3 identical to en`). With `'warn'` they still count as translated and the exit code does not change; `'error'` counts them as untranslated, so `status` fails; `'off'` / `false` disables the check. Skipped: locales of the primary's language (`en-GB` with `en`), values without letters once placeholders, `$t()` and tags are removed (`{{count}}`, `100 %`), URLs, e-mail addresses and short all-caps words (`OK`, `FAQ`). Brand names and other values that stay the same go into `status.ignoreKeys`. A plural form the primary language lacks (`ru` `_few`) is compared with its `_other`.
284
285
  - `--unused`: Report only unused translation keys — keys present in your translation files that are no longer used in your source code (i.e. what `extract` with `removeUnusedKeys` would delete). Never modifies any files and exits with a non-zero status code when unused keys are found, so it can serve as a dedicated CI check alongside the regular missing-translations check. Note that static analysis cannot detect dynamically constructed keys (e.g. ``t(`error.${code}`)``); to find keys that are truly unused at runtime, see [find unused translations with locize](https://www.locize.com/docs/guides/find-unused-translations).
285
286
 
286
287
  **Usage Examples:**
@@ -380,6 +381,12 @@ npx i18next-cli lint
380
381
  - *(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.
381
382
 
382
383
  Empty values count as untranslated and are skipped. See [ICU and MF2 messages](#icu-and-mf2-messages).
384
+ - **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:
385
+ - interpolations by name, read like i18next does: `{{name}}`, `{{ name }}`, `{{- name}}` and `{{name, uppercase}}` are all `name`, so a format may differ per language. A custom `interpolationPrefix` / `interpolationSuffix` is read
386
+ - nested `$t(key)` references
387
+ - tags, in any order: the numbered ones of `<Trans>` (`<0>…</0>`, `<1/>`) and named ones like `<bold>` from its `components`, which react-i18next shows as text when a translation renames them. The basic HTML react-i18next keeps as is (`extract.transKeepBasicHtmlNodesFor`, default `br`, `strong`, `i`, `p`) is not compared, a language may add or drop it
388
+
389
+ Plural forms are compared as a group (the union over `_zero`, `_one`, `_other`, ...), since `{{count}}` may be left out of `_one` or `_zero` and 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 (`status` reports them). Configure with `lint.checkTranslationPlaceholders`: `'warn'` / `true` (default), `'error'` (fails the run), `'off'` / `false`. With `extract.messageFormat: 'icu'` or `'mf2'` the ICU / MF2 check above runs instead.
383
390
  - **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 with `lint.checkConcatenation`: `'warn'` / `true` (default) reports it without failing the run, `'error'` makes it fail (exit non-zero, useful for CI), and `'off'` / `false` disables it.
384
391
 
385
392
  ```jsx
@@ -407,6 +414,14 @@ npx i18next-cli lint
407
414
 
408
415
  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-ignore` directive](#suppressing-detection-with-i18next-instrument-ignore).
409
416
 
417
+ **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:
418
+
419
+ ```bash
420
+ npx i18next-cli lint --update-baseline
421
+ ```
422
+
423
+ 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. The same approach as ESLint's bulk suppressions.
424
+
410
425
  To suppress warnings for code you intentionally aren't translating yet, use the [`i18next-instrument-ignore` directive](#suppressing-detection-with-i18next-instrument-ignore) — the same comment recognized by the `instrument` command.
411
426
 
412
427
  ### `instrument`
@@ -707,7 +722,9 @@ all commands.
707
722
  written (check the extract.output path in the config). If the developer
708
723
  chose repository files only: translate the extracted keys yourself or
709
724
  leave them to the team, run `npx i18next-cli status` to confirm every
710
- language is complete, and stop here.
725
+ language is complete (it also lists values still identical to the primary
726
+ language) and `npx i18next-cli lint` to check that every translation keeps
727
+ the placeholders ({{name}}, $t(), <0>) of the primary language, and stop here.
711
728
  5. Locize (only if the developer chose it in step 2): ask them for
712
729
  LOCIZE_PROJECTID and LOCIZE_API_KEY (they create the project at
713
730
  https://www.locize.app/register?from=i18next_cli__agent-prompt
@@ -1095,6 +1112,13 @@ export default defineConfig({
1095
1112
  /** Lint punctuation glued onto a translation, e.g. <Trans>Email</Trans>: (default: 'off').
1096
1113
  * Opt-in; accepts the same values as checkConcatenation. */
1097
1114
  checkPunctuationConcatenation: 'off',
1115
+
1116
+ /** Compare the placeholders ({{name}}, $t(key), <0>) of every locale with the primary
1117
+ * language (default: 'warn'). Accepts the same values as checkConcatenation. */
1118
+ checkTranslationPlaceholders: 'warn',
1119
+
1120
+ /** Baseline file written by `lint --update-baseline` (default: 'i18next-lint-baseline.json') */
1121
+ baseline: 'i18next-lint-baseline.json',
1098
1122
  },
1099
1123
 
1100
1124
  // `status` command
@@ -1103,6 +1127,10 @@ export default defineConfig({
1103
1127
  // intentionally empty in some locales. Same shape as `preservePatterns`; a `ns:`
1104
1128
  // prefix limits the pattern to one namespace. Only affects `status`, not `extract`.
1105
1129
  ignoreKeys: ['*-href', 'common:empty-table-subtitle'], // Optional
1130
+
1131
+ // Values identical to the primary language (English copied into `de`): 'warn' (default)
1132
+ // shows them, 'error' counts them as untranslated, 'off' disables the check.
1133
+ checkIdentical: 'warn',
1106
1134
  },
1107
1135
 
1108
1136
  // TypeScript type generation
package/dist/cjs/cli.js CHANGED
@@ -39,7 +39,7 @@ const program = new commander.Command();
39
39
  program
40
40
  .name('i18next-cli')
41
41
  .description('A unified, high-performance i18next CLI.')
42
- .version('1.79.1') // This string is replaced with the actual version at build time by rollup
42
+ .version('1.80.0') // This string is replaced with the actual version at build time by rollup
43
43
  .addHelpText('after', '\nUsing an AI coding agent? Install the i18next-localization skill: npx skills add i18next/i18next-cli\n');
44
44
  // new: global config override option
45
45
  program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
@@ -240,6 +240,7 @@ program
240
240
  .description('Find potential issues like hardcoded strings in your codebase.')
241
241
  .option('-w, --watch', 'Watch for file changes and re-run the linter.')
242
242
  .option('-q, --quiet', 'Suppress spinner and output')
243
+ .option('--update-baseline', 'Write all current issues to the baseline file (lint.baseline, default i18next-lint-baseline.json); lint then fails only on new issues. Commit the file.')
243
244
  .action(async (options) => {
244
245
  const cfgPath = program.opts().config;
245
246
  const loadAndRunLinter = async () => {
@@ -256,7 +257,7 @@ program
256
257
  console.log(node_util.styleText('green', 'Project structure detected successfully!'));
257
258
  config$1 = detected;
258
259
  }
259
- await linter.runLinterCli(config$1, { quiet: !!options.quiet });
260
+ await linter.runLinterCli(config$1, { quiet: !!options.quiet, updateBaseline: !!options.updateBaseline });
260
261
  };
261
262
  // Run the linter once initially
262
263
  await loadAndRunLinter();
@@ -12,7 +12,10 @@ var jsxAttributes = require('./utils/jsx-attributes.js');
12
12
  var astUtils = require('./extractor/parsers/ast-utils.js');
13
13
  var functionMatcher = require('./extractor/utils/function-matcher.js');
14
14
  var messageFormat = require('./utils/message-format.js');
15
+ var lintBaseline = require('./utils/lint-baseline.js');
16
+ var funnelMsgTracker = require('./utils/funnel-msg-tracker.js');
15
17
 
18
+ const LOCIZE_SIGNUP_URL = 'https://www.locize.app/register?from=i18next_cli__lint';
16
19
  /**
17
20
  * Loads all translation values from the primary locale's JSON files and returns
18
21
  * a flat Map of key -> translated string. Used by the interpolation linter so it
@@ -74,20 +77,6 @@ async function loadPrimaryTranslationValues(config) {
74
77
  }
75
78
  return result;
76
79
  }
77
- // Helper to extract interpolation keys from a translation string
78
- function extractInterpolationKeys(str, config) {
79
- const prefix = config.extract.interpolationPrefix ?? '{{';
80
- const suffix = config.extract.interpolationSuffix ?? '}}';
81
- // Regex to match {{key}} or {{key, format}} (i18next formatting syntax)
82
- const regex = new RegExp(`${prefix.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}\\s*([\\w.-]+)\\s*(?:,[^}]*)?${suffix.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}`, 'g');
83
- const keys = [];
84
- let match;
85
- while ((match = regex.exec(str))) {
86
- if (match[1])
87
- keys.push(match[1]);
88
- }
89
- return keys;
90
- }
91
80
  // Known i18next t() option keys that are NOT interpolation parameters.
92
81
  // These should not be flagged as "unused" in the translation string.
93
82
  const i18nextOptionKeys = new Set([
@@ -286,7 +275,7 @@ function lintInterpolationParams(ast, code, config, translationValues, analyze)
286
275
  continue;
287
276
  lastSearchIndex = position + searchText.length;
288
277
  const issueLineNumber = getLineNumber(position);
289
- const keys = analyze ? messageArgs(analyze, translationStr) : extractInterpolationKeys(translationStr, config);
278
+ const keys = analyze ? messageArgs(analyze, translationStr) : messageFormat.interpolationNames(translationStr, config.extract);
290
279
  // Only check for unused parameters if there is at least one interpolation key in the string
291
280
  if (keys.length > 0) {
292
281
  // i18next supports nested object access via dot notation (e.g. {{author.name}} with { author }).
@@ -525,7 +514,8 @@ class Linter extends node_events.EventEmitter {
525
514
  }
526
515
  return new Error(`${prefix}${String(error)}`);
527
516
  }
528
- async run() {
517
+ /** @param options.ignoreBaseline - report every issue, also those the baseline file holds (`lint --update-baseline`) */
518
+ async run(options = {}) {
529
519
  const { config } = this;
530
520
  try {
531
521
  this.emit('progress', { message: 'Finding source files to analyze...' });
@@ -644,18 +634,36 @@ class Linter extends node_events.EventEmitter {
644
634
  issuesByFile.set(file, allIssues);
645
635
  }
646
636
  }
637
+ const placeholderSetting = config.lint?.checkTranslationPlaceholders;
638
+ let resourceIssues = new Map();
647
639
  if (analyze) {
648
640
  this.emit('progress', { message: `Checking ${messageFormat$1 === 'mf2' ? 'MF2' : 'ICU'} messages in translation files...` });
649
- for (const [file, issues] of await messageFormat.lintMessageFormatResources(config, analyze)) {
650
- totalIssues += issues.length;
651
- issuesByFile.set(file, [...(issuesByFile.get(file) ?? []), ...issues]);
652
- }
641
+ resourceIssues = await messageFormat.lintMessageFormatResources(config, analyze);
642
+ }
643
+ else if (placeholderSetting !== false && placeholderSetting !== 'off' && config.locales.length > 1) {
644
+ this.emit('progress', { message: 'Checking placeholders in translation files...' });
645
+ resourceIssues = await messageFormat.lintI18nextResources(config, placeholderSetting === 'error' ? 'error' : 'warning');
646
+ }
647
+ for (const [file, issues] of resourceIssues) {
648
+ totalIssues += issues.length;
649
+ issuesByFile.set(file, [...(issuesByFile.get(file) ?? []), ...issues]);
650
+ }
651
+ let files = Object.fromEntries(issuesByFile.entries());
652
+ // Issues the baseline file holds (`lint --update-baseline`) are counted, not reported
653
+ let existingIssues = 0;
654
+ let staleBaselineEntries = 0;
655
+ const baseline = options.ignoreBaseline ? undefined : await lintBaseline.readLintBaseline(lintBaseline.lintBaselinePath(config));
656
+ if (baseline) {
657
+ ({ files, existing: existingIssues, stale: staleBaselineEntries } = lintBaseline.applyLintBaseline(files, baseline));
658
+ totalIssues -= existingIssues;
653
659
  }
654
- const files = Object.fromEntries(issuesByFile.entries());
655
660
  // `success` reflects errors only — warning-severity issues (e.g. string
656
661
  // concatenation) are reported but do not fail the run / CI.
657
- const errorCount = Array.from(issuesByFile.values()).flat().filter(i => i.severity !== 'warning').length;
658
- const data = { success: errorCount === 0, message: totalIssues > 0 ? `Linter found ${totalIssues} potential issues.` : 'No issues found.', files };
662
+ const errorCount = Object.values(files).flat().filter(i => i.severity !== 'warning').length;
663
+ const message = totalIssues > 0
664
+ ? `Linter found ${totalIssues} potential issues${existingIssues ? ` (${existingIssues} more in the baseline)` : ''}.`
665
+ : existingIssues ? `No new issues found (${existingIssues} in the baseline).` : 'No issues found.';
666
+ const data = { success: errorCount === 0, message, files, existingIssues, staleBaselineEntries };
659
667
  this.emit('done', data);
660
668
  return data;
661
669
  }
@@ -772,13 +780,21 @@ async function runLinter(config) {
772
780
  }
773
781
  async function runLinterCli(config, options = {}) {
774
782
  const internalLogger = options.logger ?? new logger.ConsoleLogger();
783
+ const log = (msg) => typeof internalLogger.info === 'function' ? internalLogger.info(msg) : console.log(msg);
775
784
  const linter = new Linter(config, internalLogger);
776
785
  const spinner = wrapOra.createSpinnerLike('', { quiet: !!options.quiet, logger: options.logger });
777
786
  linter.on('progress', (event) => {
778
787
  spinner.text = event.message;
779
788
  });
780
789
  try {
781
- const { message, files } = await linter.run();
790
+ if (options.updateBaseline) {
791
+ const { files } = await linter.run({ ignoreBaseline: true });
792
+ const path = lintBaseline.lintBaselinePath(config);
793
+ const count = await lintBaseline.writeLintBaseline(path, files);
794
+ spinner.succeed(node_util.styleText(['green', 'bold'], `Wrote ${count} existing issue${count === 1 ? '' : 's'} to ${node_path.relative(process.cwd(), path)}. Commit it: lint now fails only on new issues.`));
795
+ return;
796
+ }
797
+ const { message, files, staleBaselineEntries } = await linter.run();
782
798
  const fileEntries = Object.entries(files);
783
799
  const allIssues = fileEntries.flatMap(([, issues]) => issues);
784
800
  const hasErrors = allIssues.some(i => i.severity !== 'warning');
@@ -803,7 +819,9 @@ async function runLinterCli(config, options = {}) {
803
819
  ? 'String concatenation'
804
820
  : type === 'messageFormat'
805
821
  ? `${config.extract.messageFormat === 'mf2' ? 'MF2' : 'ICU'} message`
806
- : 'Found hardcoded string';
822
+ : type === 'placeholder'
823
+ ? 'Placeholder mismatch'
824
+ : 'Found hardcoded string';
807
825
  const tag = severity === 'warning' ? node_util.styleText('yellow', 'Warning:') : node_util.styleText('red', 'Error:');
808
826
  // line 0: a translation file whose format has no line lookup (YAML, JS)
809
827
  const detail = ` ${line ? `${node_util.styleText('gray', `${line}:`)} ` : ''}${tag} ${label}: "${text}"`;
@@ -813,6 +831,16 @@ async function runLinterCli(config, options = {}) {
813
831
  console.log(detail);
814
832
  });
815
833
  }
834
+ if (staleBaselineEntries > 0) {
835
+ log(node_util.styleText('gray', `\n${staleBaselineEntries} baseline entr${staleBaselineEntries === 1 ? 'y no longer occurs' : 'ies no longer occur'}. Run "npx i18next-cli lint --update-baseline" to drop ${staleBaselineEntries === 1 ? 'it' : 'them'}.`));
836
+ }
837
+ // A placeholder broken in a translation file was edited outside the code, usually by a
838
+ // translator or a tool: Locize runs the same check in its editor while they type.
839
+ // Gated like the other funnel messages (never in CI/non-TTY, 24h cooldown).
840
+ if (allIssues.some(i => i.type === 'placeholder') && await funnelMsgTracker.shouldShowFunnel('lint-placeholders')) {
841
+ log(`\n💡 Locize runs this placeholder check while translators type and can fix a mismatch with AI (sign up: ${LOCIZE_SIGNUP_URL})`);
842
+ await funnelMsgTracker.recordFunnelShown('lint-placeholders');
843
+ }
816
844
  // Only errors fail the process; warning-only runs exit 0.
817
845
  if (hasErrors)
818
846
  process.exit(1);
@@ -44,7 +44,9 @@ all commands.
44
44
  written (check the extract.output path in the config). If the developer
45
45
  chose repository files only: translate the extracted keys yourself or
46
46
  leave them to the team, run \`npx i18next-cli status\` to confirm every
47
- language is complete, and stop here.
47
+ language is complete (it also lists values still identical to the primary
48
+ language) and \`npx i18next-cli lint\` to check that every translation keeps
49
+ the placeholders ({{name}}, $t(), <0>) of the primary language, and stop here.
48
50
  5. Locize (only if the developer chose it in step 2): ask them for
49
51
  LOCIZE_PROJECTID and LOCIZE_API_KEY (they create the project at
50
52
  https://www.locize.app/register?from=i18next_cli__agent-prompt
@@ -26,6 +26,25 @@ function globToRegex(glob) {
26
26
  const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
27
27
  return new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
28
28
  }
29
+ const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
30
+ /**
31
+ * True for a value that may stay the same in every language: no letters once the placeholders,
32
+ * `$t()` references and tags are removed, a URL or e-mail address, or a short all-caps word ("OK", "FAQ").
33
+ */
34
+ function staysTheSame(value, config) {
35
+ const { interpolationPrefix = '{{', interpolationSuffix = '}}', nestingPrefix = '$t(', nestingSuffix = ')' } = config.extract;
36
+ const text = value
37
+ .replace(new RegExp(`${escapeRegex(interpolationPrefix)}.*?${escapeRegex(interpolationSuffix)}`, 'g'), ' ')
38
+ .replace(new RegExp(`${escapeRegex(nestingPrefix)}.*?${escapeRegex(nestingSuffix)}`, 'g'), ' ')
39
+ .replace(/<[^>]*>/g, ' ')
40
+ .trim();
41
+ const letters = text.match(/\p{L}/gu)?.length ?? 0;
42
+ if (!letters)
43
+ return true;
44
+ if (/^(?:https?:\/\/|www\.|mailto:)\S*$|^[^\s@]+@[^\s@]+\.[^\s@]+$/i.test(text))
45
+ return true;
46
+ return letters <= 5 && !/\p{Ll}/u.test(text);
47
+ }
29
48
  function classifyValue(value) {
30
49
  if (value === undefined || value === null)
31
50
  return 'absent';
@@ -327,12 +346,23 @@ async function generateStatusReport(config) {
327
346
  // surfaced as well. For the primary, an empty value is a deliberate
328
347
  // placeholder and counts as present — only truly absent keys are flagged.
329
348
  const localesToCheck = [primaryLanguage, ...secondaryLanguages.filter((l) => l !== primaryLanguage)];
349
+ // `status.checkIdentical`: values identical to the primary language's. Only `'error'` counts them as untranslated.
350
+ const identicalSetting = config.status?.checkIdentical;
351
+ const checkIdentical = identicalSetting !== false && identicalSetting !== 'off';
352
+ const isDone = (state) => state === 'translated' || (state === 'identical' && identicalSetting !== 'error');
353
+ const primaryTranslationsByNs = new Map();
354
+ const baseLanguage = (lng) => lng.split(/[-_]/)[0].toLowerCase();
355
+ // a plural form the primary language lacks (ru `_few`) is compared with its `_other`
356
+ const nonOtherPluralSuffix = new RegExp(`${escapeRegex(pluralSeparator)}(?:zero|one|two|few|many)$`);
330
357
  for (const locale of localesToCheck) {
331
358
  const isPrimary = locale === primaryLanguage;
359
+ // en-GB keeps most of the en values
360
+ const compareWithPrimary = checkIdentical && !isPrimary && baseLanguage(locale) !== baseLanguage(primaryLanguage);
332
361
  let totalTranslatedForLocale = 0;
333
362
  let totalEmptyForLocale = 0;
334
363
  let totalAbsentForLocale = 0;
335
364
  let totalOptionalForLocale = 0;
365
+ let totalIdenticalForLocale = 0;
336
366
  let totalKeysForLocale = 0;
337
367
  const namespaces = new Map();
338
368
  const mergedTranslations = mergeNamespaces
@@ -379,6 +409,9 @@ async function generateStatusReport(config) {
379
409
  // when mergedTranslations[ns] is missing.
380
410
  ? (mergedTranslations?.[ns] ?? mergedTranslations ?? {})
381
411
  : await fileUtils.loadTranslationFile(node_path.resolve(process.cwd(), fileUtils.getOutputPath(config.extract.output, locale, ns))) || {};
412
+ if (isPrimary)
413
+ primaryTranslationsByNs.set(ns, translationsForNs);
414
+ const primaryTranslations = primaryTranslationsByNs.get(ns);
382
415
  const fallbackTranslationsList = [];
383
416
  for (const fallbackNs of fallbackNamespaces) {
384
417
  if (ns === fallbackNs)
@@ -389,8 +422,21 @@ async function generateStatusReport(config) {
389
422
  let emptyInNs = 0;
390
423
  let absentInNs = 0;
391
424
  let optionalInNs = 0;
425
+ let identicalInNs = 0;
392
426
  let totalInNs = 0;
393
427
  const keyDetails = [];
428
+ const tally = (key, state) => {
429
+ totalInNs++;
430
+ if (isDone(state))
431
+ translatedInNs++;
432
+ else if (state === 'empty')
433
+ emptyInNs++;
434
+ else if (state === 'absent')
435
+ absentInNs++;
436
+ if (state === 'identical')
437
+ identicalInNs++;
438
+ keyDetails.push({ key, state });
439
+ };
394
440
  // Get the plural categories for THIS specific locale
395
441
  const getLocalePluralCategories = (locale, isOrdinal) => {
396
442
  try {
@@ -433,6 +479,13 @@ async function generateStatusReport(config) {
433
479
  // key (used in code, missing from the file) is a problem here.
434
480
  if (isPrimary && state === 'empty')
435
481
  return 'translated';
482
+ // English copied into `de` (a fallback-namespace value is not this locale's own)
483
+ if (compareWithPrimary && primaryState === 'translated' && primaryTranslations && typeof primaryValue === 'string') {
484
+ const sourceValue = nestedObject.getNestedValue(primaryTranslations, key, sep) ??
485
+ nestedObject.getNestedValue(primaryTranslations, key.replace(nonOtherPluralSuffix, `${pluralSeparator}other`), sep);
486
+ if (primaryValue === sourceValue && !staysTheSame(primaryValue, config))
487
+ return 'identical';
488
+ }
436
489
  return state;
437
490
  };
438
491
  const processedKeys = new Set();
@@ -464,19 +517,12 @@ async function generateStatusReport(config) {
464
517
  // it isn't translated — whether absent or an empty placeholder that
465
518
  // `extract` wrote. It is never a hard failure. See #270 and
466
519
  // getOptionalPluralCategories.
467
- if (state !== 'translated' && optionalCategories.has(category)) {
520
+ if (!isDone(state) && optionalCategories.has(category)) {
468
521
  optionalInNs++;
469
522
  keyDetails.push({ key: baseKey, state: 'optional' });
470
523
  }
471
524
  else {
472
- totalInNs++;
473
- if (state === 'translated')
474
- translatedInNs++;
475
- else if (state === 'empty')
476
- emptyInNs++;
477
- else
478
- absentInNs++;
479
- keyDetails.push({ key: baseKey, state });
525
+ tally(baseKey, state);
480
526
  }
481
527
  }
482
528
  }
@@ -502,14 +548,7 @@ async function generateStatusReport(config) {
502
548
  // resolves count via the bare key, so it satisfies the family on
503
549
  // its own — don't demand plural variants that were never written.
504
550
  processedKeys.add(baseKey);
505
- totalInNs++;
506
- if (bareState === 'translated')
507
- translatedInNs++;
508
- else if (bareState === 'empty')
509
- emptyInNs++;
510
- else
511
- absentInNs++;
512
- keyDetails.push({ key: baseKey, state: bareState });
551
+ tally(baseKey, bareState);
513
552
  }
514
553
  else {
515
554
  // Convention (b): plural variants exist (or the family is missing
@@ -523,19 +562,12 @@ async function generateStatusReport(config) {
523
562
  const state = resolveAndClassify(pluralKey);
524
563
  // An optional category (e.g. French `_many`) is a soft note
525
564
  // whenever it isn't translated — never a hard failure. See #270.
526
- if (state !== 'translated' && optionalCategories.has(category)) {
565
+ if (!isDone(state) && optionalCategories.has(category)) {
527
566
  optionalInNs++;
528
567
  keyDetails.push({ key: pluralKey, state: 'optional' });
529
568
  continue;
530
569
  }
531
- totalInNs++;
532
- if (state === 'translated')
533
- translatedInNs++;
534
- else if (state === 'empty')
535
- emptyInNs++;
536
- else
537
- absentInNs++;
538
- keyDetails.push({ key: pluralKey, state });
570
+ tally(pluralKey, state);
539
571
  }
540
572
  }
541
573
  }
@@ -543,15 +575,7 @@ async function generateStatusReport(config) {
543
575
  else {
544
576
  if (!processedKeys.has(baseKey)) {
545
577
  processedKeys.add(baseKey);
546
- totalInNs++;
547
- const state = resolveAndClassify(baseKey);
548
- if (state === 'translated')
549
- translatedInNs++;
550
- else if (state === 'empty')
551
- emptyInNs++;
552
- else
553
- absentInNs++;
554
- keyDetails.push({ key: baseKey, state });
578
+ tally(baseKey, resolveAndClassify(baseKey));
555
579
  }
556
580
  }
557
581
  }
@@ -562,21 +586,14 @@ async function generateStatusReport(config) {
562
586
  if (processedKeys.has(variantKey))
563
587
  continue;
564
588
  processedKeys.add(variantKey);
565
- totalInNs++;
566
- const state = resolveAndClassify(variantKey);
567
- if (state === 'translated')
568
- translatedInNs++;
569
- else if (state === 'empty')
570
- emptyInNs++;
571
- else
572
- absentInNs++;
573
- keyDetails.push({ key: variantKey, state });
589
+ tally(variantKey, resolveAndClassify(variantKey));
574
590
  }
575
- namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, optionalKeys: optionalInNs, keyDetails });
591
+ namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, optionalKeys: optionalInNs, identicalKeys: identicalInNs, keyDetails });
576
592
  totalTranslatedForLocale += translatedInNs;
577
593
  totalEmptyForLocale += emptyInNs;
578
594
  totalAbsentForLocale += absentInNs;
579
595
  totalOptionalForLocale += optionalInNs;
596
+ totalIdenticalForLocale += identicalInNs;
580
597
  totalKeysForLocale += totalInNs;
581
598
  }
582
599
  const localeStatus = {
@@ -585,6 +602,7 @@ async function generateStatusReport(config) {
585
602
  totalEmpty: totalEmptyForLocale,
586
603
  totalAbsent: totalAbsentForLocale,
587
604
  totalOptional: totalOptionalForLocale,
605
+ totalIdentical: totalIdenticalForLocale,
588
606
  namespaces,
589
607
  };
590
608
  if (isPrimary) {
@@ -600,14 +618,24 @@ async function generateStatusReport(config) {
600
618
  * Builds a compact breakdown string like "3 untranslated, 2 absent" for use in
601
619
  * summary lines. Returns an empty string when there is nothing to report.
602
620
  */
603
- function buildBreakdown(emptyCount, absentCount) {
621
+ function buildBreakdown(emptyCount, absentCount, identicalCount = 0, primaryLanguage = '') {
604
622
  const parts = [];
605
623
  if (emptyCount > 0)
606
624
  parts.push(node_util.styleText('yellow', `${emptyCount} untranslated`));
625
+ if (identicalCount > 0)
626
+ parts.push(node_util.styleText('yellow', `${identicalCount} identical to ${primaryLanguage}`));
607
627
  if (absentCount > 0)
608
628
  parts.push(node_util.styleText('red', `${absentCount} absent`));
609
629
  return parts.join(', ');
610
630
  }
631
+ /**
632
+ * The funnel's gap for a locale: untranslated keys, plus the values identical to the
633
+ * primary language that `'warn'` (default) still counts as translated.
634
+ */
635
+ function funnelGap(config, locale, data) {
636
+ const identicalCountedAsTranslated = config.status?.checkIdentical === 'error' ? 0 : data.identical;
637
+ return { locale, untranslated: data.totalKeys - data.translated + identicalCountedAsTranslated, identical: data.identical };
638
+ }
611
639
  /**
612
640
  * Main display router that calls the appropriate display function based on options.
613
641
  *
@@ -653,7 +681,8 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
653
681
  console.log(node_util.styleText('bold', `\nKey Status for "${node_util.styleText('cyan', locale)}":`));
654
682
  const totalKeysForLocale = localeData.totalKeys;
655
683
  printProgressBar('Overall', localeData.totalTranslated, totalKeysForLocale);
656
- const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
684
+ const primaryLanguage = config.extract.primaryLanguage ?? '';
685
+ const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent, localeData.totalIdentical, primaryLanguage);
657
686
  if (breakdown)
658
687
  console.log(` ${breakdown}`);
659
688
  const namespacesToDisplay = namespaceFilter ? [namespaceFilter] : Array.from(localeData.namespaces.keys()).sort();
@@ -663,7 +692,7 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
663
692
  continue;
664
693
  console.log(node_util.styleText(['cyan', 'bold'], `\nNamespace: ${ns}`));
665
694
  printProgressBar('Namespace Progress', nsData.translatedKeys, nsData.totalKeys);
666
- const nsBreakdown = buildBreakdown(nsData.emptyKeys, nsData.absentKeys);
695
+ const nsBreakdown = buildBreakdown(nsData.emptyKeys, nsData.absentKeys, nsData.identicalKeys, primaryLanguage);
667
696
  if (nsBreakdown)
668
697
  console.log(` ${nsBreakdown}`);
669
698
  const keysToDisplay = hideTranslated
@@ -679,6 +708,9 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
679
708
  else if (state === 'optional') {
680
709
  console.log(` ${node_util.styleText('gray', '○')} ${key} ${node_util.styleText('gray', '(optional plural form)')}`);
681
710
  }
711
+ else if (state === 'identical') {
712
+ console.log(` ${node_util.styleText('yellow', '≈')} ${key} ${node_util.styleText('yellow', `(identical to ${primaryLanguage})`)}`);
713
+ }
682
714
  else {
683
715
  console.log(` ${node_util.styleText('red', '✗')} ${key} ${node_util.styleText('red', '(absent)')}`);
684
716
  }
@@ -690,7 +722,7 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
690
722
  console.log(node_util.styleText(['red', 'bold'], `\nSummary: Found ${missingCount} key(s) used in code but absent from the "${locale}" translation files. Run "i18next-cli extract" to add them.`));
691
723
  }
692
724
  else {
693
- const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
725
+ const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent, config.status?.checkIdentical === 'error' ? localeData.totalIdentical : 0, primaryLanguage);
694
726
  console.log(node_util.styleText(['yellow', 'bold'], `\nSummary: Found ${missingCount} incomplete translations for "${locale}" — ${summaryBreakdown}.`));
695
727
  }
696
728
  }
@@ -700,11 +732,16 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
700
732
  else {
701
733
  console.log(node_util.styleText(['green', 'bold'], `\nSummary: 🎉 All keys are translated for "${locale}".`));
702
734
  }
735
+ if (localeData.totalIdentical > 0 && config.status?.checkIdentical !== 'error') {
736
+ console.log(node_util.styleText('yellow', `${localeData.totalIdentical} value(s) are identical to "${primaryLanguage}" and may still need translating. Values that stay the same go into status.ignoreKeys.`));
737
+ }
703
738
  // Untranslated keys in a secondary locale are the gap Locize fills; absent
704
739
  // keys in the primary language are an `extract` problem (handled above).
705
740
  const nsData = namespaceFilter ? localeData.namespaces.get(namespaceFilter) : undefined;
706
- const untranslated = nsData ? nsData.totalKeys - nsData.translatedKeys : missingCount;
707
- await locizeFunnel.printUntranslatedFunnel('status', isPrimary ? [] : [{ locale, untranslated }], LOCIZE_SIGNUP_URL);
741
+ const gap = nsData
742
+ ? funnelGap(config, locale, { totalKeys: nsData.totalKeys, translated: nsData.translatedKeys, identical: nsData.identicalKeys })
743
+ : funnelGap(config, locale, { totalKeys: totalKeysForLocale, translated: localeData.totalTranslated, identical: localeData.totalIdentical });
744
+ await locizeFunnel.printUntranslatedFunnel('status', isPrimary ? [] : [gap], LOCIZE_SIGNUP_URL);
708
745
  }
709
746
  /**
710
747
  * Displays a summary report filtered by a single namespace.
@@ -729,7 +766,7 @@ async function displayNamespaceSummaryReport(report, config, namespace) {
729
766
  if (nsLocaleData) {
730
767
  const percentage = nsLocaleData.totalKeys > 0 ? Math.round((nsLocaleData.translatedKeys / nsLocaleData.totalKeys) * 100) : 100;
731
768
  const bar = generateProgressBarText(percentage);
732
- const breakdown = buildBreakdown(nsLocaleData.emptyKeys, nsLocaleData.absentKeys);
769
+ const breakdown = buildBreakdown(nsLocaleData.emptyKeys, nsLocaleData.absentKeys, nsLocaleData.identicalKeys, config.extract.primaryLanguage);
733
770
  const suffix = breakdown ? ` — ${breakdown}` : '';
734
771
  console.log(`- ${locale}: ${bar} ${percentage}% (${nsLocaleData.translatedKeys}/${nsLocaleData.totalKeys} keys)${suffix}`);
735
772
  }
@@ -741,7 +778,9 @@ async function displayNamespaceSummaryReport(report, config, namespace) {
741
778
  }
742
779
  const gaps = Array.from(report.locales, ([locale, localeData]) => {
743
780
  const nsLocaleData = localeData.namespaces.get(namespace);
744
- return { locale, untranslated: nsLocaleData ? nsLocaleData.totalKeys - nsLocaleData.translatedKeys : 0 };
781
+ return nsLocaleData
782
+ ? funnelGap(config, locale, { totalKeys: nsLocaleData.totalKeys, translated: nsLocaleData.translatedKeys, identical: nsLocaleData.identicalKeys })
783
+ : { locale, untranslated: 0 };
745
784
  });
746
785
  await locizeFunnel.printUntranslatedFunnel('status', gaps, LOCIZE_SIGNUP_URL);
747
786
  }
@@ -769,7 +808,7 @@ async function displayOverallSummaryReport(report, config) {
769
808
  for (const [locale, localeData] of report.locales.entries()) {
770
809
  const percentage = localeData.totalKeys > 0 ? Math.round((localeData.totalTranslated / localeData.totalKeys) * 100) : 100;
771
810
  const bar = generateProgressBarText(percentage);
772
- const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
811
+ const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent, localeData.totalIdentical, primaryLanguage);
773
812
  const suffix = breakdown ? ` — ${breakdown}` : '';
774
813
  console.log(`- ${locale}: ${bar} ${percentage}% (${localeData.totalTranslated}/${localeData.totalKeys} keys)${suffix}`);
775
814
  }
@@ -777,7 +816,7 @@ async function displayOverallSummaryReport(report, config) {
777
816
  console.log(node_util.styleText(['red', 'bold'], `\n⚠ Primary language "${primaryLanguage}" is missing ${report.primary.totalAbsent} key(s) that are used in code.`));
778
817
  console.log(node_util.styleText('red', ` Run "i18next-cli status ${primaryLanguage}" for details, or "i18next-cli extract" to add them.`));
779
818
  }
780
- const gaps = Array.from(report.locales, ([locale, localeData]) => ({ locale, untranslated: localeData.totalKeys - localeData.totalTranslated }));
819
+ const gaps = Array.from(report.locales, ([locale, localeData]) => funnelGap(config, locale, { totalKeys: localeData.totalKeys, translated: localeData.totalTranslated, identical: localeData.totalIdentical }));
781
820
  await locizeFunnel.printUntranslatedFunnel('status', gaps, LOCIZE_SIGNUP_URL);
782
821
  }
783
822
  /**