i18next-cli 1.79.0 → 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.
@@ -20,6 +20,25 @@ function globToRegex(glob) {
20
20
  const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
21
21
  return new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
22
22
  }
23
+ const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
24
+ /**
25
+ * True for a value that may stay the same in every language: no letters once the placeholders,
26
+ * `$t()` references and tags are removed, a URL or e-mail address, or a short all-caps word ("OK", "FAQ").
27
+ */
28
+ function staysTheSame(value, config) {
29
+ const { interpolationPrefix = '{{', interpolationSuffix = '}}', nestingPrefix = '$t(', nestingSuffix = ')' } = config.extract;
30
+ const text = value
31
+ .replace(new RegExp(`${escapeRegex(interpolationPrefix)}.*?${escapeRegex(interpolationSuffix)}`, 'g'), ' ')
32
+ .replace(new RegExp(`${escapeRegex(nestingPrefix)}.*?${escapeRegex(nestingSuffix)}`, 'g'), ' ')
33
+ .replace(/<[^>]*>/g, ' ')
34
+ .trim();
35
+ const letters = text.match(/\p{L}/gu)?.length ?? 0;
36
+ if (!letters)
37
+ return true;
38
+ if (/^(?:https?:\/\/|www\.|mailto:)\S*$|^[^\s@]+@[^\s@]+\.[^\s@]+$/i.test(text))
39
+ return true;
40
+ return letters <= 5 && !/\p{Ll}/u.test(text);
41
+ }
23
42
  function classifyValue(value) {
24
43
  if (value === undefined || value === null)
25
44
  return 'absent';
@@ -321,12 +340,23 @@ async function generateStatusReport(config) {
321
340
  // surfaced as well. For the primary, an empty value is a deliberate
322
341
  // placeholder and counts as present — only truly absent keys are flagged.
323
342
  const localesToCheck = [primaryLanguage, ...secondaryLanguages.filter((l) => l !== primaryLanguage)];
343
+ // `status.checkIdentical`: values identical to the primary language's. Only `'error'` counts them as untranslated.
344
+ const identicalSetting = config.status?.checkIdentical;
345
+ const checkIdentical = identicalSetting !== false && identicalSetting !== 'off';
346
+ const isDone = (state) => state === 'translated' || (state === 'identical' && identicalSetting !== 'error');
347
+ const primaryTranslationsByNs = new Map();
348
+ const baseLanguage = (lng) => lng.split(/[-_]/)[0].toLowerCase();
349
+ // a plural form the primary language lacks (ru `_few`) is compared with its `_other`
350
+ const nonOtherPluralSuffix = new RegExp(`${escapeRegex(pluralSeparator)}(?:zero|one|two|few|many)$`);
324
351
  for (const locale of localesToCheck) {
325
352
  const isPrimary = locale === primaryLanguage;
353
+ // en-GB keeps most of the en values
354
+ const compareWithPrimary = checkIdentical && !isPrimary && baseLanguage(locale) !== baseLanguage(primaryLanguage);
326
355
  let totalTranslatedForLocale = 0;
327
356
  let totalEmptyForLocale = 0;
328
357
  let totalAbsentForLocale = 0;
329
358
  let totalOptionalForLocale = 0;
359
+ let totalIdenticalForLocale = 0;
330
360
  let totalKeysForLocale = 0;
331
361
  const namespaces = new Map();
332
362
  const mergedTranslations = mergeNamespaces
@@ -373,6 +403,9 @@ async function generateStatusReport(config) {
373
403
  // when mergedTranslations[ns] is missing.
374
404
  ? (mergedTranslations?.[ns] ?? mergedTranslations ?? {})
375
405
  : await loadTranslationFile(resolve(process.cwd(), getOutputPath(config.extract.output, locale, ns))) || {};
406
+ if (isPrimary)
407
+ primaryTranslationsByNs.set(ns, translationsForNs);
408
+ const primaryTranslations = primaryTranslationsByNs.get(ns);
376
409
  const fallbackTranslationsList = [];
377
410
  for (const fallbackNs of fallbackNamespaces) {
378
411
  if (ns === fallbackNs)
@@ -383,8 +416,21 @@ async function generateStatusReport(config) {
383
416
  let emptyInNs = 0;
384
417
  let absentInNs = 0;
385
418
  let optionalInNs = 0;
419
+ let identicalInNs = 0;
386
420
  let totalInNs = 0;
387
421
  const keyDetails = [];
422
+ const tally = (key, state) => {
423
+ totalInNs++;
424
+ if (isDone(state))
425
+ translatedInNs++;
426
+ else if (state === 'empty')
427
+ emptyInNs++;
428
+ else if (state === 'absent')
429
+ absentInNs++;
430
+ if (state === 'identical')
431
+ identicalInNs++;
432
+ keyDetails.push({ key, state });
433
+ };
388
434
  // Get the plural categories for THIS specific locale
389
435
  const getLocalePluralCategories = (locale, isOrdinal) => {
390
436
  try {
@@ -427,6 +473,13 @@ async function generateStatusReport(config) {
427
473
  // key (used in code, missing from the file) is a problem here.
428
474
  if (isPrimary && state === 'empty')
429
475
  return 'translated';
476
+ // English copied into `de` (a fallback-namespace value is not this locale's own)
477
+ if (compareWithPrimary && primaryState === 'translated' && primaryTranslations && typeof primaryValue === 'string') {
478
+ const sourceValue = getNestedValue(primaryTranslations, key, sep) ??
479
+ getNestedValue(primaryTranslations, key.replace(nonOtherPluralSuffix, `${pluralSeparator}other`), sep);
480
+ if (primaryValue === sourceValue && !staysTheSame(primaryValue, config))
481
+ return 'identical';
482
+ }
430
483
  return state;
431
484
  };
432
485
  const processedKeys = new Set();
@@ -458,19 +511,12 @@ async function generateStatusReport(config) {
458
511
  // it isn't translated — whether absent or an empty placeholder that
459
512
  // `extract` wrote. It is never a hard failure. See #270 and
460
513
  // getOptionalPluralCategories.
461
- if (state !== 'translated' && optionalCategories.has(category)) {
514
+ if (!isDone(state) && optionalCategories.has(category)) {
462
515
  optionalInNs++;
463
516
  keyDetails.push({ key: baseKey, state: 'optional' });
464
517
  }
465
518
  else {
466
- totalInNs++;
467
- if (state === 'translated')
468
- translatedInNs++;
469
- else if (state === 'empty')
470
- emptyInNs++;
471
- else
472
- absentInNs++;
473
- keyDetails.push({ key: baseKey, state });
519
+ tally(baseKey, state);
474
520
  }
475
521
  }
476
522
  }
@@ -496,14 +542,7 @@ async function generateStatusReport(config) {
496
542
  // resolves count via the bare key, so it satisfies the family on
497
543
  // its own — don't demand plural variants that were never written.
498
544
  processedKeys.add(baseKey);
499
- totalInNs++;
500
- if (bareState === 'translated')
501
- translatedInNs++;
502
- else if (bareState === 'empty')
503
- emptyInNs++;
504
- else
505
- absentInNs++;
506
- keyDetails.push({ key: baseKey, state: bareState });
545
+ tally(baseKey, bareState);
507
546
  }
508
547
  else {
509
548
  // Convention (b): plural variants exist (or the family is missing
@@ -517,19 +556,12 @@ async function generateStatusReport(config) {
517
556
  const state = resolveAndClassify(pluralKey);
518
557
  // An optional category (e.g. French `_many`) is a soft note
519
558
  // whenever it isn't translated — never a hard failure. See #270.
520
- if (state !== 'translated' && optionalCategories.has(category)) {
559
+ if (!isDone(state) && optionalCategories.has(category)) {
521
560
  optionalInNs++;
522
561
  keyDetails.push({ key: pluralKey, state: 'optional' });
523
562
  continue;
524
563
  }
525
- totalInNs++;
526
- if (state === 'translated')
527
- translatedInNs++;
528
- else if (state === 'empty')
529
- emptyInNs++;
530
- else
531
- absentInNs++;
532
- keyDetails.push({ key: pluralKey, state });
564
+ tally(pluralKey, state);
533
565
  }
534
566
  }
535
567
  }
@@ -537,15 +569,7 @@ async function generateStatusReport(config) {
537
569
  else {
538
570
  if (!processedKeys.has(baseKey)) {
539
571
  processedKeys.add(baseKey);
540
- totalInNs++;
541
- const state = resolveAndClassify(baseKey);
542
- if (state === 'translated')
543
- translatedInNs++;
544
- else if (state === 'empty')
545
- emptyInNs++;
546
- else
547
- absentInNs++;
548
- keyDetails.push({ key: baseKey, state });
572
+ tally(baseKey, resolveAndClassify(baseKey));
549
573
  }
550
574
  }
551
575
  }
@@ -556,21 +580,14 @@ async function generateStatusReport(config) {
556
580
  if (processedKeys.has(variantKey))
557
581
  continue;
558
582
  processedKeys.add(variantKey);
559
- totalInNs++;
560
- const state = resolveAndClassify(variantKey);
561
- if (state === 'translated')
562
- translatedInNs++;
563
- else if (state === 'empty')
564
- emptyInNs++;
565
- else
566
- absentInNs++;
567
- keyDetails.push({ key: variantKey, state });
583
+ tally(variantKey, resolveAndClassify(variantKey));
568
584
  }
569
- namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, optionalKeys: optionalInNs, keyDetails });
585
+ namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, optionalKeys: optionalInNs, identicalKeys: identicalInNs, keyDetails });
570
586
  totalTranslatedForLocale += translatedInNs;
571
587
  totalEmptyForLocale += emptyInNs;
572
588
  totalAbsentForLocale += absentInNs;
573
589
  totalOptionalForLocale += optionalInNs;
590
+ totalIdenticalForLocale += identicalInNs;
574
591
  totalKeysForLocale += totalInNs;
575
592
  }
576
593
  const localeStatus = {
@@ -579,6 +596,7 @@ async function generateStatusReport(config) {
579
596
  totalEmpty: totalEmptyForLocale,
580
597
  totalAbsent: totalAbsentForLocale,
581
598
  totalOptional: totalOptionalForLocale,
599
+ totalIdentical: totalIdenticalForLocale,
582
600
  namespaces,
583
601
  };
584
602
  if (isPrimary) {
@@ -594,14 +612,24 @@ async function generateStatusReport(config) {
594
612
  * Builds a compact breakdown string like "3 untranslated, 2 absent" for use in
595
613
  * summary lines. Returns an empty string when there is nothing to report.
596
614
  */
597
- function buildBreakdown(emptyCount, absentCount) {
615
+ function buildBreakdown(emptyCount, absentCount, identicalCount = 0, primaryLanguage = '') {
598
616
  const parts = [];
599
617
  if (emptyCount > 0)
600
618
  parts.push(styleText('yellow', `${emptyCount} untranslated`));
619
+ if (identicalCount > 0)
620
+ parts.push(styleText('yellow', `${identicalCount} identical to ${primaryLanguage}`));
601
621
  if (absentCount > 0)
602
622
  parts.push(styleText('red', `${absentCount} absent`));
603
623
  return parts.join(', ');
604
624
  }
625
+ /**
626
+ * The funnel's gap for a locale: untranslated keys, plus the values identical to the
627
+ * primary language that `'warn'` (default) still counts as translated.
628
+ */
629
+ function funnelGap(config, locale, data) {
630
+ const identicalCountedAsTranslated = config.status?.checkIdentical === 'error' ? 0 : data.identical;
631
+ return { locale, untranslated: data.totalKeys - data.translated + identicalCountedAsTranslated, identical: data.identical };
632
+ }
605
633
  /**
606
634
  * Main display router that calls the appropriate display function based on options.
607
635
  *
@@ -647,7 +675,8 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
647
675
  console.log(styleText('bold', `\nKey Status for "${styleText('cyan', locale)}":`));
648
676
  const totalKeysForLocale = localeData.totalKeys;
649
677
  printProgressBar('Overall', localeData.totalTranslated, totalKeysForLocale);
650
- const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
678
+ const primaryLanguage = config.extract.primaryLanguage ?? '';
679
+ const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent, localeData.totalIdentical, primaryLanguage);
651
680
  if (breakdown)
652
681
  console.log(` ${breakdown}`);
653
682
  const namespacesToDisplay = namespaceFilter ? [namespaceFilter] : Array.from(localeData.namespaces.keys()).sort();
@@ -657,7 +686,7 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
657
686
  continue;
658
687
  console.log(styleText(['cyan', 'bold'], `\nNamespace: ${ns}`));
659
688
  printProgressBar('Namespace Progress', nsData.translatedKeys, nsData.totalKeys);
660
- const nsBreakdown = buildBreakdown(nsData.emptyKeys, nsData.absentKeys);
689
+ const nsBreakdown = buildBreakdown(nsData.emptyKeys, nsData.absentKeys, nsData.identicalKeys, primaryLanguage);
661
690
  if (nsBreakdown)
662
691
  console.log(` ${nsBreakdown}`);
663
692
  const keysToDisplay = hideTranslated
@@ -673,6 +702,9 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
673
702
  else if (state === 'optional') {
674
703
  console.log(` ${styleText('gray', '○')} ${key} ${styleText('gray', '(optional plural form)')}`);
675
704
  }
705
+ else if (state === 'identical') {
706
+ console.log(` ${styleText('yellow', '≈')} ${key} ${styleText('yellow', `(identical to ${primaryLanguage})`)}`);
707
+ }
676
708
  else {
677
709
  console.log(` ${styleText('red', '✗')} ${key} ${styleText('red', '(absent)')}`);
678
710
  }
@@ -684,7 +716,7 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
684
716
  console.log(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.`));
685
717
  }
686
718
  else {
687
- const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
719
+ const summaryBreakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent, config.status?.checkIdentical === 'error' ? localeData.totalIdentical : 0, primaryLanguage);
688
720
  console.log(styleText(['yellow', 'bold'], `\nSummary: Found ${missingCount} incomplete translations for "${locale}" — ${summaryBreakdown}.`));
689
721
  }
690
722
  }
@@ -694,11 +726,16 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
694
726
  else {
695
727
  console.log(styleText(['green', 'bold'], `\nSummary: 🎉 All keys are translated for "${locale}".`));
696
728
  }
729
+ if (localeData.totalIdentical > 0 && config.status?.checkIdentical !== 'error') {
730
+ console.log(styleText('yellow', `${localeData.totalIdentical} value(s) are identical to "${primaryLanguage}" and may still need translating. Values that stay the same go into status.ignoreKeys.`));
731
+ }
697
732
  // Untranslated keys in a secondary locale are the gap Locize fills; absent
698
733
  // keys in the primary language are an `extract` problem (handled above).
699
734
  const nsData = namespaceFilter ? localeData.namespaces.get(namespaceFilter) : undefined;
700
- const untranslated = nsData ? nsData.totalKeys - nsData.translatedKeys : missingCount;
701
- await printUntranslatedFunnel('status', isPrimary ? [] : [{ locale, untranslated }], LOCIZE_SIGNUP_URL);
735
+ const gap = nsData
736
+ ? funnelGap(config, locale, { totalKeys: nsData.totalKeys, translated: nsData.translatedKeys, identical: nsData.identicalKeys })
737
+ : funnelGap(config, locale, { totalKeys: totalKeysForLocale, translated: localeData.totalTranslated, identical: localeData.totalIdentical });
738
+ await printUntranslatedFunnel('status', isPrimary ? [] : [gap], LOCIZE_SIGNUP_URL);
702
739
  }
703
740
  /**
704
741
  * Displays a summary report filtered by a single namespace.
@@ -723,7 +760,7 @@ async function displayNamespaceSummaryReport(report, config, namespace) {
723
760
  if (nsLocaleData) {
724
761
  const percentage = nsLocaleData.totalKeys > 0 ? Math.round((nsLocaleData.translatedKeys / nsLocaleData.totalKeys) * 100) : 100;
725
762
  const bar = generateProgressBarText(percentage);
726
- const breakdown = buildBreakdown(nsLocaleData.emptyKeys, nsLocaleData.absentKeys);
763
+ const breakdown = buildBreakdown(nsLocaleData.emptyKeys, nsLocaleData.absentKeys, nsLocaleData.identicalKeys, config.extract.primaryLanguage);
727
764
  const suffix = breakdown ? ` — ${breakdown}` : '';
728
765
  console.log(`- ${locale}: ${bar} ${percentage}% (${nsLocaleData.translatedKeys}/${nsLocaleData.totalKeys} keys)${suffix}`);
729
766
  }
@@ -735,7 +772,9 @@ async function displayNamespaceSummaryReport(report, config, namespace) {
735
772
  }
736
773
  const gaps = Array.from(report.locales, ([locale, localeData]) => {
737
774
  const nsLocaleData = localeData.namespaces.get(namespace);
738
- return { locale, untranslated: nsLocaleData ? nsLocaleData.totalKeys - nsLocaleData.translatedKeys : 0 };
775
+ return nsLocaleData
776
+ ? funnelGap(config, locale, { totalKeys: nsLocaleData.totalKeys, translated: nsLocaleData.translatedKeys, identical: nsLocaleData.identicalKeys })
777
+ : { locale, untranslated: 0 };
739
778
  });
740
779
  await printUntranslatedFunnel('status', gaps, LOCIZE_SIGNUP_URL);
741
780
  }
@@ -763,7 +802,7 @@ async function displayOverallSummaryReport(report, config) {
763
802
  for (const [locale, localeData] of report.locales.entries()) {
764
803
  const percentage = localeData.totalKeys > 0 ? Math.round((localeData.totalTranslated / localeData.totalKeys) * 100) : 100;
765
804
  const bar = generateProgressBarText(percentage);
766
- const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent);
805
+ const breakdown = buildBreakdown(localeData.totalEmpty, localeData.totalAbsent, localeData.totalIdentical, primaryLanguage);
767
806
  const suffix = breakdown ? ` — ${breakdown}` : '';
768
807
  console.log(`- ${locale}: ${bar} ${percentage}% (${localeData.totalTranslated}/${localeData.totalKeys} keys)${suffix}`);
769
808
  }
@@ -771,7 +810,7 @@ async function displayOverallSummaryReport(report, config) {
771
810
  console.log(styleText(['red', 'bold'], `\n⚠ Primary language "${primaryLanguage}" is missing ${report.primary.totalAbsent} key(s) that are used in code.`));
772
811
  console.log(styleText('red', ` Run "i18next-cli status ${primaryLanguage}" for details, or "i18next-cli extract" to add them.`));
773
812
  }
774
- const gaps = Array.from(report.locales, ([locale, localeData]) => ({ locale, untranslated: localeData.totalKeys - localeData.totalTranslated }));
813
+ const gaps = Array.from(report.locales, ([locale, localeData]) => funnelGap(config, locale, { totalKeys: localeData.totalKeys, translated: localeData.totalTranslated, identical: localeData.totalIdentical }));
775
814
  await printUntranslatedFunnel('status', gaps, LOCIZE_SIGNUP_URL);
776
815
  }
777
816
  /**
@@ -0,0 +1,67 @@
1
+ import { writeFile, readFile } from 'node:fs/promises';
2
+ import { resolve, relative, sep } from 'node:path';
3
+
4
+ /** The baseline file: `lint.baseline`, default `i18next-lint-baseline.json` in the working directory. */
5
+ const lintBaselinePath = (config) => resolve(process.cwd(), config.lint?.baseline ?? 'i18next-lint-baseline.json');
6
+ const fileKey = (file) => relative(process.cwd(), resolve(process.cwd(), file)).split(sep).join('/');
7
+ const issueKey = (issue) => `${issue.type ?? 'hardcoded'}: ${issue.text}`;
8
+ /** The baseline, or undefined when the file does not exist. A file that does not parse throws. */
9
+ async function readLintBaseline(path) {
10
+ let content;
11
+ try {
12
+ content = await readFile(path, 'utf-8');
13
+ }
14
+ catch {
15
+ return undefined;
16
+ }
17
+ try {
18
+ return JSON.parse(content);
19
+ }
20
+ catch (err) {
21
+ throw new Error(`could not parse the lint baseline ${path}: ${err?.message ?? err}. Run "npx i18next-cli lint --update-baseline" to write it again.`);
22
+ }
23
+ }
24
+ /** Writes every issue into the baseline, sorted for stable diffs. Returns the number of issues written. */
25
+ async function writeLintBaseline(path, files) {
26
+ const baseline = {};
27
+ let count = 0;
28
+ for (const [file, issues] of Object.entries(files).sort(([a], [b]) => fileKey(a).localeCompare(fileKey(b)))) {
29
+ const counts = {};
30
+ for (const key of issues.map(issueKey).sort())
31
+ counts[key] = (counts[key] ?? 0) + 1;
32
+ baseline[fileKey(file)] = counts;
33
+ count += issues.length;
34
+ }
35
+ await writeFile(path, JSON.stringify(baseline, null, 2) + '\n');
36
+ return count;
37
+ }
38
+ /**
39
+ * Leaves out the issues the baseline holds. Returns the remaining issues, how many were left out,
40
+ * and how many baseline entries no longer occur (fixed issues, to drop with `--update-baseline`).
41
+ */
42
+ function applyLintBaseline(files, baseline) {
43
+ const left = new Map(Object.entries(baseline).map(([file, counts]) => [file, { ...counts }]));
44
+ const remaining = {};
45
+ let existing = 0;
46
+ for (const [file, issues] of Object.entries(files)) {
47
+ const counts = left.get(fileKey(file));
48
+ const fresh = issues.filter(issue => {
49
+ const key = issueKey(issue);
50
+ if (!counts?.[key])
51
+ return true;
52
+ counts[key]--;
53
+ existing++;
54
+ return false;
55
+ });
56
+ if (fresh.length)
57
+ remaining[file] = fresh;
58
+ }
59
+ let stale = 0;
60
+ for (const counts of left.values()) {
61
+ for (const n of Object.values(counts))
62
+ stale += n;
63
+ }
64
+ return { files: remaining, existing, stale };
65
+ }
66
+
67
+ export { applyLintBaseline, lintBaselinePath, readLintBaseline, writeLintBaseline };
@@ -20,7 +20,9 @@ async function printUntranslatedFunnel(funnelKey, gaps, signupUrl, log = console
20
20
  const where = open.length === 1
21
21
  ? `in ${open[0].locale}`
22
22
  : `(${open.map(g => `${g.locale} ${g.untranslated}`).join(', ')})`;
23
- log(`\n💡 ${total} untranslated key${total === 1 ? '' : 's'} ${where}. Translate them with AI in one command: ${styleText('cyan', 'npx i18next-cli localize')} (sign up: ${signupUrl})`);
23
+ const identical = open.reduce((sum, g) => sum + (g.identical ?? 0), 0);
24
+ const copied = identical ? `, ${identical} of them still identical to the primary language` : '';
25
+ log(`\n💡 ${total} untranslated key${total === 1 ? '' : 's'} ${where}${copied}. Translate them with AI in one command: ${styleText('cyan', 'npx i18next-cli localize')} (sign up: ${signupUrl})`);
24
26
  return recordFunnelShown(funnelKey);
25
27
  }
26
28
 
@@ -3,7 +3,28 @@ import { basename, resolve } from 'node:path';
3
3
  import { glob } from 'glob';
4
4
  import { parseTree, findNodeAtLocation } from 'jsonc-parser';
5
5
  import { getOutputPath, loadTranslationFile } from './file-utils.js';
6
+ import { parseNestedReferences } from './nesting.js';
6
7
 
8
+ const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
9
+ /**
10
+ * The variable names of the i18next interpolations in a value: `{{name}}`, `{{- name}}` (unescaped),
11
+ * `{{val, number}}` and `{{ user.name }}` give `name`, `name`, `val` and `user.name`.
12
+ * Read like i18next's Interpolator: anything between prefix and suffix, trimmed, a `-` right after the
13
+ * prefix marks it unescaped, and a format follows the first `,`.
14
+ * ponytail: i18next's defaults for unescapePrefix (`-`) and formatSeparator (`,`); custom ones are not read.
15
+ */
16
+ function interpolationNames(value, extract) {
17
+ const prefix = escapeRegExp(extract.interpolationPrefix ?? '{{');
18
+ const suffix = escapeRegExp(extract.interpolationSuffix ?? '}}');
19
+ const names = [];
20
+ for (const [, inner] of value.matchAll(new RegExp(`${prefix}(.+?)${suffix}`, 'g'))) {
21
+ const name = inner.replace(/^-/, '').split(',')[0].trim();
22
+ // a brace means ICU (`one {{count} item}`) in a project without extract.messageFormat, not a variable
23
+ if (name && !/[{}]/.test(name))
24
+ names.push(name);
25
+ }
26
+ return names;
27
+ }
7
28
  /**
8
29
  * True for `extract.messageFormat` `'icu'` and `'mf2'`. These formats put plurals and selects into the
9
30
  * message itself and have no `$t()` nesting, so the CLI writes no plural or context suffix keys for them.
@@ -220,6 +241,15 @@ async function lineFinder(file) {
220
241
  return node ? content.slice(0, node.parent?.offset ?? node.offset).split('\n').length : 0;
221
242
  };
222
243
  }
244
+ // Namespace discovery as in `sync`: the primary language's files
245
+ async function primaryNamespaces(config, primary) {
246
+ const { output, ignoreNamespaces = [] } = config.extract;
247
+ if (typeof output === 'string' && !output.includes('{{namespace}}'))
248
+ return [undefined];
249
+ return (await glob(getOutputPath(output, primary, '*').replace(/\\/g, '/')))
250
+ .map(file => basename(file).split('.')[0])
251
+ .filter(ns => !ignoreNamespaces.includes(ns));
252
+ }
223
253
  /**
224
254
  * Checks every translation value of every locale for `extract.messageFormat` `'icu'` or `'mf2'`:
225
255
  * syntax, argument names against the primary language, and plural categories per locale.
@@ -229,16 +259,11 @@ async function lintMessageFormatResources(config, analyze) {
229
259
  const isMf2 = config.extract.messageFormat === 'mf2';
230
260
  const formatName = isMf2 ? 'MF2' : 'ICU';
231
261
  const arg = (name) => isMf2 ? `{$${name}}` : `{${name}}`;
232
- const { output, ignoreNamespaces = [] } = config.extract;
262
+ const { output } = config.extract;
233
263
  const keySeparator = config.extract.keySeparator || '.';
234
264
  const primary = config.extract.primaryLanguage || config.locales[0] || 'en';
235
265
  const locales = [primary, ...config.locales.filter(l => l !== primary)];
236
- // Namespace discovery as in `sync`: the primary language's files
237
- const namespaces = typeof output === 'string' && !output.includes('{{namespace}}')
238
- ? [undefined]
239
- : (await glob(getOutputPath(output, primary, '*').replace(/\\/g, '/')))
240
- .map(file => basename(file).split('.')[0])
241
- .filter(ns => !ignoreNamespaces.includes(ns));
266
+ const namespaces = await primaryNamespaces(config, primary);
242
267
  const issuesByFile = new Map();
243
268
  for (const ns of namespaces) {
244
269
  let primaryShapes = new Map();
@@ -301,5 +326,94 @@ async function lintMessageFormatResources(config, analyze) {
301
326
  }
302
327
  return issuesByFile;
303
328
  }
329
+ /**
330
+ * Checks the translation values of every locale in the i18next format against the primary language: the
331
+ * interpolations (by name, so `{{val, number}}` and `{{ val }}` are both `val`), the nested `$t(key)` references and
332
+ * the tags (`<0>`, `<1/>`, `<bold>`), except the basic HTML react-i18next keeps (`transKeepBasicHtmlNodesFor`).
333
+ * Plural forms are compared as a group (the union over `_one`, `_other`, ...), since a language may leave `{{count}}`
334
+ * out of `_one` or `_zero` and has forms the primary language lacks.
335
+ * The same idea as Locize's check 240 (`checkI18nFeatures`). Returns the issues per translation file.
336
+ * ponytail: a placeholder dropped from one plural form while another form keeps it passes; a per-form rule would flag `{{count}}`.
337
+ */
338
+ async function lintI18nextResources(config, severity) {
339
+ const { output, interpolationPrefix = '{{', interpolationSuffix = '}}', nestingPrefix = '$t(', nestingSuffix = ')', nestingOptionsSeparator } = config.extract;
340
+ const keySeparator = config.extract.keySeparator || '.';
341
+ const nsSeparator = config.extract.nsSeparator ?? ':';
342
+ // the suffixes i18next's PluralResolver appends: `_one`, `_ordinal_two`, and `_zero` for a count of 0
343
+ const s = escapeRegExp(config.extract.pluralSeparator ?? '_');
344
+ const pluralSuffix = new RegExp(`(?:${s}ordinal)?${s}(?:zero|one|two|few|many|other)$`);
345
+ // react-i18next's default, src/defaults.js
346
+ const keptHtml = new Set(config.extract.transKeepBasicHtmlNodesFor ?? ['br', 'strong', 'i', 'p']);
347
+ const primary = config.extract.primaryLanguage || config.locales[0] || 'en';
348
+ const locales = config.locales.filter(l => l !== primary);
349
+ const placeholders = (value) => [
350
+ ...interpolationNames(value, config.extract).map(name => `${interpolationPrefix}${name}${interpolationSuffix}`),
351
+ ...parseNestedReferences(value, { nestingPrefix, nestingSuffix, nestingOptionsSeparator, nsSeparator })
352
+ .map(ref => `${nestingPrefix}${ref.ns ? `${ref.ns}${nsSeparator}` : ''}${ref.key}${nestingSuffix}`),
353
+ // <Trans> renders <0>…</0> from its children and <bold> from its components; an unknown tag shows up as
354
+ // text. The kept basic HTML (<br/>, <strong>) is rendered as is, so a language may add or drop it.
355
+ ...[...value.matchAll(/<([A-Za-z0-9][\w.:-]*)(?:\s(?:"[^"]*"|'[^']*'|[^'">])*)?\/?>/g)]
356
+ .filter(match => !keptHtml.has(match[1]))
357
+ .map(match => `<${match[1]}>`),
358
+ ];
359
+ const groupsOf = (resources) => {
360
+ const groups = new Map();
361
+ for (const [path, value] of leaves(resources)) {
362
+ if (typeof value !== 'string')
363
+ continue;
364
+ const key = path.join(keySeparator);
365
+ const base = key.replace(pluralSuffix, '');
366
+ let group = groups.get(base);
367
+ if (!group)
368
+ groups.set(base, group = { path, label: key, values: 0, empty: false, tokens: new Set() });
369
+ else
370
+ group.label = base;
371
+ if (value === '') {
372
+ group.empty = true;
373
+ continue;
374
+ }
375
+ group.values++;
376
+ for (const token of placeholders(value))
377
+ group.tokens.add(token);
378
+ }
379
+ return groups;
380
+ };
381
+ // A file that does not parse makes `extract`, `sync` and `status` fail loudly, so `lint` skips it
382
+ const load = (file) => loadTranslationFile(file).catch(() => null);
383
+ const issuesByFile = new Map();
384
+ for (const ns of await primaryNamespaces(config, primary)) {
385
+ const primaryResources = await load(getOutputPath(output, primary, ns));
386
+ if (!primaryResources)
387
+ continue;
388
+ const primaryGroups = groupsOf(primaryResources);
389
+ for (const lng of locales) {
390
+ const file = getOutputPath(output, lng, ns);
391
+ const resources = await load(file);
392
+ if (!resources)
393
+ continue;
394
+ const problems = [];
395
+ for (const [base, group] of groupsOf(resources)) {
396
+ const source = primaryGroups.get(base);
397
+ if (!source?.values || !group.values)
398
+ continue;
399
+ // a partly translated plural may still lack the form that carries {{count}}
400
+ const missing = group.empty ? [] : [...source.tokens].filter(t => !group.tokens.has(t));
401
+ const unexpected = [...group.tokens].filter(t => !source.tokens.has(t));
402
+ if (!missing.length && !unexpected.length)
403
+ continue;
404
+ const diff = [
405
+ missing.length ? `missing ${missing.join(', ')}` : '',
406
+ unexpected.length ? `unexpected ${unexpected.join(', ')}` : '',
407
+ ].filter(Boolean).join(', ');
408
+ problems.push({ path: group.path, text: `${group.label}: ${diff} (compared with "${primary}")` });
409
+ }
410
+ if (problems.length) {
411
+ const lineOf = await lineFinder(file);
412
+ issuesByFile.set(file, problems.map(({ path, text }) => ({ text, line: lineOf(path), type: 'placeholder', severity })));
413
+ }
414
+ }
415
+ }
416
+ return issuesByFile;
417
+ }
304
418
 
305
- export { lintMessageFormatResources, loadMessageAnalyzer, pluralCategories, toMessageFormatPlaceholders, usesMessageFormat };
419
+ export { interpolationNames, lintI18nextResources, lintMessageFormatResources, loadMessageAnalyzer, pluralCategories, toMessageFormatPlaceholders, usesMessageFormat };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "i18next-cli",
3
- "version": "1.79.0",
3
+ "version": "1.80.0",
4
4
  "description": "A unified, high-performance i18next CLI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC,QAAA,MAAM,OAAO,SAAgB,CAAA;AA+e7B,OAAO,EAAE,OAAO,EAAE,CAAA"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC,QAAA,MAAM,OAAO,SAAgB,CAAA;AAgf7B,OAAO,EAAE,OAAO,EAAE,CAAA"}
package/types/linter.d.ts CHANGED
@@ -11,6 +11,10 @@ type LinterEventMap = {
11
11
  success: boolean;
12
12
  message: string;
13
13
  files: Record<string, LintIssue[]>;
14
+ /** Issues left out because the baseline file holds them */
15
+ existingIssues: number;
16
+ /** Baseline entries that no longer occur */
17
+ staleBaselineEntries: number;
14
18
  }
15
19
  ];
16
20
  error: [error: Error];
@@ -22,12 +26,17 @@ export declare class Linter extends EventEmitter<LinterEventMap> {
22
26
  private logger;
23
27
  constructor(config: I18nextToolkitConfig, logger?: Logger);
24
28
  wrapError(error: unknown): Error;
25
- run(): Promise<{
29
+ /** @param options.ignoreBaseline - report every issue, also those the baseline file holds (`lint --update-baseline`) */
30
+ run(options?: {
31
+ ignoreBaseline?: boolean;
32
+ }): Promise<{
26
33
  success: boolean;
27
34
  message: string;
28
35
  files: {
29
36
  [k: string]: LintIssue[];
30
37
  };
38
+ existingIssues: number;
39
+ staleBaselineEntries: number;
31
40
  }>;
32
41
  private createLintPluginContext;
33
42
  private initializeLintPlugins;
@@ -71,10 +80,13 @@ export declare function runLinter(config: I18nextToolkitConfig): Promise<{
71
80
  files: {
72
81
  [k: string]: LintIssue[];
73
82
  };
83
+ existingIssues: number;
84
+ staleBaselineEntries: number;
74
85
  }>;
75
86
  export declare function runLinterCli(config: I18nextToolkitConfig, options?: {
76
87
  quiet?: boolean;
77
88
  logger?: Logger;
89
+ updateBaseline?: boolean;
78
90
  }): Promise<void>;
79
91
  export {};
80
92
  //# sourceMappingURL=linter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../src/linter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAQ1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,SAAS,EAA6B,MAAM,YAAY,CAAA;AAsfpG,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE;QAAC;YACT,OAAO,EAAE,MAAM,CAAC;SACjB;KAAC,CAAC;IACH,IAAI,EAAE;QAAC;YACL,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;SACpC;KAAC,CAAC;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,MAAM,EAAiD,CAAA;AAC7F,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAAqD,CAAA;AAKvG,qBAAa,MAAO,SAAQ,YAAY,CAAC,cAAc,CAAC;IACtD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAQ;gBAET,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAE,MAA4B;IAM/E,SAAS,CAAE,KAAK,EAAE,OAAO;IAanB,GAAG;;;;;;;IAgJT,OAAO,CAAC,uBAAuB;YAOjB,qBAAqB;IAWnC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,0BAA0B;YAUpB,qBAAqB;YAgBrB,uBAAuB;CAgBtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB;;;;;;GAE5D;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,iBAiDnD"}
1
+ {"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../src/linter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAU1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,SAAS,EAA6B,MAAM,YAAY,CAAA;AAuepG,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE;QAAC;YACT,OAAO,EAAE,MAAM,CAAC;SACjB;KAAC,CAAC;IACH,IAAI,EAAE;QAAC;YACL,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;YACnC,2DAA2D;YAC3D,cAAc,EAAE,MAAM,CAAC;YACvB,4CAA4C;YAC5C,oBAAoB,EAAE,MAAM,CAAC;SAC9B;KAAC,CAAC;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,MAAM,EAAiD,CAAA;AAC7F,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAAqD,CAAA;AAKvG,qBAAa,MAAO,SAAQ,YAAY,CAAC,cAAc,CAAC;IACtD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAQ;gBAET,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAE,MAA4B;IAM/E,SAAS,CAAE,KAAK,EAAE,OAAO;IAazB,wHAAwH;IAClH,GAAG,CAAE,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO;;;;;;;;;IAiKrD,OAAO,CAAC,uBAAuB;YAOjB,qBAAqB;IAWnC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,0BAA0B;YAUpB,qBAAqB;YAgBrB,uBAAuB;CAgBtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB;;;;;;;;GAE5D;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,iBAwE7E"}
@@ -10,5 +10,5 @@
10
10
  * Locize is optional in this flow: the developer is asked once (step 2) and
11
11
  * nothing Locize-related happens unless they said yes.
12
12
  */
13
- export declare const AGENT_PROMPT = "You are localizing this app with i18next. Locize, the translation management\nservice by the i18next maintainers, is optional: the developer decides in\nstep 2 and nothing Locize-related happens unless they say yes. Execute these\nsteps in order, verifying each before continuing. Use `npx i18next-cli` for\nall commands.\n\n1. Detect: confirm this is a React/Next.js project (check package.json).\n - If Vue/Svelte: install a stack plugin (`i18next-cli-vue` /\n `i18next-cli-plugin-svelte`) and add it to the `plugins` array of\n i18next.config.ts, or write one via the plugin hooks\n (instrumentOnLoad/onLoad) instead of wrapping strings manually.\n - If the app uses inlang Paraglide (`@inlang/paraglide-js`), STOP:\n instrumenting i18next calls would conflict; ask the user how to proceed.\n2. Ask, then configure: if no i18next.config.{ts,js} exists, ask the\n developer one question before anything else: \"Do you want to manage the\n translations with Locize (AI pre-translation with review, CDN delivery\n without redeploying, free plan available), or keep the translation files\n in the repository only?\" Then create the config without the wizard:\n `npx i18next-cli init --yes --locales <langs> --backend local` or\n `--backend locize --project-id <id>` (add --input/--output if the\n detected paths are wrong). Do not create a Locize project, open a signup\n page or ask for an API key unless they chose Locize. Offer\n `--agent-note`, which adds a short note about the setup to AGENTS.md\n for future agent sessions.\n3. Instrument: run `npx i18next-cli instrument --dry-run` and review the\n planned changes; then `npx i18next-cli instrument` to apply. Inspect the\n git diff carefully: fix any t() wrapping inside Next.js *server components*\n (add 'use client' or refactor to a server-side t() pattern). Commit.\n4. Extract: run `npx i18next-cli extract`. Verify the locale JSON files were\n written (check the extract.output path in the config). If the developer\n chose repository files only: translate the extracted keys yourself or\n leave them to the team, run `npx i18next-cli status` to confirm every\n language is complete, and stop here.\n5. Locize (only if the developer chose it in step 2): ask them for\n LOCIZE_PROJECTID and LOCIZE_API_KEY (they create the project at\n https://www.locize.app/register?from=i18next_cli__agent-prompt\n any write-capable API key works; the target languages from\n i18next.config.ts are created automatically on the first sync.\n Auto-translation and quality estimation are enabled by default for new\n projects; translations run once the project is subscribed or an AI/MT\n provider is configured). Export both as environment variables.\n6. Translate & deliver (Locize only):\n `npx i18next-cli locize-sync --auto-translate true`\n then `npx i18next-cli locize-download` to pull the AI translations, and\n `npx i18next-cli status` to confirm all languages are (near) 100%.\n AI translation is asynchronous; if targets are still empty, wait a minute\n and re-run locize-download.\n7. Optionally (Locize only) switch runtime loading to i18next-locize-backend\n (CDN delivery, so translation fixes go live without redeploying).\n NEVER put the API key in client-side code; the CDN only needs the\n project ID.\n";
13
+ export declare const AGENT_PROMPT = "You are localizing this app with i18next. Locize, the translation management\nservice by the i18next maintainers, is optional: the developer decides in\nstep 2 and nothing Locize-related happens unless they say yes. Execute these\nsteps in order, verifying each before continuing. Use `npx i18next-cli` for\nall commands.\n\n1. Detect: confirm this is a React/Next.js project (check package.json).\n - If Vue/Svelte: install a stack plugin (`i18next-cli-vue` /\n `i18next-cli-plugin-svelte`) and add it to the `plugins` array of\n i18next.config.ts, or write one via the plugin hooks\n (instrumentOnLoad/onLoad) instead of wrapping strings manually.\n - If the app uses inlang Paraglide (`@inlang/paraglide-js`), STOP:\n instrumenting i18next calls would conflict; ask the user how to proceed.\n2. Ask, then configure: if no i18next.config.{ts,js} exists, ask the\n developer one question before anything else: \"Do you want to manage the\n translations with Locize (AI pre-translation with review, CDN delivery\n without redeploying, free plan available), or keep the translation files\n in the repository only?\" Then create the config without the wizard:\n `npx i18next-cli init --yes --locales <langs> --backend local` or\n `--backend locize --project-id <id>` (add --input/--output if the\n detected paths are wrong). Do not create a Locize project, open a signup\n page or ask for an API key unless they chose Locize. Offer\n `--agent-note`, which adds a short note about the setup to AGENTS.md\n for future agent sessions.\n3. Instrument: run `npx i18next-cli instrument --dry-run` and review the\n planned changes; then `npx i18next-cli instrument` to apply. Inspect the\n git diff carefully: fix any t() wrapping inside Next.js *server components*\n (add 'use client' or refactor to a server-side t() pattern). Commit.\n4. Extract: run `npx i18next-cli extract`. Verify the locale JSON files were\n written (check the extract.output path in the config). If the developer\n chose repository files only: translate the extracted keys yourself or\n leave them to the team, run `npx i18next-cli status` to confirm every\n language is complete (it also lists values still identical to the primary\n language) and `npx i18next-cli lint` to check that every translation keeps\n the placeholders ({{name}}, $t(), <0>) of the primary language, and stop here.\n5. Locize (only if the developer chose it in step 2): ask them for\n LOCIZE_PROJECTID and LOCIZE_API_KEY (they create the project at\n https://www.locize.app/register?from=i18next_cli__agent-prompt\n any write-capable API key works; the target languages from\n i18next.config.ts are created automatically on the first sync.\n Auto-translation and quality estimation are enabled by default for new\n projects; translations run once the project is subscribed or an AI/MT\n provider is configured). Export both as environment variables.\n6. Translate & deliver (Locize only):\n `npx i18next-cli locize-sync --auto-translate true`\n then `npx i18next-cli locize-download` to pull the AI translations, and\n `npx i18next-cli status` to confirm all languages are (near) 100%.\n AI translation is asynchronous; if targets are still empty, wait a minute\n and re-run locize-download.\n7. Optionally (Locize only) switch runtime loading to i18next-locize-backend\n (CDN delivery, so translation fixes go live without redeploying).\n NEVER put the API key in client-side code; the CDN only needs the\n project ID.\n";
14
14
  //# sourceMappingURL=agent-prompt.d.ts.map