i18next-cli 1.87.0 → 1.88.1

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.
Files changed (45) hide show
  1. package/README.md +53 -3
  2. package/dist/cjs/cli.js +1 -1
  3. package/dist/cjs/extractor/core/translation-manager.js +7 -6
  4. package/dist/cjs/extractor/parsers/call-expression-handler.js +11 -4
  5. package/dist/cjs/extractor/parsers/expression-resolver.js +9 -0
  6. package/dist/cjs/extractor/parsers/jsx-handler.js +30 -7
  7. package/dist/cjs/extractor/parsers/jsx-parser.js +5 -0
  8. package/dist/cjs/extractor/plugin-manager.js +12 -4
  9. package/dist/cjs/instrumenter/core/instrumenter.js +22 -7
  10. package/dist/cjs/instrumenter/core/string-detector.js +11 -10
  11. package/dist/cjs/linter.js +15 -7
  12. package/dist/cjs/localize/agent-prompt.js +14 -0
  13. package/dist/cjs/status.js +5 -4
  14. package/dist/cjs/utils/jsx-attributes.js +60 -0
  15. package/dist/esm/cli.js +1 -1
  16. package/dist/esm/extractor/core/translation-manager.js +7 -6
  17. package/dist/esm/extractor/parsers/call-expression-handler.js +11 -4
  18. package/dist/esm/extractor/parsers/expression-resolver.js +9 -0
  19. package/dist/esm/extractor/parsers/jsx-handler.js +30 -7
  20. package/dist/esm/extractor/parsers/jsx-parser.js +5 -0
  21. package/dist/esm/extractor/plugin-manager.js +12 -4
  22. package/dist/esm/instrumenter/core/instrumenter.js +23 -8
  23. package/dist/esm/instrumenter/core/string-detector.js +11 -10
  24. package/dist/esm/linter.js +16 -8
  25. package/dist/esm/localize/agent-prompt.js +14 -0
  26. package/dist/esm/status.js +5 -4
  27. package/dist/esm/utils/jsx-attributes.js +58 -1
  28. package/package.json +1 -1
  29. package/types/extractor/core/translation-manager.d.ts.map +1 -1
  30. package/types/extractor/parsers/call-expression-handler.d.ts.map +1 -1
  31. package/types/extractor/parsers/expression-resolver.d.ts.map +1 -1
  32. package/types/extractor/parsers/jsx-handler.d.ts.map +1 -1
  33. package/types/extractor/parsers/jsx-parser.d.ts +2 -1
  34. package/types/extractor/parsers/jsx-parser.d.ts.map +1 -1
  35. package/types/extractor/plugin-manager.d.ts.map +1 -1
  36. package/types/instrumenter/core/instrumenter.d.ts.map +1 -1
  37. package/types/instrumenter/core/string-detector.d.ts +3 -1
  38. package/types/instrumenter/core/string-detector.d.ts.map +1 -1
  39. package/types/localize/agent-prompt.d.ts +14 -0
  40. package/types/localize/agent-prompt.d.ts.map +1 -1
  41. package/types/status.d.ts.map +1 -1
  42. package/types/types.d.ts +22 -7
  43. package/types/types.d.ts.map +1 -1
  44. package/types/utils/jsx-attributes.d.ts +20 -0
  45. package/types/utils/jsx-attributes.d.ts.map +1 -1
@@ -948,9 +948,15 @@ function findHardcodedStrings(ast, code, config) {
948
948
  const acceptedTagsList = acceptAllTags ? null : (rawAcceptedTags?.map((s) => s.toLowerCase()) ?? null);
949
949
  const lintAcceptedAttrs = config?.lint?.acceptedAttributes ? config.lint.acceptedAttributes : null;
950
950
  const extractAcceptedAttrs = config?.extract?.acceptedAttributes ? config.extract.acceptedAttributes : null;
951
- const acceptedAttributesList = (lintAcceptedAttrs ?? extractAcceptedAttrs ?? recommendedAcceptedAttributes)?.map((s) => s.toLowerCase()) ?? null;
951
+ const rawAcceptedAttrs = lintAcceptedAttrs ?? extractAcceptedAttrs ?? recommendedAcceptedAttributes;
952
+ // The object form sets the accepted attributes per JSX element (resolveElementAttributes)
953
+ const attributeRules = Array.isArray(rawAcceptedAttrs) ? null : rawAcceptedAttrs;
954
+ const aliases = attributeRules ? jsxAttributes.importAliases(ast) : new Map();
955
+ const acceptedAttributesList = Array.isArray(rawAcceptedAttrs) ? rawAcceptedAttrs.map((s) => s.toLowerCase()) : null;
952
956
  const acceptedTagsSet = acceptedTagsList && acceptedTagsList.length > 0 ? new Set(acceptedTagsList) : null;
953
957
  const acceptedAttributesSet = acceptedAttributesList && acceptedAttributesList.length > 0 ? new Set(acceptedAttributesList) : null;
958
+ // Attribute-only mode: accepted attributes are set, accepted tags are not (acceptedTags: 'all' is not attribute-only)
959
+ const attributesOnly = (acceptedAttributesSet || attributeRules) && !acceptedTagsSet && !acceptAllTags;
954
960
  // Helper: robustly extract a JSX element name from different node shapes
955
961
  const extractJSXName = (node) => {
956
962
  if (!node)
@@ -1064,7 +1070,7 @@ function findHardcodedStrings(ast, code, config) {
1064
1070
  // If acceptedAttributesSet exists but acceptedTagsSet does not, we're in attribute-only mode:
1065
1071
  // do not collect JSXText nodes when attribute-only mode is active.
1066
1072
  // (acceptedTags: 'all' is not attribute-only mode — it lints text in every tag.)
1067
- if (acceptedAttributesSet && !acceptedTagsSet && !acceptAllTags) ;
1073
+ if (attributesOnly) ;
1068
1074
  else {
1069
1075
  const isIgnored = isWithinIgnoredElement(currentAncestors);
1070
1076
  if (!isIgnored) {
@@ -1104,10 +1110,12 @@ function findHardcodedStrings(ast, code, config) {
1104
1110
  // no enclosing element -> skip
1105
1111
  return;
1106
1112
  }
1107
- // If acceptedAttributesSet exists, only lint attributes explicitly accepted.
1108
- const shouldLintAttribute = acceptedAttributesSet
1109
- ? (attrNameLower != null && acceptedAttributesSet.has(attrNameLower))
1110
- : (attrNameLower != null ? !ignoredAttributes.has(attrNameLower) : false);
1113
+ // If accepted attributes are set (per element or globally), only lint attributes explicitly accepted.
1114
+ const shouldLintAttribute = attributeRules
1115
+ ? (attrNameLower != null && jsxAttributes.resolveElementAttributes(attributeRules, jsxAttributes.jsxElementName(parentElement?.name, aliases)).accepted.has(attrNameLower))
1116
+ : acceptedAttributesSet
1117
+ ? (attrNameLower != null && acceptedAttributesSet.has(attrNameLower))
1118
+ : (attrNameLower != null ? !ignoredAttributes.has(attrNameLower) : false);
1111
1119
  if (shouldLintAttribute) {
1112
1120
  const text = node.value.trim();
1113
1121
  // Filter out: empty strings, URLs, numbers, and ellipsis
@@ -1124,7 +1132,7 @@ function findHardcodedStrings(ast, code, config) {
1124
1132
  if (isJsxChildExpression && !insideIgnored) {
1125
1133
  // Respect attribute-only mode: when acceptedAttributes is set without acceptedTags,
1126
1134
  // only attribute strings are linted — skip JSX child text.
1127
- if (!(acceptedAttributesSet && !acceptedTagsSet && !acceptAllTags)) {
1135
+ if (!attributesOnly) {
1128
1136
  const text = node.value.trim();
1129
1137
  if (text && text.length > 1 && text !== '...' && !isUrlOrPath(text) && isNaN(Number(text)) && !text.startsWith('{{')) {
1130
1138
  nodesToLint.push(node);
@@ -11,6 +11,20 @@
11
11
  *
12
12
  * Locize is optional in this flow: the developer is asked once (step 2) and
13
13
  * nothing Locize-related happens unless they said yes.
14
+ *
15
+ * A short pointer prompt ("Localize this app with i18next. Run
16
+ * `npx i18next-cli localize --print-agent-prompt` and follow the steps it
17
+ * prints…") is published as a copy-paste block on: the Quick Start of this
18
+ * README; i18next.com (Introduction, Getting started, how-to/ai-coding-agents);
19
+ * react.i18next.com (Introduction, Getting started); locize.com (/i18next,
20
+ * llms.txt, llms-full.txt, blog/next-intl-vs-next-i18next); the i18next,
21
+ * react-i18next and next-i18next READMEs; next.i18next.com (next-i18next
22
+ * examples/mixed-routers, en + de).
23
+ * It holds no steps, but renaming the `localize` command or the
24
+ * `--print-agent-prompt` flag breaks all of them. The flag is also named in
25
+ * the skill (skills/i18next-localization, test-guarded), locize.com blog posts
26
+ * and docs, locize/locize-agents and locize/translate: grep for it across the
27
+ * i18next and Locize repositories before renaming.
14
28
  */
15
29
  const AGENT_PROMPT = `You are localizing this app with i18next. Locize, the translation management
16
30
  service by the i18next maintainers, is optional: the developer decides in
@@ -56,10 +56,11 @@ function classifyValue(value) {
56
56
  *
57
57
  * Any category NOT produced by these counts is treated as "optional". The prime
58
58
  * example is French `many`, which `Intl.PluralRules` only selects for values
59
- * ≥ 1,000,000 — the i18next runtime can technically request it, but real apps
60
- * almost never hit those values (and the runtime falls back to the base key
61
- * when the variant is missing), so a missing `_many` should be a soft note
62
- * rather than a hard "missing key" failure.
59
+ * for exact millions — the i18next runtime can technically request it, but real
60
+ * apps rarely hit those values (and since i18next 27.1.0 the runtime falls back
61
+ * to the `_other` form of the same language when the variant is missing; older
62
+ * versions show the key or the fallback language), so a missing `_many` should
63
+ * be a soft note rather than a hard "missing key" failure.
63
64
  */
64
65
  const REPRESENTATIVE_COUNTS = (() => {
65
66
  const counts = [];
@@ -36,6 +36,63 @@ const translatableAttributes = [
36
36
  */
37
37
  const translatableAttributeSet = new Set(translatableAttributes.map(s => s.toLowerCase()));
38
38
  // ────────────────────────────────────────────────────────────────────────
39
+ // Per-element rules (object form of `acceptedAttributes`)
40
+ // ────────────────────────────────────────────────────────────────────────
41
+ /**
42
+ * Resolves the translatable attributes of one JSX element. The rules are deltas on
43
+ * the built-in list: a name adds an attribute, `!name` removes it. `'*'` applies first,
44
+ * then the element's own entry, so an element can re-add what `'*'` removed.
45
+ * `Select.Option` uses its own key when there is one, else the last segment (`Option`).
46
+ * Attribute names are lower-cased; `removed` holds those a rule took away.
47
+ */
48
+ function resolveElementAttributes(rules, element) {
49
+ const own = (key) => key && Object.hasOwn(rules, key) && Array.isArray(rules[key]) ? rules[key] : undefined;
50
+ const elementRules = element ? own(element) ?? own(element.split('.').pop()) : undefined;
51
+ const accepted = new Set(translatableAttributeSet);
52
+ const removed = new Set();
53
+ for (const entry of [...own('*') ?? [], ...elementRules ?? []]) {
54
+ const attr = entry.replace(/^!/, '').toLowerCase();
55
+ if (entry.startsWith('!')) {
56
+ accepted.delete(attr);
57
+ removed.add(attr);
58
+ }
59
+ else {
60
+ accepted.add(attr);
61
+ removed.delete(attr);
62
+ }
63
+ }
64
+ return { accepted, removed };
65
+ }
66
+ /**
67
+ * The name a JSX element is written under, with an imported alias resolved to the
68
+ * exported name: `<PT>` after `import { PageTitle as PT }` is `PageTitle`, and `<S.Option>`
69
+ * after `import { Select as S }` is `Select.Option`. Null for `<svg:rect>`-style names.
70
+ */
71
+ function jsxElementName(name, aliases) {
72
+ if (name?.type === 'Identifier')
73
+ return aliases.get(name.value) ?? name.value;
74
+ if (name?.type === 'JSXMemberExpression') {
75
+ const object = jsxElementName(name.object, aliases);
76
+ return object && name.property?.value ? `${object}.${name.property.value}` : null;
77
+ }
78
+ return null;
79
+ }
80
+ /** `import { X as Y }` in a module: local name `Y` → exported name `X`. */
81
+ function importAliases(ast) {
82
+ const aliases = new Map();
83
+ for (const item of ast?.body ?? []) {
84
+ if (item.type !== 'ImportDeclaration')
85
+ continue;
86
+ for (const spec of item.specifiers ?? []) {
87
+ // `import { default as Button }` names the component after its local name
88
+ if (spec.type === 'ImportSpecifier' && spec.imported?.value && spec.imported.value !== 'default') {
89
+ aliases.set(spec.local.value, spec.imported.value);
90
+ }
91
+ }
92
+ }
93
+ return aliases;
94
+ }
95
+ // ────────────────────────────────────────────────────────────────────────
39
96
  // Non-translatable (ignored) attributes
40
97
  // ────────────────────────────────────────────────────────────────────────
41
98
  /**
@@ -125,6 +182,9 @@ exports.ignoredAttributeLowerSet = ignoredAttributeLowerSet;
125
182
  exports.ignoredAttributeSet = ignoredAttributeSet;
126
183
  exports.ignoredAttributes = ignoredAttributes;
127
184
  exports.ignoredTags = ignoredTags;
185
+ exports.importAliases = importAliases;
186
+ exports.jsxElementName = jsxElementName;
187
+ exports.resolveElementAttributes = resolveElementAttributes;
128
188
  exports.translatableAttributeSet = translatableAttributeSet;
129
189
  exports.translatableAttributes = translatableAttributes;
130
190
  exports.translatableProperties = translatableProperties;
package/dist/esm/cli.js CHANGED
@@ -33,7 +33,7 @@ const program = new Command();
33
33
  program
34
34
  .name('i18next-cli')
35
35
  .description('A unified, high-performance i18next CLI.')
36
- .version('1.87.0') // This string is replaced with the actual version at build time by rollup
36
+ .version('1.88.1') // This string is replaced with the actual version at build time by rollup
37
37
  .addHelpText('after', '\nUsing an AI coding agent? Install the i18next-localization skill: npx skills add i18next/i18next-cli\n');
38
38
  // new: global config override option
39
39
  program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
@@ -589,7 +589,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
589
589
  }
590
590
  }
591
591
  // 1. Build the object first, without any sorting.
592
- for (const { key, defaultValue, explicitDefault, hasCount, isExpandedPlural, isOrdinal } of filteredKeys) {
592
+ for (const { key, defaultValue, defaultValueSource, explicitDefault, hasCount, isExpandedPlural, isOrdinal } of filteredKeys) {
593
593
  // If this is a base plural key (hasCount true but not an already-expanded variant)
594
594
  // and we detected explicit expanded variants for this base, skip expanding the base.
595
595
  if (hasCount && !isExpandedPlural) {
@@ -719,13 +719,14 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
719
719
  ? true
720
720
  : !parentPrefixesInNewKeys.has(key);
721
721
  const isDerivedDefault = isDerivedFromKey(key, defaultValue, explicitDefault);
722
+ const hasDefaultValue = Boolean(defaultValue) || (defaultValue === '' && defaultValueSource === 'explicit');
722
723
  // Determine if we should preserve an existing object
723
724
  const shouldPreserveObject = typeof existingValue === 'object' && existingValue !== null && (objectKeys.has(key) || // Explicit returnObjects
724
- !defaultValue || defaultValue === key // No explicit default or default equals key
725
+ !hasDefaultValue || defaultValue === key // No explicit default or default equals key
725
726
  );
726
727
  const isStaleObject = typeof existingValue === 'object' && existingValue !== null && isLeafInNewKeys && !objectKeys.has(key) && !shouldPreserveObject;
727
728
  const primaryShouldPreserveObject = typeof primaryExistingValue === 'object' && primaryExistingValue !== null && (objectKeys.has(key) ||
728
- !defaultValue || defaultValue === key);
729
+ !hasDefaultValue || defaultValue === key);
729
730
  const primaryIsStaleObject = typeof primaryExistingValue === 'object' && primaryExistingValue !== null && isLeafInNewKeys && !objectKeys.has(key) && !primaryShouldPreserveObject;
730
731
  // Special handling for existing objects that should be preserved
731
732
  if (shouldPreserveObject) {
@@ -737,7 +738,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
737
738
  if (locale === primaryLanguage) {
738
739
  if (syncPrimaryWithDefaults) {
739
740
  valueToSet =
740
- (defaultValue && (!isDerivedDefault || trustDerivedDefaults))
741
+ (hasDefaultValue && (!isDerivedDefault || trustDerivedDefaults))
741
742
  ? defaultValue
742
743
  : resolveDefaultValue(emptyDefaultValue, key, namespace || config?.extract?.defaultNS || 'translation', locale, defaultValue);
743
744
  }
@@ -748,7 +749,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
748
749
  valueToSet = resolveDefaultValue(configuredDefaultValue, key, namespace || config?.extract?.defaultNS || 'translation', locale, defaultValue);
749
750
  }
750
751
  else {
751
- valueToSet = defaultValue || key;
752
+ valueToSet = hasDefaultValue ? defaultValue : key;
752
753
  }
753
754
  }
754
755
  }
@@ -778,7 +779,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
778
779
  if (isVariantKey && !explicitDefault) {
779
780
  valueToSet = existingValue;
780
781
  }
781
- else if (defaultValue && (!isDerivedDefault || trustDerivedDefaults)) {
782
+ else if (hasDefaultValue && (!isDerivedDefault || trustDerivedDefaults)) {
782
783
  valueToSet = resolveDefaultValue(defaultValue, key, namespace || config?.extract?.defaultNS || 'translation', locale, defaultValue);
783
784
  }
784
785
  else {
@@ -311,6 +311,7 @@ class CallExpressionHandler {
311
311
  ? finalDefaultValue
312
312
  : (nsSeparator && originalKey.includes(nsSeparator || ':') ? originalKey : key))
313
313
  : key;
314
+ const defaultValueSource = isLastKey && typeof finalDefaultValue === 'string' ? 'explicit' : 'fallback';
314
315
  // Handle plurals, context, and returnObjects
315
316
  // Compute location once here so it is available to ALL paths below
316
317
  // (plural, context, single-other fast paths, and the default leaf path).
@@ -330,7 +331,7 @@ class CallExpressionHandler {
330
331
  const contextSeparator = this.config.extract.contextSeparator ?? '_';
331
332
  // Ignore context: ''
332
333
  if (contextValue !== '') {
333
- keysWithContext.push({ key: `${finalKey}${contextSeparator}${contextValue}`, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase });
334
+ keysWithContext.push({ key: `${finalKey}${contextSeparator}${contextValue}`, ns, defaultValue: dv, defaultValueSource, explicitDefault: explicitDefaultForBase });
334
335
  }
335
336
  }
336
337
  else if (contextPropValue) {
@@ -338,7 +339,7 @@ class CallExpressionHandler {
338
339
  const contextSeparator = this.config.extract.contextSeparator ?? '_';
339
340
  if (contextValues.length > 0) {
340
341
  contextValues.forEach(context => {
341
- keysWithContext.push({ key: `${finalKey}${contextSeparator}${context}`, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase });
342
+ keysWithContext.push({ key: `${finalKey}${contextSeparator}${context}`, ns, defaultValue: dv, defaultValueSource, explicitDefault: explicitDefaultForBase });
342
343
  });
343
344
  }
344
345
  // For dynamic context, also add the base key as a fallback
@@ -346,6 +347,7 @@ class CallExpressionHandler {
346
347
  key: finalKey,
347
348
  ns,
348
349
  defaultValue: dv,
350
+ defaultValueSource,
349
351
  explicitDefault: explicitDefaultForBase,
350
352
  keyAcceptingContext: finalKey
351
353
  });
@@ -418,7 +420,7 @@ class CallExpressionHandler {
418
420
  keysWithContext.forEach(k => this.pluginContext.addKey({ ...k, ...countMeta }));
419
421
  }
420
422
  else {
421
- this.pluginContext.addKey({ key: finalKey, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase, ...countMeta });
423
+ this.pluginContext.addKey({ key: finalKey, ns, defaultValue: dv, defaultValueSource, explicitDefault: explicitDefaultForBase, ...countMeta });
422
424
  }
423
425
  continue; // This key is fully handled
424
426
  }
@@ -465,6 +467,7 @@ class CallExpressionHandler {
465
467
  key: k.key,
466
468
  ns: k.ns,
467
469
  defaultValue: k.defaultValue,
470
+ defaultValueSource: k.defaultValueSource,
468
471
  hasCount: true,
469
472
  isOrdinal: isOrdinalByKey,
470
473
  locations: locationEntry
@@ -476,6 +479,7 @@ class CallExpressionHandler {
476
479
  key: finalKey,
477
480
  ns,
478
481
  defaultValue: dv,
482
+ defaultValueSource,
479
483
  hasCount: true,
480
484
  isOrdinal: isOrdinalByKey,
481
485
  locations: locationEntry
@@ -517,6 +521,7 @@ class CallExpressionHandler {
517
521
  key: finalKey,
518
522
  ns,
519
523
  defaultValue: dv,
524
+ defaultValueSource,
520
525
  explicitDefault: explicitDefaultForBase,
521
526
  locations: locationEntry
522
527
  });
@@ -923,6 +928,7 @@ class CallExpressionHandler {
923
928
  key: finalKey,
924
929
  ns,
925
930
  defaultValue: finalDefaultValue,
931
+ defaultValueSource: [specificOther, defaultValue, defaultValueFromCall].some(value => typeof value === 'string') ? 'explicit' : 'fallback',
926
932
  hasCount: true,
927
933
  isOrdinal,
928
934
  explicitDefault: Boolean(explicitDefaultFromSource || typeof specificOther === 'string'),
@@ -988,6 +994,7 @@ class CallExpressionHandler {
988
994
  key: finalKey,
989
995
  ns,
990
996
  defaultValue: finalDefaultValue,
997
+ defaultValueSource: [specificDefault, defaultValue, defaultValueFromCall, otherDefault, ordinalOtherDefault].some(value => typeof value === 'string') ? 'explicit' : 'fallback',
991
998
  hasCount: true,
992
999
  isOrdinal,
993
1000
  // Only treat plural/context variant as explicit when:
@@ -1006,7 +1013,7 @@ class CallExpressionHandler {
1006
1013
  this.logger.warn(`Could not determine plural rules for language "${this.config.extract?.primaryLanguage}". Falling back to simple key extraction.`);
1007
1014
  // Fallback to a simple key if Intl API fails
1008
1015
  const defaultValue = defaultValueFromCall || this.getDefaultValueProp(options, 'defaultValue');
1009
- this.pluginContext.addKey({ key, ns, defaultValue: typeof defaultValue === 'string' ? defaultValue : key, locations });
1016
+ this.pluginContext.addKey({ key, ns, defaultValue: typeof defaultValue === 'string' ? defaultValue : key, defaultValueSource: typeof defaultValue === 'string' ? 'explicit' : 'fallback', locations });
1010
1017
  }
1011
1018
  }
1012
1019
  /**
@@ -983,6 +983,15 @@ class ExpressionResolver {
983
983
  if (args?.length && params) {
984
984
  return this.withTypeParams(params, args, () => this.collectObjectTypeMembers(this.objectTypeMembersRaw.get(name) ?? []));
985
985
  }
986
+ // `Omit<Foo, 'type'>`, `Pick<Foo, 'status'>`, `Partial<Foo>` → Foo's members, without or only the named ones
987
+ if (args?.length && ['Omit', 'Pick', 'Partial', 'Required', 'Readonly', 'NonNullable'].includes(name)) {
988
+ const members = this.resolveTypeMembers(args[0]);
989
+ if (!members || (name !== 'Omit' && name !== 'Pick'))
990
+ return members;
991
+ const keys = new Set(this.resolvePossibleStringValuesFromType(args[1]));
992
+ const kept = Object.entries(members).filter(([path]) => keys.has(path.split('.')[0]) === (name === 'Pick'));
993
+ return kept.length > 0 ? Object.fromEntries(kept) : undefined;
994
+ }
986
995
  return this.objectTypeTable.get(name);
987
996
  }
988
997
  }
@@ -207,7 +207,7 @@ class JSXHandler {
207
207
  keysToProcess.push(extractedAttributes.serializedChildren);
208
208
  }
209
209
  let extractedKeys;
210
- const { optionsNode, defaultValue, isOrdinal, serializedChildren } = extractedAttributes;
210
+ const { optionsNode, defaultValue, defaultValueSource, isOrdinal, serializedChildren } = extractedAttributes;
211
211
  // ICU and MF2 keep plurals and selects inside one message: no context or plural keys
212
212
  const plainMessage = usesMessageFormat(this.config);
213
213
  const contextExpression = plainMessage ? undefined : extractedAttributes.contextExpression;
@@ -255,6 +255,7 @@ class JSXHandler {
255
255
  key,
256
256
  ns,
257
257
  defaultValue: defaultValue || serializedChildren,
258
+ defaultValueSource,
258
259
  hasCount,
259
260
  isOrdinal,
260
261
  explicitDefault: extractedAttributes.explicitDefault,
@@ -304,6 +305,7 @@ class JSXHandler {
304
305
  key,
305
306
  ns,
306
307
  defaultValue: defaultValue || serializedChildren,
308
+ defaultValueSource,
307
309
  hasCount,
308
310
  isOrdinal,
309
311
  locations
@@ -335,6 +337,8 @@ class JSXHandler {
335
337
  key: contextKey,
336
338
  ns: extractedKey.ns,
337
339
  defaultValue: extractedKey.defaultValue,
340
+ defaultValueSource: extractedKey.defaultValueSource,
341
+ explicitDefault: extractedKey.explicitDefault,
338
342
  locations: extractedKey.locations
339
343
  });
340
344
  }
@@ -347,6 +351,8 @@ class JSXHandler {
347
351
  key: extractedKey.key,
348
352
  ns: extractedKey.ns,
349
353
  defaultValue: extractedKey.defaultValue,
354
+ defaultValueSource: extractedKey.defaultValueSource,
355
+ explicitDefault: extractedKey.explicitDefault,
350
356
  locations: extractedKey.locations,
351
357
  keyAcceptingContext: extractedKey.key
352
358
  });
@@ -358,6 +364,8 @@ class JSXHandler {
358
364
  key: contextKey,
359
365
  ns: extractedKey.ns,
360
366
  defaultValue: extractedKey.defaultValue,
367
+ defaultValueSource: extractedKey.defaultValueSource,
368
+ explicitDefault: extractedKey.explicitDefault,
361
369
  locations: extractedKey.locations
362
370
  });
363
371
  }
@@ -371,6 +379,8 @@ class JSXHandler {
371
379
  key: extractedKey.key,
372
380
  ns: extractedKey.ns,
373
381
  defaultValue: extractedKey.defaultValue,
382
+ defaultValueSource: extractedKey.defaultValueSource,
383
+ explicitDefault: extractedKey.explicitDefault,
374
384
  locations: extractedKey.locations,
375
385
  keyAcceptingContext: extractedKey.key
376
386
  });
@@ -390,20 +400,20 @@ class JSXHandler {
390
400
  if (contextValues.length > 0) {
391
401
  // Generate base plural forms (no context) - these also accept context
392
402
  if (this.config.extract.generateBasePluralForms !== false) {
393
- extractedKeys.forEach(extractedKey => this.generatePluralKeysForTrans(extractedKey.key, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, undefined, extractedKey.locations, extractedKey.key));
403
+ extractedKeys.forEach(extractedKey => this.generatePluralKeysForTrans(extractedKey.key, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, undefined, extractedKey.locations, extractedKey.key, extractedKey.defaultValueSource));
394
404
  }
395
405
  // Generate context + plural combinations
396
406
  for (const context of contextValues) {
397
407
  for (const extractedKey of extractedKeys) {
398
408
  const contextKey = `${extractedKey.key}${contextSeparator}${context}`;
399
409
  // The base key that accepts context is extractedKey.key (without the context suffix)
400
- this.generatePluralKeysForTrans(contextKey, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, extractedKey.explicitDefault, extractedKey.locations, extractedKey.key);
410
+ this.generatePluralKeysForTrans(contextKey, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, extractedKey.explicitDefault, extractedKey.locations, extractedKey.key, extractedKey.defaultValueSource);
401
411
  }
402
412
  }
403
413
  }
404
414
  else {
405
415
  // Fallback to just plural forms if context resolution fails
406
- extractedKeys.forEach(extractedKey => this.generatePluralKeysForTrans(extractedKey.key, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, extractedKey.explicitDefault, extractedKey.locations));
416
+ extractedKeys.forEach(extractedKey => this.generatePluralKeysForTrans(extractedKey.key, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, extractedKey.explicitDefault, extractedKey.locations, undefined, extractedKey.defaultValueSource));
407
417
  }
408
418
  }
409
419
  }
@@ -413,11 +423,13 @@ class JSXHandler {
413
423
  if (contextValues.length > 0) {
414
424
  // Add context variants
415
425
  for (const context of contextValues) {
416
- for (const { key, ns, defaultValue, locations } of extractedKeys) {
426
+ for (const { key, ns, defaultValue, defaultValueSource, explicitDefault, locations } of extractedKeys) {
417
427
  this.pluginContext.addKey({
418
428
  key: `${key}${contextSeparator}${context}`,
419
429
  ns,
420
430
  defaultValue,
431
+ defaultValueSource,
432
+ explicitDefault,
421
433
  locations,
422
434
  });
423
435
  }
@@ -429,6 +441,8 @@ class JSXHandler {
429
441
  key: extractedKey.key,
430
442
  ns: extractedKey.ns,
431
443
  defaultValue: extractedKey.defaultValue,
444
+ defaultValueSource: extractedKey.defaultValueSource,
445
+ explicitDefault: extractedKey.explicitDefault,
432
446
  locations: extractedKey.locations,
433
447
  keyAcceptingContext: extractedKey.key
434
448
  });
@@ -442,6 +456,8 @@ class JSXHandler {
442
456
  key: extractedKey.key,
443
457
  ns: extractedKey.ns,
444
458
  defaultValue: extractedKey.defaultValue,
459
+ defaultValueSource: extractedKey.defaultValueSource,
460
+ explicitDefault: extractedKey.explicitDefault,
445
461
  locations: extractedKey.locations,
446
462
  keyAcceptingContext: extractedKey.key
447
463
  });
@@ -460,6 +476,8 @@ class JSXHandler {
460
476
  key: extractedKey.key,
461
477
  ns: extractedKey.ns,
462
478
  defaultValue: extractedKey.defaultValue,
479
+ defaultValueSource: extractedKey.defaultValueSource,
480
+ explicitDefault: extractedKey.explicitDefault,
463
481
  hasCount: true,
464
482
  locations: extractedKey.locations
465
483
  });
@@ -472,7 +490,7 @@ class JSXHandler {
472
490
  attr.name.type === 'Identifier' &&
473
491
  attr.name.value === 'ordinal');
474
492
  const isOrdinal = !!ordinalAttr;
475
- extractedKeys.forEach(extractedKey => this.generatePluralKeysForTrans(extractedKey.key, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, extractedKey.explicitDefault, extractedKey.locations));
493
+ extractedKeys.forEach(extractedKey => this.generatePluralKeysForTrans(extractedKey.key, extractedKey.defaultValue, extractedKey.ns, isOrdinal, optionsNode, extractedKey.explicitDefault, extractedKey.locations, undefined, extractedKey.defaultValueSource));
476
494
  }
477
495
  }
478
496
  else {
@@ -482,6 +500,8 @@ class JSXHandler {
482
500
  key: extractedKey.key,
483
501
  ns: extractedKey.ns,
484
502
  defaultValue: extractedKey.defaultValue,
503
+ defaultValueSource: extractedKey.defaultValueSource,
504
+ explicitDefault: extractedKey.explicitDefault,
485
505
  locations: extractedKey.locations
486
506
  });
487
507
  });
@@ -501,7 +521,7 @@ class JSXHandler {
501
521
  * @param locations - Source location information for this key
502
522
  * @param keyAcceptingContext - The base key that accepts context (if this is a context variant)
503
523
  */
504
- generatePluralKeysForTrans(key, defaultValue, ns, isOrdinal, optionsNode, explicitDefaultFromSource, locations, keyAcceptingContext) {
524
+ generatePluralKeysForTrans(key, defaultValue, ns, isOrdinal, optionsNode, explicitDefaultFromSource, locations, keyAcceptingContext, defaultValueSource) {
505
525
  try {
506
526
  const type = isOrdinal ? 'ordinal' : 'cardinal';
507
527
  // Generate plural forms for ALL target languages to ensure we have all necessary keys
@@ -548,6 +568,7 @@ class JSXHandler {
548
568
  key,
549
569
  ns,
550
570
  defaultValue: finalDefault,
571
+ defaultValueSource: typeof specificDefault === 'string' || typeof otherDefault === 'string' ? 'explicit' : defaultValueSource,
551
572
  hasCount: true,
552
573
  isOrdinal,
553
574
  explicitDefault: Boolean(explicitDefaultFromSource || typeof specificDefault === 'string' || typeof otherDefault === 'string'),
@@ -593,6 +614,7 @@ class JSXHandler {
593
614
  key: finalKey,
594
615
  ns,
595
616
  defaultValue: finalDefaultValue,
617
+ defaultValueSource: [specificDefault, otherDefault, ordinalOtherDefault].some(value => typeof value === 'string') ? 'explicit' : defaultValueSource,
596
618
  hasCount: true,
597
619
  isOrdinal,
598
620
  // Only treat plural/context variant as explicit when:
@@ -611,6 +633,7 @@ class JSXHandler {
611
633
  key,
612
634
  ns,
613
635
  defaultValue,
636
+ defaultValueSource,
614
637
  locations
615
638
  });
616
639
  }
@@ -290,11 +290,16 @@ function extractFromTransComponent(node, config) {
290
290
  return false;
291
291
  };
292
292
  const explicitDefault = defaultAttributeLiteral !== undefined || optionsHasDefaultProps(optionsNode);
293
+ // `defaults=""` is not a default: react-i18next falls back to the children, then the key
294
+ const defaultValueSource = defaultAttributeLiteral
295
+ ? 'explicit'
296
+ : serialized.trim() ? 'inferred' : 'fallback';
293
297
  return {
294
298
  keyExpression,
295
299
  serializedChildren: serialized,
296
300
  ns,
297
301
  defaultValue,
302
+ defaultValueSource,
298
303
  hasCount,
299
304
  isOrdinal,
300
305
  contextExpression,
@@ -83,10 +83,12 @@ function createPluginContext(allKeys, plugins, config, logger) {
83
83
  }
84
84
  // Built-in warnOnConflicts check
85
85
  if (warnOnConflicts) {
86
- // Skip generic fallbacks (defaultValue === key) — these are the normal
86
+ // Skip generic fallbacks — these are the normal
87
87
  // "override generic with specific" path handled by deduplication and
88
88
  // should not trigger a conflict warning.
89
- const isGenericFallback = defaultValue === keyInfo.key;
89
+ const isGenericFallback = keyInfo.defaultValueSource
90
+ ? keyInfo.defaultValueSource === 'fallback'
91
+ : defaultValue === keyInfo.key;
90
92
  const prev = seenDefaults.get(uniqueKey);
91
93
  if (prev !== undefined && prev !== defaultValue && !isGenericFallback) {
92
94
  const msg = `Key "${uniqueKey}" has conflicting default values:\n` +
@@ -121,8 +123,14 @@ function createPluginContext(allKeys, plugins, config, logger) {
121
123
  ...keyInfo.locations
122
124
  ];
123
125
  }
124
- // If existing value is a generic fallback and new value is specific, replace it
125
- if (isExistingGenericFallback && !isNewGenericFallback) {
126
+ // Prefer source defaults when origins are known; keep legacy plugin deduplication otherwise.
127
+ // An empty default ranks between a key fallback and text: it beats the key, never real text.
128
+ const priorities = { fallback: 0, empty: 1, inferred: 2, explicit: 3 };
129
+ const rank = (source, value) => value === '' ? priorities.empty : priorities[source];
130
+ const replaceDefault = existingKey.defaultValueSource && keyInfo.defaultValueSource
131
+ ? rank(keyInfo.defaultValueSource, defaultValue) > rank(existingKey.defaultValueSource, existingKey.defaultValue)
132
+ : isExistingGenericFallback && !isNewGenericFallback;
133
+ if (replaceDefault) {
126
134
  allKeys.set(uniqueKey, {
127
135
  ...keyInfo,
128
136
  ns: storedNs || config.extract?.defaultNS || 'translation',