i18next-cli 1.75.2 → 1.76.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.
Files changed (53) hide show
  1. package/README.md +43 -1
  2. package/dist/cjs/cli.js +5 -3
  3. package/dist/cjs/extractor/core/ast-visitors.js +1 -0
  4. package/dist/cjs/extractor/core/extractor.js +4 -0
  5. package/dist/cjs/extractor/core/translation-manager.js +4 -0
  6. package/dist/cjs/extractor/parsers/call-expression-handler.js +12 -9
  7. package/dist/cjs/extractor/parsers/comment-parser.js +6 -1
  8. package/dist/cjs/extractor/parsers/expression-resolver.js +26 -5
  9. package/dist/cjs/extractor/parsers/jsx-handler.js +60 -4
  10. package/dist/cjs/extractor/parsers/jsx-parser.js +161 -1
  11. package/dist/cjs/index.js +7 -1
  12. package/dist/cjs/instrumenter/core/instrumenter.js +38 -0
  13. package/dist/cjs/linter.js +35 -6
  14. package/dist/cjs/localize/localize.js +4 -2
  15. package/dist/cjs/status.js +5 -0
  16. package/dist/cjs/types-generator.js +7 -1
  17. package/dist/cjs/utils/message-format.js +284 -0
  18. package/dist/esm/cli.js +5 -3
  19. package/dist/esm/extractor/core/ast-visitors.js +1 -0
  20. package/dist/esm/extractor/core/extractor.js +4 -0
  21. package/dist/esm/extractor/core/translation-manager.js +4 -0
  22. package/dist/esm/extractor/parsers/call-expression-handler.js +12 -9
  23. package/dist/esm/extractor/parsers/comment-parser.js +6 -1
  24. package/dist/esm/extractor/parsers/expression-resolver.js +26 -5
  25. package/dist/esm/extractor/parsers/jsx-handler.js +61 -5
  26. package/dist/esm/extractor/parsers/jsx-parser.js +160 -2
  27. package/dist/esm/index.js +7 -1
  28. package/dist/esm/instrumenter/core/instrumenter.js +38 -0
  29. package/dist/esm/linter.js +35 -6
  30. package/dist/esm/localize/localize.js +4 -2
  31. package/dist/esm/status.js +5 -0
  32. package/dist/esm/types-generator.js +7 -1
  33. package/dist/esm/utils/message-format.js +278 -0
  34. package/package.json +3 -1
  35. package/types/extractor/core/ast-visitors.d.ts.map +1 -1
  36. package/types/extractor/core/extractor.d.ts.map +1 -1
  37. package/types/extractor/core/translation-manager.d.ts.map +1 -1
  38. package/types/extractor/parsers/call-expression-handler.d.ts.map +1 -1
  39. package/types/extractor/parsers/comment-parser.d.ts.map +1 -1
  40. package/types/extractor/parsers/expression-resolver.d.ts +5 -1
  41. package/types/extractor/parsers/expression-resolver.d.ts.map +1 -1
  42. package/types/extractor/parsers/jsx-handler.d.ts +13 -1
  43. package/types/extractor/parsers/jsx-handler.d.ts.map +1 -1
  44. package/types/extractor/parsers/jsx-parser.d.ts +16 -0
  45. package/types/extractor/parsers/jsx-parser.d.ts.map +1 -1
  46. package/types/instrumenter/core/instrumenter.d.ts.map +1 -1
  47. package/types/linter.d.ts.map +1 -1
  48. package/types/status.d.ts.map +1 -1
  49. package/types/types-generator.d.ts.map +1 -1
  50. package/types/types.d.ts +16 -3
  51. package/types/types.d.ts.map +1 -1
  52. package/types/utils/message-format.d.ts +55 -0
  53. package/types/utils/message-format.d.ts.map +1 -0
package/README.md CHANGED
@@ -340,6 +340,8 @@ Generates TypeScript definitions from your translation files for full type-safet
340
340
 
341
341
  > **Note:** When `extract.defaultNS` is set to `false`, the generated `defaultNS` is derived from your resource files (i18next's type system cannot express `defaultNS: false`). Adjust the generated `i18next.d.ts` if your runtime i18next config uses a different default namespace.
342
342
 
343
+ > **Note:** With `extract.messageFormat: 'icu'` or `'mf2'` the generated `i18next.d.ts` sets `parseInterpolation: false` (needs `i18next` >= 26.2.0), so ICU plurals like `one {{count} row}` are not typed as `{{…}}` interpolation. The file is only written when it does not exist yet; for an existing one `types` prints a warning until you add the line.
344
+
343
345
  ```bash
344
346
  npx i18next-cli types [options]
345
347
  ```
@@ -370,7 +372,13 @@ npx i18next-cli lint
370
372
  **What it checks:**
371
373
 
372
374
  - **Hardcoded strings** *(error)* — user-facing text in JSX elements and attributes that isn't wrapped in `t()`/`<Trans>`.
373
- - **Interpolation parameters** *(error)* — mismatches between `{{placeholders}}` in a translation and the params passed to `t()` (missing or unused). Toggle with `lint.checkInterpolationParams` (default: `true`).
375
+ - **Interpolation parameters** *(error)* — mismatches between `{{placeholders}}` in a translation and the params passed to `t()` (missing or unused). Toggle with `lint.checkInterpolationParams` (default: `true`). With `extract.messageFormat: 'icu'` or `'mf2'` the arguments come from the ICU or MF2 parser (`{name}`, `{$name}`), so plurals like `one {{count} row}` are not read as `{{…}}` interpolation.
376
+ - **ICU / MF2 messages** *(error, only with `extract.messageFormat: 'icu'` or `'mf2'`)*: every value in the translation files of all locales is parsed. The linter reports, with file, key and line (JSON files):
377
+ - syntax errors with the parser's message, e.g. `greeting: ICU syntax error: EXPECT_ARGUMENT_CLOSING_BRACE at column 7`
378
+ - argument names that differ from the primary language (a renamed or missing `{name}`). `#` in a plural is not an argument
379
+ - plural categories of `plural` and `selectordinal` (MF2: `.match` on `:number` or `:integer`) that do not fit the locale. Allowed are the locale's CLDR categories, required are `other` plus every category a whole number from 0 to 1000 selects. So `ru` needs `one`, `few` and `many`, while `fr`, `es`, `it` and `pt` may leave out `many` (only from 1,000,000) and `cs` its `many` (fractions only), and `zero` in English is reported as unused. Exact selectors like `=0` are always allowed, and they count for a category when they cover every whole number it is used for: `=1` covers `one` in English, but not in Russian, where `one` is also 21, 31 and so on. For a locale `Intl` does not know only `other` is required.
380
+
381
+ Empty values count as untranslated and are skipped. See [ICU and MF2 messages](#icu-and-mf2-messages).
374
382
  - **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.
375
383
 
376
384
  ```jsx
@@ -650,6 +658,7 @@ npx skills add i18next/i18next-cli
650
658
  ```
651
659
 
652
660
  [![skills.sh installs](https://www.skills.sh/b/i18next/i18next-cli)](https://www.skills.sh/i18next/i18next-cli)
661
+ [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
653
662
 
654
663
  Then just ask it to *"add i18n to this project"*. See [`skills/i18next-localization`](./skills/i18next-localization/SKILL.md) — it ships in this repo, so it stays version-matched to the commands it drives.
655
664
 
@@ -1045,6 +1054,12 @@ export default defineConfig({
1045
1054
  // Example: '}}'
1046
1055
  interpolationSuffix: '}}', // Default: '}}'
1047
1056
 
1057
+ // The syntax of your translation values: 'i18next' (default), 'icu' (i18next-icu) or 'mf2' (i18next-mf2).
1058
+ // With 'icu' or 'mf2', `extract` writes one key per message (no plural or context suffix keys),
1059
+ // `lint` checks the syntax, arguments and plural categories of every translation value, and
1060
+ // `types` adds `parseInterpolation: false` to a new i18next.d.ts. See "ICU and MF2 messages" below.
1061
+ messageFormat: 'i18next', // Default: 'i18next'
1062
+
1048
1063
  // Warn (or error) when the same ns:key is extracted with different default values.
1049
1064
  warnOnConflicts: true // Default: false
1050
1065
  },
@@ -1745,6 +1760,33 @@ types: {
1745
1760
 
1746
1761
  This is useful for organizing translations into logical groups while maintaining type safety across your entire namespace hierarchy.
1747
1762
 
1763
+ ### ICU and MF2 messages
1764
+
1765
+ If your translations are written in ICU MessageFormat ([i18next-icu](https://github.com/i18next/i18next-icu)) or Unicode MessageFormat 2 ([i18next-mf2](https://github.com/i18next/i18next-mf2)), tell the CLI:
1766
+
1767
+ ```typescript
1768
+ export default defineConfig({
1769
+ locales: ['en', 'de', 'ru'],
1770
+ extract: {
1771
+ input: ['src/**/*.{ts,tsx}'],
1772
+ output: 'locales/{{language}}/{{namespace}}.json',
1773
+ messageFormat: 'icu', // or 'mf2'
1774
+ },
1775
+ })
1776
+ ```
1777
+
1778
+ What it changes:
1779
+
1780
+ - `extract` writes one key per message. `t('photos', '{count, plural, one {# photo} other {# photos}}', { count })` gives `photos`, not `photos_one` and `photos_other`, and `context` adds no `_male` keys, because ICU and MF2 keep plurals and selects inside the message and the plugins never read suffix keys. `$t()` in a value is text, not nesting. Plural suffix keys left over from an earlier extraction are removed like other unused keys.
1781
+ - `extract` writes the children of `<Trans>` with `{name}` (ICU) or `{$name}` (MF2) in the value; the key of a `<Trans>` without `i18nKey` stays what react-i18next builds at runtime (`Hello {{name}}`).
1782
+ - `extract` reads [`IcuTrans`](https://react.i18next.com/latest/icu-trans-component) and `IcuTransWithoutContext` (also when imported under another name): the key is `i18nKey`, or `defaultTranslation` when there is none, and `defaultTranslation` is the value. The components of `react-i18next/icu.macro` (`Trans`, `Plural`, `Select`, `SelectOrdinal`) are extracted with the message the macro builds, for example `<Trans i18nKey="welcome">Welcome, <strong>{name}</strong>!</Trans>` gives `Welcome, <0>{name}</0>!`. These two are recognized in every format, without adding them to `transComponents`.
1783
+ - `status` counts a plural or select message as one key.
1784
+ - `instrument` writes `{name}` / `{$name}` placeholders and escapes the text around them (`File '{{name}}'` becomes `File ''{name}'`, since an apostrophe before `{` starts quoted text in ICU), a ternary like `count === 1 ? 'task' : 'tasks'` becomes one plural message (`{count, plural, one {…} other {…}}`, MF2 `.match $count`) instead of `defaultValue_one` / `defaultValue_other`, and the i18n init file it creates registers `i18next-icu` or `i18next-mf2`.
1785
+ - `lint` parses every translation value and reports syntax errors, arguments that differ from the primary language and plural categories that do not fit a locale (see [`lint`](#lint)). The `t()` interpolation check reads the arguments with the same parser.
1786
+ - `types` sets `parseInterpolation: false` in a newly generated `i18next.d.ts`.
1787
+
1788
+ What keeps and what stops working at runtime with these formats (plural and context suffix keys, `$t()` nesting, i18next formatters, `escapeValue`) is described in [Using ICU or MF2](https://www.i18next.com/how-to/using-icu-or-mf2).
1789
+
1748
1790
  ## Migration from i18next-parser
1749
1791
 
1750
1792
  Automatically migrate from legacy `i18next-parser.config.js`:
package/dist/cjs/cli.js CHANGED
@@ -10,12 +10,14 @@ var config = require('./config.js');
10
10
  var heuristicConfig = require('./heuristic-config.js');
11
11
  var extractor = require('./extractor/core/extractor.js');
12
12
  require('node:path');
13
- require('node:module');
14
- var nestedObject = require('./utils/nested-object.js');
15
13
  require('node:fs/promises');
14
+ require('jsonc-parser');
16
15
  require('jiti');
17
16
  require('@croct/json5-parser');
18
17
  require('yaml');
18
+ require('node:module');
19
+ require('@swc/core');
20
+ var nestedObject = require('./utils/nested-object.js');
19
21
  var typesGenerator = require('./types-generator.js');
20
22
  var syncer = require('./syncer.js');
21
23
  var migrator = require('./migrator.js');
@@ -37,7 +39,7 @@ const program = new commander.Command();
37
39
  program
38
40
  .name('i18next-cli')
39
41
  .description('A unified, high-performance i18next CLI.')
40
- .version('1.75.2') // This string is replaced with the actual version at build time by rollup
42
+ .version('1.76.0') // This string is replaced with the actual version at build time by rollup
41
43
  .addHelpText('after', '\nUsing an AI coding agent? Install the i18next-localization skill: npx skills add i18next/i18next-cli\n');
42
44
  // new: global config override option
43
45
  program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
@@ -206,6 +206,7 @@ class ASTVisitors {
206
206
  // Reset per-file captured variables in the expression resolver so variables from other files don't leak.
207
207
  this.expressionResolver.resetFileSymbols();
208
208
  this.scopeManager.enterScope(); // Create the root scope for the file
209
+ this.jsxHandler.setReactI18nextImports(node.body ?? []);
209
210
  this.walk(node);
210
211
  this.scopeManager.exitScope(); // Clean up the root scope
211
212
  }
@@ -160,6 +160,10 @@ function mayContainExtractionSite(code, config) {
160
160
  }
161
161
  for (const component of config.extract.transComponents || ['Trans'])
162
162
  names.add(component.split('.').pop());
163
+ // always extracted, see JSXHandler
164
+ names.add('IcuTrans');
165
+ names.add('IcuTransWithoutContext');
166
+ names.add('icu.macro');
163
167
  const alt = (set) => [...set].map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
164
168
  re = new RegExp(`(?<!\\w)(?:(?:${alt(calls)})\\s*(?:\\?\\.\\s*)?[(<]|(?:${alt(names)})(?![\\w$]))`);
165
169
  extractionSiteRegexes.set(config, re);
@@ -8,6 +8,7 @@ var defaultValue = require('../../utils/default-value.js');
8
8
  var logger = require('../../utils/logger.js');
9
9
  var pluralRules = require('../../utils/plural-rules.js');
10
10
  var nesting = require('../../utils/nesting.js');
11
+ var messageFormat = require('../../utils/message-format.js');
11
12
  var contextVariants = require('../../utils/context-variants.js');
12
13
 
13
14
  // used for natural language check
@@ -280,6 +281,9 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
280
281
  })();
281
282
  const seenNestedValues = new Set();
282
283
  const collectFromValue = (value) => {
284
+ // ICU and MF2 output $t() as text, so it references no key
285
+ if (messageFormat.usesMessageFormat(config))
286
+ return;
283
287
  if (typeof value === 'string') {
284
288
  if (seenNestedValues.has(value))
285
289
  return;
@@ -2,6 +2,7 @@
2
2
 
3
3
  var pluralRules = require('../../utils/plural-rules.js');
4
4
  var nesting = require('../../utils/nesting.js');
5
+ var messageFormat = require('../../utils/message-format.js');
5
6
  var astUtils = require('./ast-utils.js');
6
7
  var functionMatcher = require('../utils/function-matcher.js');
7
8
 
@@ -184,11 +185,11 @@ class CallExpressionHandler {
184
185
  }
185
186
  let defaultValue;
186
187
  let options;
188
+ // Options inline or in a variable: `t('key', { count })`, `t('key', params)` (#307)
187
189
  if (node.arguments.length > 1) {
188
190
  const arg2 = astUtils.unwrapParens(node.arguments[1].expression);
189
- if (arg2.type === 'ObjectExpression') {
190
- options = arg2;
191
- }
191
+ options = this.expressionResolver.objectLiteralOf(arg2);
192
+ if (options) ;
192
193
  else if (arg2.type === 'StringLiteral') {
193
194
  defaultValue = arg2.value;
194
195
  }
@@ -200,10 +201,7 @@ class CallExpressionHandler {
200
201
  }
201
202
  }
202
203
  if (node.arguments.length > 2) {
203
- const arg3 = astUtils.unwrapParens(node.arguments[2].expression);
204
- if (arg3.type === 'ObjectExpression') {
205
- options = arg3;
206
- }
204
+ options = this.expressionResolver.objectLiteralOf(node.arguments[2].expression) ?? options;
207
205
  }
208
206
  const defaultValueFromOptions = options ? this.getDefaultValueProp(options, 'defaultValue') : undefined;
209
207
  const finalDefaultValue = (typeof defaultValueFromOptions === 'string' ? defaultValueFromOptions : defaultValue);
@@ -322,8 +320,10 @@ class CallExpressionHandler {
322
320
  const locationEntry = location
323
321
  ? [{ file: this.getCurrentFile(), line: location.line, column: location.column }]
324
322
  : undefined;
323
+ // ICU and MF2 keep plurals and selects inside one message: no context or plural keys
324
+ const plainMessage = messageFormat.usesMessageFormat(this.config);
325
325
  if (options) {
326
- const contextPropValue = astUtils.getObjectPropValueExpression(options, 'context');
326
+ const contextPropValue = plainMessage ? undefined : astUtils.getObjectPropValueExpression(options, 'context');
327
327
  const keysWithContext = [];
328
328
  // 1. Handle Context
329
329
  if (contextPropValue?.type === 'StringLiteral' || contextPropValue?.type === 'NumericLiteral' || contextPropValue?.type === 'BooleanLiteral') {
@@ -406,7 +406,7 @@ class CallExpressionHandler {
406
406
  }
407
407
  return false;
408
408
  })();
409
- if (hasCount || isOrdinalByKey) {
409
+ if (!plainMessage && (hasCount || isOrdinalByKey)) {
410
410
  // Check if plurals are disabled FIRST, before any plural optimization paths
411
411
  if (this.config.extract.disablePlurals) {
412
412
  // When plurals are disabled, treat count as a regular option (for interpolation only)
@@ -537,6 +537,9 @@ class CallExpressionHandler {
537
537
  * plugin context.
538
538
  */
539
539
  extractNestedKeys(text, _ns) {
540
+ // ICU and MF2 output $t() as text
541
+ if (messageFormat.usesMessageFormat(this.config))
542
+ return;
540
543
  const references = nesting.parseNestedReferences(text, {
541
544
  nestingPrefix: this.config.extract.nestingPrefix,
542
545
  nestingSuffix: this.config.extract.nestingSuffix,
@@ -1,6 +1,7 @@
1
1
  'use strict';
2
2
 
3
3
  var pluralRules = require('../../utils/plural-rules.js');
4
+ var messageFormat = require('../../utils/message-format.js');
4
5
 
5
6
  // Checks if a string looks like natural language (contains spaces, punctuation, etc.)
6
7
  const naturalLanguageChars = /[ ,?!;]/;
@@ -138,7 +139,11 @@ function extractKeysFromComments(code, pluginContext, config, scopeResolver, kee
138
139
  continue;
139
140
  }
140
141
  // 5. Handle context and count combinations based on disablePlurals setting
141
- if (config.extract.disablePlurals) {
142
+ if (messageFormat.usesMessageFormat(config)) {
143
+ // ICU and MF2 keep plurals and selects inside one message
144
+ pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key });
145
+ }
146
+ else if (config.extract.disablePlurals) {
142
147
  // When plurals are disabled, ignore count for key generation. We still
143
148
  // tag the key with `hasCount` (when a count was present) so `status` can
144
149
  // recognise it as count-driven; file generation ignores the flag under
@@ -83,10 +83,10 @@ class ModuleTable extends Map {
83
83
  if (value !== undefined)
84
84
  return value;
85
85
  }
86
- return super.get(name);
86
+ return undefined;
87
87
  }
88
88
  has(name) {
89
- return this.scope.keysOf(name).some(key => super.has(key)) || super.has(name);
89
+ return this.scope.keysOf(name).some(key => super.has(key));
90
90
  }
91
91
  set(name, value) {
92
92
  const key = this.scope.declaringKey(name);
@@ -185,6 +185,9 @@ class ExpressionResolver {
185
185
  // Per-file identifiers holding an object type, from their annotation or from the
186
186
  // function they were initialised by: `const animal = getAnimal()` -> { animal: { type: [...] } }
187
187
  objectVariables = new Map();
188
+ // Per-file object literals by variable, so `const params = { count }; t('key', params)`
189
+ // reads its options like an inline object (#307)
190
+ objectLiterals = new Map();
188
191
  // Set while the pre-scan runs. Captures that read other declarations queue a
189
192
  // replay here, because what they read may be declared in a file scanned later.
190
193
  recording = false;
@@ -204,6 +207,8 @@ class ExpressionResolver {
204
207
  fileImports = new Map();
205
208
  // module -> namespace import's local name -> the import's resolved path
206
209
  fileNamespaces = new Map();
210
+ // module -> the variables it declares, which shadow the same names declared in other files
211
+ fileVariables = new Map();
207
212
  // tsconfig `paths`, `@api` -> `/abs/src/api`
208
213
  pathAliases = {};
209
214
  constructor(hooks) {
@@ -232,16 +237,18 @@ class ExpressionResolver {
232
237
  }
233
238
  // ModuleTable: the keys `name` read in the current file may be stored under, most specific first
234
239
  keysOf(name) {
235
- if (name.includes('#'))
240
+ if (name.includes('#') || !this.currentModule)
236
241
  return [name];
237
- if (!this.currentModule)
238
- return [];
239
242
  const keys = [];
240
243
  const imported = this.fileImports.get(this.currentModule)?.get(name);
241
244
  const module = imported && this.moduleOf(imported.from);
242
245
  if (module)
243
246
  keys.push(`${module}#${imported.name}`);
244
247
  keys.push(`${this.currentModule}#${name}`);
248
+ // A variable of this file never means another file's same-named one, even when its own
249
+ // value isn't captured (`const params = { count }` vs another file's `params` array) (#307)
250
+ if (!this.fileVariables.get(this.currentModule)?.has(name))
251
+ keys.push(name);
245
252
  return keys;
246
253
  }
247
254
  // ModuleTable: the key a declaration made in the current file is also stored under
@@ -287,6 +294,7 @@ class ExpressionResolver {
287
294
  this.temporaryVariables.clear();
288
295
  this.arrayElementMembers.clear();
289
296
  this.objectVariables.clear();
297
+ this.objectLiterals.clear();
290
298
  }
291
299
  /**
292
300
  * Call once every file has been pre-scanned. Captures ran in file order, so one
@@ -402,6 +410,11 @@ class ExpressionResolver {
402
410
  if (node.id.type !== 'Identifier')
403
411
  return;
404
412
  const name = node.id.value;
413
+ if (this.currentModule) {
414
+ if (!this.fileVariables.has(this.currentModule))
415
+ this.fileVariables.set(this.currentModule, new Set());
416
+ this.fileVariables.get(this.currentModule).add(name);
417
+ }
405
418
  // `const items: IProps[] = …` → remember the element's member map so
406
419
  // `items.map(({ size }) => …)` can bind the callback parameter.
407
420
  const idTypeAnnotation = this.extractTypeAnnotation(node.id);
@@ -436,6 +449,7 @@ class ExpressionResolver {
436
449
  const unwrappedInit = unwrapExpr(init);
437
450
  // ObjectExpression -> map of string props
438
451
  if (unwrappedInit.type === 'ObjectExpression' && Array.isArray(unwrappedInit.properties)) {
452
+ this.objectLiterals.set(name, unwrappedInit);
439
453
  const map = {};
440
454
  for (const p of unwrappedInit.properties) {
441
455
  if (!p || p.type !== 'KeyValueProperty')
@@ -1105,6 +1119,13 @@ class ExpressionResolver {
1105
1119
  return v;
1106
1120
  return this.sharedVariableTable.get(name);
1107
1121
  }
1122
+ /** The object literal `expr` is, inline or through a variable of this file, or undefined. */
1123
+ objectLiteralOf(expr) {
1124
+ expr = unwrapExpr(expr);
1125
+ if (expr?.type === 'ObjectExpression')
1126
+ return expr;
1127
+ return expr?.type === 'Identifier' ? this.objectLiterals.get(expr.value) : undefined;
1128
+ }
1108
1129
  /**
1109
1130
  * Return the as-const object map stored for a variable name.
1110
1131
  * Returns undefined if the name is not a known object map.
@@ -2,18 +2,27 @@
2
2
 
3
3
  var pluralRules = require('../../utils/plural-rules.js');
4
4
  var jsxParser = require('./jsx-parser.js');
5
+ var messageFormat = require('../../utils/message-format.js');
5
6
  var astUtils = require('./ast-utils.js');
6
7
  var callExpressionHandler = require('./call-expression-handler.js');
7
8
 
8
9
  // Checks if a string looks like natural language (contains spaces, punctuation, etc.)
9
10
  const naturalLanguageChars = /[ ,?!;]/;
10
11
  const looksLikeNaturalLanguage = (s) => naturalLanguageChars.test(s);
12
+ // react-i18next's exports of the IcuTrans component (IcuTransWithoutContext is the one for React Server Components)
13
+ const ICU_TRANS_EXPORTS = ['IcuTrans', 'IcuTransWithoutContext'];
11
14
  class JSXHandler {
12
15
  config;
13
16
  pluginContext;
14
17
  expressionResolver;
15
18
  getCurrentFile;
16
19
  getCurrentCode;
20
+ /** local name -> component, for the components the current file imports from react-i18next/icu.macro */
21
+ icuMacroComponents = new Map();
22
+ /** the names IcuTrans is used under in the current file */
23
+ icuTransNames = new Set(ICU_TRANS_EXPORTS);
24
+ /** the <Trans> elements in the case props of a macro <Plural> or <Select>, which belong to its message */
25
+ consumedByMacro = new WeakSet();
17
26
  constructor(config, pluginContext, expressionResolver, getCurrentFile, getCurrentCode) {
18
27
  this.config = config;
19
28
  this.pluginContext = pluginContext;
@@ -21,6 +30,33 @@ class JSXHandler {
21
30
  this.getCurrentFile = getCurrentFile;
22
31
  this.getCurrentCode = getCurrentCode;
23
32
  }
33
+ /**
34
+ * Records the local names the current file imports the components of `react-i18next/icu.macro`
35
+ * (`Trans`, `Plural`, `Select`, `SelectOrdinal`) and `IcuTrans` / `IcuTransWithoutContext` under,
36
+ * so `import { IcuTrans as T }` and `import { Trans } from 'react-i18next/icu.macro'` are recognized.
37
+ */
38
+ setReactI18nextImports(body) {
39
+ this.icuMacroComponents = new Map();
40
+ this.icuTransNames = new Set(ICU_TRANS_EXPORTS);
41
+ for (const item of body) {
42
+ if (item.type !== 'ImportDeclaration')
43
+ continue;
44
+ const isMacro = /^react-i18next\/icu\.macro(\.js)?$/.test(item.source.value);
45
+ if (!isMacro && !/^react-i18next(\/|$)/.test(item.source.value))
46
+ continue;
47
+ for (const specifier of item.specifiers) {
48
+ if (specifier.type !== 'ImportSpecifier')
49
+ continue;
50
+ const imported = specifier.imported?.value ?? specifier.local.value;
51
+ if (isMacro && (imported === 'Trans' || imported === 'Plural' || imported === 'Select' || imported === 'SelectOrdinal')) {
52
+ this.icuMacroComponents.set(specifier.local.value, imported);
53
+ }
54
+ else if (!isMacro && ICU_TRANS_EXPORTS.includes(imported)) {
55
+ this.icuTransNames.add(specifier.local.value);
56
+ }
57
+ }
58
+ }
59
+ }
24
60
  /**
25
61
  * Computes line and column from a node's normalised span.
26
62
  * SWC spans are normalised to file-relative offsets after parsing,
@@ -124,12 +160,28 @@ class JSXHandler {
124
160
  * @param getScopeInfo - Function to retrieve scope information for variables
125
161
  */
126
162
  handleJSXElement(node, getScopeInfo) {
163
+ if (this.consumedByMacro.has(node))
164
+ return;
127
165
  const elementName = this.getElementName(node);
128
- if (elementName && (this.config.extract.transComponents || ['Trans']).includes(elementName)) {
129
- this.warnOnUnrepresentableTransChildren(node, elementName);
166
+ const macroComponent = elementName ? this.icuMacroComponents.get(elementName) : undefined;
167
+ if (macroComponent && macroComponent !== 'Trans') {
168
+ for (const attr of node.opening.attributes ?? []) {
169
+ if (attr.type === 'JSXAttribute' && attr.value?.type === 'JSXExpressionContainer')
170
+ this.consumedByMacro.add(attr.value.expression);
171
+ }
172
+ }
173
+ const isIcuTrans = !!elementName && this.icuTransNames.has(elementName);
174
+ if (elementName && (macroComponent || isIcuTrans || (this.config.extract.transComponents || ['Trans']).includes(elementName))) {
175
+ // the macro writes {name} on purpose, so only plain <Trans> gets the {{name}} advice
176
+ if (!macroComponent && !isIcuTrans)
177
+ this.warnOnUnrepresentableTransChildren(node, elementName);
130
178
  let extractedAttributes = null;
131
179
  try {
132
- extractedAttributes = jsxParser.extractFromTransComponent(node, this.config);
180
+ extractedAttributes = macroComponent
181
+ ? jsxParser.extractFromIcuMacro(node, macroComponent)
182
+ : isIcuTrans
183
+ ? jsxParser.extractFromIcuTrans(node)
184
+ : jsxParser.extractFromTransComponent(node, this.config);
133
185
  }
134
186
  catch (err) {
135
187
  const loc = this.getLocationFromNode(node);
@@ -157,7 +209,11 @@ class JSXHandler {
157
209
  keysToProcess.push(extractedAttributes.serializedChildren);
158
210
  }
159
211
  let extractedKeys;
160
- const { contextExpression, optionsNode, defaultValue, hasCount, isOrdinal, serializedChildren } = extractedAttributes;
212
+ const { optionsNode, defaultValue, isOrdinal, serializedChildren } = extractedAttributes;
213
+ // ICU and MF2 keep plurals and selects inside one message: no context or plural keys
214
+ const plainMessage = messageFormat.usesMessageFormat(this.config);
215
+ const contextExpression = plainMessage ? undefined : extractedAttributes.contextExpression;
216
+ const hasCount = !plainMessage && extractedAttributes.hasCount;
161
217
  // Extract location information using the helper method
162
218
  const location = this.getLocationFromNode(node);
163
219
  const locations = location
@@ -1,7 +1,9 @@
1
1
  'use strict';
2
2
 
3
3
  var astUtils = require('./ast-utils.js');
4
+ var messageFormat = require('../../utils/message-format.js');
4
5
  var node_module = require('node:module');
6
+ var core = require('@swc/core');
5
7
 
6
8
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
7
9
  let cachedReactI18next;
@@ -274,7 +276,8 @@ function extractFromTransComponent(node, config) {
274
276
  defaultValue = processedKeyValue;
275
277
  }
276
278
  else if (!defaultsAttr && serialized.trim()) {
277
- defaultValue = serialized;
279
+ // react-i18next serializes interpolation objects as {{name}}; ICU and MF2 values need {name} / {$name}
280
+ defaultValue = messageFormat.toMessageFormatPlaceholders(serialized, config);
278
281
  }
279
282
  // Determine if tOptions contained explicit defaultValue* properties
280
283
  const optionsHasDefaultProps = (opts) => {
@@ -302,6 +305,161 @@ function extractFromTransComponent(node, config) {
302
305
  explicitDefault
303
306
  };
304
307
  }
308
+ function findAttribute(node, name) {
309
+ return node.opening.attributes?.find((attr) => attr.type === 'JSXAttribute' && attr.name.type === 'Identifier' && attr.name.value === name);
310
+ }
311
+ // The `i18nKey` of an IcuTrans or icu.macro component, undefined when there is none (the message is the key then)
312
+ function getKeyExpression(node) {
313
+ const attr = findAttribute(node, 'i18nKey');
314
+ if (attr?.value?.type === 'StringLiteral')
315
+ return attr.value.value.trim() ? attr.value : undefined;
316
+ if (attr?.value?.type === 'JSXExpressionContainer' && attr.value.expression.type !== 'JSXEmptyExpression')
317
+ return attr.value.expression;
318
+ return undefined;
319
+ }
320
+ /**
321
+ * Extracts react-i18next's `<IcuTrans i18nKey="invite" defaultTranslation="We invited <0>{user}</0>." />`.
322
+ * Like IcuTrans at runtime, the key is `i18nKey`, or `defaultTranslation` when there is none.
323
+ */
324
+ function extractFromIcuTrans(node) {
325
+ const defaultAttr = findAttribute(node, 'defaultTranslation');
326
+ const defaultTranslation = (defaultAttr && getStringLiteralFromAttribute(defaultAttr)) ?? '';
327
+ const keyExpression = getKeyExpression(node);
328
+ if (!keyExpression && !defaultTranslation.trim())
329
+ return null;
330
+ const nsAttr = findAttribute(node, 'ns');
331
+ return {
332
+ keyExpression,
333
+ serializedChildren: defaultTranslation,
334
+ defaultValue: defaultTranslation,
335
+ ns: nsAttr && getStringLiteralFromAttribute(nsAttr),
336
+ explicitDefault: !!defaultTranslation,
337
+ };
338
+ }
339
+ /**
340
+ * Extracts the components of `react-i18next/icu.macro`. The macro compiles them to IcuTrans with a
341
+ * `defaultTranslation` it builds from the children or props, and that is the key when there is no
342
+ * `i18nKey`, so the message is built exactly like the macro does (quirks included):
343
+ *
344
+ * - `<Trans>Welcome, <strong>{name}</strong>!</Trans>` → `Welcome, <0>{name}</0>!`
345
+ * - `<Plural count={count} one="# item" other="# items" />` → `{count, plural, one {# item} other {# items}}`
346
+ * - `<Select switch={gender} male="He" other="They" />` → `{gender, select, male {He} other {They}}`
347
+ */
348
+ function extractFromIcuMacro(node, component) {
349
+ let message;
350
+ let ns;
351
+ if (component === 'Trans') {
352
+ const defaultsAttr = findAttribute(node, 'defaults');
353
+ const defaults = defaultsAttr && getStringLiteralFromAttribute(defaultsAttr);
354
+ // the macro parses `defaults` as JSX children, unless `content` or `components` is set
355
+ // (then it builds an empty message from the children it no longer has)
356
+ const children = defaults === undefined
357
+ ? node.children
358
+ : findAttribute(node, 'content') || findAttribute(node, 'components')
359
+ ? []
360
+ : core.parseSync(`<>${defaults}</>`, { syntax: 'ecmascript', jsx: true }).body[0].expression.children;
361
+ message = mergeMacroChildren(children, 0).text;
362
+ const nsAttr = findAttribute(node, 'ns');
363
+ ns = nsAttr && getStringLiteralFromAttribute(nsAttr);
364
+ }
365
+ else {
366
+ // Plural, Select and SelectOrdinal do not pass `ns` on (the macro would make it a case)
367
+ message = buildMacroChoice(node, component);
368
+ }
369
+ const keyExpression = getKeyExpression(node);
370
+ if (!keyExpression && !message.trim())
371
+ return null;
372
+ return { keyExpression, serializedChildren: message, defaultValue: message, ns };
373
+ }
374
+ // Port of icu.macro's mergeChildren: text, {name}, {name, number}, tagged templates, and <N>…</N>
375
+ // for every element, numbered per nesting level. Fragments and other expressions are dropped.
376
+ function mergeMacroChildren(children, start) {
377
+ let index = start;
378
+ let text = '';
379
+ for (const child of children) {
380
+ if (child.type === 'JSXText') {
381
+ text += child.value.replace(/^\n\s+/, '').replace(/\n\s+$/, '');
382
+ }
383
+ else if (child.type === 'JSXElement') {
384
+ text += `<${index}>${mergeMacroChildren(child.children, 0).text}</${index}>`;
385
+ index++;
386
+ }
387
+ else if (child.type === 'JSXExpressionContainer') {
388
+ const expr = child.expression;
389
+ if ((expr.type === 'StringLiteral' || expr.type === 'NumericLiteral' || expr.type === 'BooleanLiteral') && expr.value) {
390
+ text += String(expr.value);
391
+ }
392
+ else if (expr.type === 'Identifier') {
393
+ text += `{${expr.value}}`;
394
+ }
395
+ else if (expr.type === 'SequenceExpression') {
396
+ text += `{${expr.expressions.map((e) => e.value ?? '').join(', ')}}`;
397
+ }
398
+ else if (expr.type === 'TaggedTemplateExpression') {
399
+ const merged = mergeMacroTemplate(expr, index);
400
+ text += merged.text;
401
+ index = merged.next;
402
+ }
403
+ }
404
+ }
405
+ return { text, next: index };
406
+ }
407
+ // Port of icu.macro's tagged templates: number`${n}` → {n, number}, plural`${count}, one {…} other {…}` → {count, plural, …}
408
+ function mergeMacroTemplate(node, start) {
409
+ const type = node.tag.type === 'Identifier' ? node.tag.value : 'unknown';
410
+ const { quasis, expressions } = node.template;
411
+ let index = start;
412
+ let text = '';
413
+ quasis.forEach((quasi, i) => {
414
+ text += (quasi.cooked ?? '').replace(/\s+/g, ' ');
415
+ const expr = expressions[i];
416
+ if (!expr)
417
+ return;
418
+ if (expr.type === 'Identifier') {
419
+ text += `${expr.value}, ${type}`;
420
+ }
421
+ else if (expr.type === 'JSXElement') {
422
+ text += `<${index}>${mergeMacroChildren(expr.children, 0).text}</${index}>`;
423
+ index++;
424
+ }
425
+ else if (expr.type === 'TaggedTemplateExpression') {
426
+ const merged = mergeMacroTemplate(expr, index);
427
+ text += merged.text;
428
+ index = merged.next;
429
+ }
430
+ });
431
+ return { text: `{${text}}`, next: index };
432
+ }
433
+ // Port of icu.macro's pluralAsJSX / selectAsJSX
434
+ function buildMacroChoice(node, component) {
435
+ const type = component === 'Select' ? 'select' : component.toLowerCase();
436
+ const switchProp = component === 'Select' ? 'switch' : 'count';
437
+ let message = '';
438
+ let index = 0;
439
+ for (const attr of node.opening.attributes ?? []) {
440
+ if (attr.type !== 'JSXAttribute' || attr.name.type !== 'Identifier')
441
+ continue;
442
+ const name = attr.name.value;
443
+ if (name === 'i18nKey' || name === 'values')
444
+ continue;
445
+ const selector = component !== 'Select' && name.startsWith('$') ? `=${name.slice(1)}` : name;
446
+ if (name === switchProp) {
447
+ const expr = attr.value?.type === 'JSXExpressionContainer' ? attr.value.expression : undefined;
448
+ const arg = expr?.type === 'Identifier' ? expr.value : component === 'Select' ? 'selectKey' : 'count';
449
+ message = `{${arg}, ${type}, ${message}`;
450
+ }
451
+ else if (attr.value?.type === 'StringLiteral') {
452
+ message = `${message} ${selector} {${attr.value.value}}`;
453
+ }
454
+ else if (attr.value?.type === 'JSXExpressionContainer') {
455
+ const expr = attr.value.expression;
456
+ const merged = mergeMacroChildren(expr.type === 'JSXElement' || expr.type === 'JSXFragment' ? expr.children : [], index);
457
+ message = `${message} ${selector} {${merged.text}}`;
458
+ index = merged.next;
459
+ }
460
+ }
461
+ return `${message}}`;
462
+ }
305
463
  /**
306
464
  * Creates a dummy React component. The implementation / return value is
307
465
  * irrelevant, as long as we have something realistic-looking to pass to
@@ -508,4 +666,6 @@ function serializeJSXChildren(children, config) {
508
666
  return rt.nodesToString(swcChildrenToReactNodes(children), i18nextOptions);
509
667
  }
510
668
 
669
+ exports.extractFromIcuMacro = extractFromIcuMacro;
670
+ exports.extractFromIcuTrans = extractFromIcuTrans;
511
671
  exports.extractFromTransComponent = extractFromTransComponent;
package/dist/cjs/index.js CHANGED
@@ -5,7 +5,14 @@ var extractor = require('./extractor/core/extractor.js');
5
5
  var keyFinder = require('./extractor/core/key-finder.js');
6
6
  var translationManager = require('./extractor/core/translation-manager.js');
7
7
  require('node:path');
8
+ require('node:fs/promises');
9
+ require('glob');
10
+ require('jsonc-parser');
11
+ require('jiti');
12
+ require('@croct/json5-parser');
13
+ require('yaml');
8
14
  require('node:module');
15
+ require('@swc/core');
9
16
  var linter = require('./linter.js');
10
17
  var syncer = require('./syncer.js');
11
18
  var status = require('./status.js');
@@ -15,7 +22,6 @@ var instrumenter = require('./instrumenter/core/instrumenter.js');
15
22
  require('./utils/jsx-attributes.js');
16
23
  require('magic-string');
17
24
  var localize = require('./localize/localize.js');
18
- require('node:fs/promises');
19
25
  var agentPrompt = require('./localize/agent-prompt.js');
20
26
 
21
27