i18next-cli 1.89.0 → 1.91.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 (51) hide show
  1. package/README.md +57 -7
  2. package/dist/cjs/cli.js +8 -4
  3. package/dist/cjs/config.js +13 -12
  4. package/dist/cjs/extractor/core/extractor.js +1 -3
  5. package/dist/cjs/extractor/parsers/jsx-parser.js +4 -2
  6. package/dist/cjs/heuristic-config.js +51 -6
  7. package/dist/cjs/init.js +5 -0
  8. package/dist/cjs/instrumenter/core/instrumenter.js +272 -23
  9. package/dist/cjs/instrumenter/core/key-generator.js +1 -0
  10. package/dist/cjs/instrumenter/core/next-files.js +104 -0
  11. package/dist/cjs/instrumenter/core/transformer.js +97 -73
  12. package/dist/cjs/linter.js +190 -23
  13. package/dist/cjs/localize/agent-prompt.js +5 -2
  14. package/dist/cjs/localize/detect.js +1 -0
  15. package/dist/cjs/localize/localize.js +25 -4
  16. package/dist/esm/cli.js +8 -4
  17. package/dist/esm/config.js +13 -12
  18. package/dist/esm/extractor/core/extractor.js +1 -3
  19. package/dist/esm/extractor/parsers/jsx-parser.js +4 -3
  20. package/dist/esm/heuristic-config.js +52 -7
  21. package/dist/esm/init.js +5 -0
  22. package/dist/esm/instrumenter/core/instrumenter.js +273 -24
  23. package/dist/esm/instrumenter/core/key-generator.js +1 -0
  24. package/dist/esm/instrumenter/core/next-files.js +101 -0
  25. package/dist/esm/instrumenter/core/transformer.js +97 -73
  26. package/dist/esm/linter.js +192 -25
  27. package/dist/esm/localize/agent-prompt.js +5 -2
  28. package/dist/esm/localize/detect.js +1 -0
  29. package/dist/esm/localize/localize.js +25 -4
  30. package/package.json +2 -1
  31. package/types/cli.d.ts.map +1 -1
  32. package/types/config.d.ts.map +1 -1
  33. package/types/extractor/core/extractor.d.ts.map +1 -1
  34. package/types/extractor/parsers/jsx-parser.d.ts +1 -0
  35. package/types/extractor/parsers/jsx-parser.d.ts.map +1 -1
  36. package/types/heuristic-config.d.ts.map +1 -1
  37. package/types/init.d.ts.map +1 -1
  38. package/types/instrumenter/core/instrumenter.d.ts.map +1 -1
  39. package/types/instrumenter/core/key-generator.d.ts.map +1 -1
  40. package/types/instrumenter/core/next-files.d.ts +25 -0
  41. package/types/instrumenter/core/next-files.d.ts.map +1 -0
  42. package/types/instrumenter/core/transformer.d.ts +6 -0
  43. package/types/instrumenter/core/transformer.d.ts.map +1 -1
  44. package/types/linter.d.ts.map +1 -1
  45. package/types/localize/agent-prompt.d.ts +1 -1
  46. package/types/localize/agent-prompt.d.ts.map +1 -1
  47. package/types/localize/detect.d.ts +2 -0
  48. package/types/localize/detect.d.ts.map +1 -1
  49. package/types/localize/localize.d.ts.map +1 -1
  50. package/types/types.d.ts +54 -2
  51. package/types/types.d.ts.map +1 -1
@@ -7,6 +7,18 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
7
7
 
8
8
  var MagicString__default = /*#__PURE__*/_interopDefault(MagicString);
9
9
 
10
+ /** The hook a component gets `t` from, and where `useTranslation`/`useT`/`getT` and `Trans` are imported from. */
11
+ function bindingsFor(next) {
12
+ switch (next?.kind) {
13
+ case 'server': return { hook: 'getT', hookModule: next.serverModule, transModule: 'react-i18next/TransWithoutContext', call: args => `await getT(${args})` };
14
+ // its `t` is a prop: no hook; a <Trans> without context works on both sides
15
+ case 'shared':
16
+ case 'unknown': return { hook: 'useT', hookModule: 'next-i18next/client', transModule: 'react-i18next/TransWithoutContext', call: args => `useT(${args})` };
17
+ case 'client': return { hook: 'useT', hookModule: 'next-i18next/client', transModule: 'next-i18next/client', call: args => `useT(${args})` };
18
+ case 'pages': return { hook: 'useTranslation', hookModule: 'next-i18next/pages', transModule: 'next-i18next/pages', call: args => `useTranslation(${args})` };
19
+ default: return { hook: 'useTranslation', hookModule: 'react-i18next', transModule: 'react-i18next', call: args => `useTranslation(${args})` };
20
+ }
21
+ }
10
22
  /**
11
23
  * Transforms a source file, replacing candidate strings with instrumented code.
12
24
  * Also injects useTranslation() hooks into React function components that
@@ -27,6 +39,10 @@ function transformFile(content, file, candidates, options) {
27
39
  importAdded: false,
28
40
  hookInjected: false
29
41
  };
42
+ const bindings = bindingsFor(options.next);
43
+ // A <Trans> in a Server Component has no React context: it takes `t` and `i18n` from getT()
44
+ // (and in a component that Server and Client Components both render, from its props)
45
+ const transProps = ['server', 'shared', 'unknown'].includes(options.next?.kind ?? '') ? ' t={t} i18n={i18n}' : '';
30
46
  // <Trans> attributes in the quotes the file's JSX attributes use (`title='…'` or `title="…"`)
31
47
  // (a file without quoted attributes: the quotes of its imports)
32
48
  const singleQuoted = (single, double) => Math.sign((content.match(single)?.length ?? 0) - (content.match(double)?.length ?? 0));
@@ -89,7 +105,7 @@ function transformFile(content, file, candidates, options) {
89
105
  // <Trans> works in any render code, a helper outside a component too; without React the text stays
90
106
  if (candidate.type === 'jsx-mixed' && !options.hasReact)
91
107
  continue;
92
- const replacement = buildReplacement(candidate, key, useHookStyle, nsForReplacement, jsxQuote);
108
+ const replacement = buildReplacement(candidate, key, useHookStyle, nsForReplacement, jsxQuote, transProps);
93
109
  if (replacement) {
94
110
  s.overwrite(candidate.offset, candidate.endOffset, replacement);
95
111
  transformCount++;
@@ -98,8 +114,9 @@ function transformFile(content, file, candidates, options) {
98
114
  if (candidate.type === 'jsx-mixed') {
99
115
  hasTransCandidates = true;
100
116
  }
101
- // jsx-mixed candidates use <Trans>, not t(), so they need neither useTranslation nor i18next
102
- if (candidate.type !== 'jsx-mixed') {
117
+ // jsx-mixed candidates use <Trans>, not t(), so they need neither useTranslation nor i18next (but in a
118
+ // Server Component its `t` and `i18n`)
119
+ if (candidate.type !== 'jsx-mixed' || (transProps && candidate.insideComponent)) {
103
120
  if (candidate.insideComponent) {
104
121
  transformedComponents.add(candidate.insideComponent);
105
122
  }
@@ -131,10 +148,6 @@ function transformFile(content, file, candidates, options) {
131
148
  const components = options.components || [];
132
149
  // Inject useTranslation() hooks into affected React components
133
150
  if (options.hasReact && transformedComponents.size > 0) {
134
- // Process components in reverse order of bodyStart to avoid offset shifts
135
- const affectedComponents = components
136
- .filter(c => transformedComponents.has(c.name) && !c.hasUseTranslation)
137
- .sort((a, b) => b.bodyStart - a.bodyStart);
138
151
  const addHookLine = (comp, line) => {
139
152
  const indent = comp.expressionBody ? lineIndent(content, comp.bodyStart) + ' ' : detectIndent(content, comp.bodyStart);
140
153
  if (comp.expressionBody) {
@@ -145,60 +158,58 @@ function transformFile(content, file, candidates, options) {
145
158
  else {
146
159
  s.appendRight(comp.bodyStart + 1, `\n${indent}${line}`);
147
160
  }
161
+ // getT() is awaited: a Server Component becomes async, and `export const metadata = {…}` the function
162
+ // Next.js calls instead, `export async function generateMetadata () { …; return {…} }`
163
+ if (comp.metadataHead) {
164
+ const { start, end, type } = comp.metadataHead;
165
+ // contentOnly: the block that wraps the object starts at `end`, and stays
166
+ s.overwrite(start, end, `async function generateMetadata ()${type ? `: Promise<${type}>` : ''} `, { contentOnly: true });
167
+ }
168
+ else if (options.next?.kind === 'server' && !comp.isAsync && comp.start !== undefined) {
169
+ s.appendLeft(comp.start, 'async ');
170
+ // an async function returns a promise: `(): JSX.Element` becomes `(): Promise<JSX.Element>`
171
+ const type = comp.returnType;
172
+ if (type && !/^Promise\s*</.test(content.slice(type.start, type.end))) {
173
+ s.appendLeft(type.start, 'Promise<');
174
+ s.appendRight(type.end, '>');
175
+ }
176
+ }
148
177
  injections.hookInjected = true;
149
178
  };
150
- for (const comp of affectedComponents) {
179
+ // Components in reverse order of bodyStart to avoid offset shifts
180
+ for (const comp of components.filter(c => transformedComponents.has(c.name)).sort((a, b) => b.bodyStart - a.bodyStart)) {
151
181
  const defaultNS = options.config.extract?.defaultNS ?? 'translation';
152
182
  const nsArg = (options.namespace && options.namespace !== defaultNS) ? `'${options.namespace}'` : '';
153
- // Build destructuring: include `t` if the component has string candidates
154
- // (but not jsx-mixed which use <Trans>),
155
- // include `i18n` if the component has language-change sites.
156
- const needsT = highConfidenceCandidates.some(c => c.insideComponent === comp.name && c.type !== 'jsx-mixed');
157
- const needsI18n = componentsNeedingI18n.has(comp.name);
158
- const parts = [];
159
- if (needsT)
160
- parts.push('t');
161
- if (needsI18n)
162
- parts.push('i18n');
163
- // Skip if component needs neither t nor i18n
164
- // (e.g. component only has jsx-mixed / <Trans> candidates)
165
- if (!needsT && !needsI18n)
183
+ // `t` for its t() calls (and a <Trans> in a Server Component), `i18n` for a language change (and that <Trans>)
184
+ const own = highConfidenceCandidates.filter(c => c.insideComponent === comp.name);
185
+ const needsT = !comp.hasUseTranslation && own.some(c => c.type !== 'jsx-mixed' || transProps);
186
+ const needsI18n = componentsNeedingI18n.has(comp.name) || (!!transProps && !comp.i18nParam && own.some(c => c.type === 'jsx-mixed'));
187
+ const missing = [needsT && 't', needsI18n && !comp.hookPattern?.names.includes('i18n') && 'i18n'].filter(Boolean);
188
+ if (!missing.length)
166
189
  continue;
167
- addHookLine(comp, `const { ${parts.join(', ')} } = useTranslation(${nsArg})`);
168
- }
169
- // For components that already have useTranslation but need i18n added,
170
- // try to upgrade `const { t } = useTranslation(...)` → `const { t, i18n } = useTranslation(...)`
171
- if (componentsNeedingI18n.size > 0) {
172
- const compsWithExistingHook = components.filter(c => componentsNeedingI18n.has(c.name) && c.hasUseTranslation);
173
- for (const comp of compsWithExistingHook) {
174
- // Search for the destructuring pattern within the component body
175
- const bodyText = content.slice(comp.bodyStart, comp.bodyEnd);
176
- // Skip if i18n is already destructured
177
- if (/const\s*\{[^}]*\bi18n\b[^}]*\}\s*=\s*useTranslation/.test(bodyText))
178
- continue;
179
- // Match `{ t }` or `{ t, ... }` in `const { t } = useTranslation`
180
- const hookRe = /const\s*\{\s*t\s*\}\s*=\s*useTranslation/;
181
- const hookMatch = hookRe.exec(bodyText);
182
- if (hookMatch) {
183
- const absStart = comp.bodyStart + hookMatch.index;
184
- const absEnd = absStart + hookMatch[0].length;
185
- const upgraded = hookMatch[0].replace(/\{\s*t\s*\}/, '{ t, i18n }');
186
- s.overwrite(absStart, absEnd, upgraded);
187
- }
188
- else {
189
- // its `t` is a prop or comes from another hook: `i18n` needs a hook of its own
190
- addHookLine(comp, 'const { i18n } = useTranslation()');
191
- }
190
+ // that call gives `t` only to the code after it: a text before it would read `t` before its declaration
191
+ const before = (offset) => offset < comp.hookPattern.statement;
192
+ const usedBefore = comp.hookPattern && (own.some(c => before(c.offset)) ||
193
+ languageChangeSites.some(site => site.insideComponent === comp.name && before(site.callStart)));
194
+ if (comp.hookPattern && !usedBefore && (comp.hasUseTranslation || !comp.hookPattern.names.includes('t'))) {
195
+ // it calls a translation hook already (`const { i18n } = useT('ns')`): that call gives them, from its
196
+ // namespace (`{ t, i18n }`)
197
+ if (missing.includes('t'))
198
+ s.appendLeft(comp.hookPattern.first, 't, ');
199
+ if (missing.includes('i18n'))
200
+ s.appendRight(comp.hookPattern.last, ', i18n');
201
+ }
202
+ else {
203
+ addHookLine(comp, `const { ${missing.join(', ')} } = ${bindings.call(missing.includes('t') ? nsArg : '')}`);
192
204
  }
193
205
  }
194
206
  }
195
207
  // Add import statements
196
- addImportStatements(s, content, {
208
+ addImportStatements(s, content, [
197
209
  // only for a hook injected here: a component with a `t` of its own (a prop) needs none
198
- needsUseTranslation: injections.hookInjected,
199
- needsI18next: hasNonComponentCandidates || !options.hasReact,
200
- needsTrans: hasTransCandidates && options.hasReact
201
- }, options.imports);
210
+ ...(injections.hookInjected ? [{ name: bindings.hook, module: bindings.hookModule }] : []),
211
+ ...(hasTransCandidates && options.hasReact ? [{ name: 'Trans', module: bindings.transModule }] : [])
212
+ ], hasNonComponentCandidates || !options.hasReact, options.imports);
202
213
  injections.importAdded = true;
203
214
  }
204
215
  // Warn when i18next.t() is used in React projects (translations may not be loaded yet)
@@ -230,7 +241,7 @@ function transformFile(content, file, candidates, options) {
230
241
  * @param useHookStyle - If true, uses t() (from useTranslation hook); otherwise uses i18next.t()
231
242
  * @param namespace - Optional namespace (only set when different from defaultNS)
232
243
  */
233
- function buildReplacement(candidate, key, useHookStyle, namespace, jsxQuote = '"') {
244
+ function buildReplacement(candidate, key, useHookStyle, namespace, jsxQuote = '"', transProps = '') {
234
245
  const tFunc = useHookStyle ? 't' : 'i18next.t';
235
246
  const escapedContent = escapeString(candidate.content);
236
247
  // ── Plural form: t('key', { defaultValue_zero: '…', …, count: expr }) ──
@@ -281,7 +292,7 @@ function buildReplacement(candidate, key, useHookStyle, namespace, jsxQuote = '"
281
292
  return `{${tCall}}`;
282
293
  case 'jsx-mixed': {
283
294
  const nsAttr = namespace ? ` ns=${jsxQuote}${namespace}${jsxQuote}` : '';
284
- return `<Trans i18nKey=${jsxQuote}${key}${jsxQuote}${nsAttr}>${candidate.content}</Trans>`;
295
+ return `<Trans i18nKey=${jsxQuote}${key}${jsxQuote}${nsAttr}${transProps}>${candidate.content}</Trans>`;
285
296
  }
286
297
  case 'template-literal':
287
298
  case 'string-literal':
@@ -339,33 +350,33 @@ function detectIndent(content, braceOffset) {
339
350
  return ' ';
340
351
  }
341
352
  /**
342
- * Adds necessary import statements (useTranslation, Trans, and/or i18next).
353
+ * Adds the import statements the rewrite needs: the named imports `needed` (a hook, `Trans`), each from its module
354
+ * (added to an import of that module the file has), and `i18next` for `i18next.t()`.
343
355
  */
344
- function addImportStatements(s, content, needs, imports) {
356
+ function addImportStatements(s, content, needed, needsI18next, imports) {
345
357
  let importStatement = '';
346
358
  const imported = (moduleName) => imports
347
359
  ? imports.some(i => i.source === moduleName) || new RegExp(`require\\(['"]${moduleName}['"]\\)`).test(content)
348
360
  : hasImport(content, moduleName);
349
361
  // A name the file imports already, from any module (`useTranslation` re-exported by a shared package)
350
362
  const bound = (name) => !!imports?.some(i => i.locals?.includes(name));
351
- // Build a combined react-i18next import
352
- const reactI18nextImports = [];
353
- if (needs.needsUseTranslation && !bound('useTranslation'))
354
- reactI18nextImports.push('useTranslation');
355
- if (needs.needsTrans && !bound('Trans'))
356
- reactI18nextImports.push('Trans');
357
- if (reactI18nextImports.length > 0) {
358
- if (!imported('react-i18next')) {
359
- importStatement += `import { ${reactI18nextImports.join(', ')} } from 'react-i18next'\n`;
363
+ const byModule = new Map();
364
+ for (const { name, module } of needed) {
365
+ if (!bound(name))
366
+ byModule.set(module, [...(byModule.get(module) ?? []), name]);
367
+ }
368
+ for (const [module, names] of byModule) {
369
+ if (!imported(module)) {
370
+ importStatement += `import { ${names.join(', ')} } from '${module}'\n`;
360
371
  }
361
372
  else {
362
- // react-i18next is already imported — augment with any missing named exports
363
- const existing = imports?.find(i => i.source === 'react-i18next');
364
- augmentReactI18nextImport(s, content, reactI18nextImports, existing?.start ?? 0);
373
+ // the module is imported already: augment it with the missing named exports
374
+ const existing = imports?.find(i => i.source === module);
375
+ augmentNamedImport(s, content, module, names, existing?.start ?? 0);
365
376
  }
366
377
  }
367
378
  // `i18next.t()` needs that name: with the AST, an import of i18next under another name does not count
368
- if (needs.needsI18next && (imports ? !bound('i18next') : !imported('i18next'))) {
379
+ if (needsI18next && (imports ? !bound('i18next') : !imported('i18next'))) {
369
380
  importStatement += "import i18next from 'i18next'\n";
370
381
  }
371
382
  if (!importStatement)
@@ -376,6 +387,13 @@ function addImportStatements(s, content, needs, imports) {
376
387
  if (content.startsWith('#!')) {
377
388
  insertPos = content.indexOf('\n') + 1;
378
389
  }
390
+ // and the directives (`'use client'`), which must stay the first statements
391
+ const directives = DIRECTIVES_RE.exec(content.slice(insertPos));
392
+ if (directives) {
393
+ insertPos += directives[0].length;
394
+ if (content[insertPos - 1] !== '\n')
395
+ importStatement = `\n${importStatement}`;
396
+ }
379
397
  if (imports) {
380
398
  // After the last import declaration's line
381
399
  const lastEnd = Math.max(...imports.map(i => i.end), -1);
@@ -405,6 +423,8 @@ function addImportStatements(s, content, needs, imports) {
405
423
  importStatement = `\n${importStatement}`;
406
424
  s.appendRight(insertPos, importStatement);
407
425
  }
426
+ /** The directive prologue: `'use client'`, `'use strict'` and the like, with the comments around them, to the line end. */
427
+ const DIRECTIVES_RE = /^(?:(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*(['"])use [\w ]+\1;?[^\S\n]*(?:\/\/[^\n]*)?(?:\n|$))+/;
408
428
  /**
409
429
  * Returns the offset just past the end of the import statement that begins at
410
430
  * `start`, handling multi-line imports with `{ ... }` clauses. The statement
@@ -453,21 +473,25 @@ function findImportStatementEnd(content, start) {
453
473
  return content.length;
454
474
  }
455
475
  /**
456
- * Augments an existing `import { ... } from 'react-i18next'` with any missing
476
+ * Augments an existing `import { ... } from '<module>'` with any missing
457
477
  * named exports (e.g. adds `Trans` when only `useTranslation` is imported).
478
+ * A module imported without braces (`import i18n from …`) gets its own import.
458
479
  */
459
- function augmentReactI18nextImport(s, content, needed, from = 0) {
460
- const importRegex = /import\s*\{([^}]*)\}\s*from\s*['"]react-i18next['"]/g;
480
+ function augmentNamedImport(s, content, module, needed, from = 0) {
481
+ const quoted = module.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
482
+ const importRegex = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*['"]${quoted}['"]`, 'g');
461
483
  importRegex.lastIndex = from;
462
484
  const importMatch = importRegex.exec(content);
463
- if (!importMatch)
485
+ if (!importMatch) {
486
+ s.prependLeft(from, `import { ${needed.join(', ')} } from '${module}'\n`);
464
487
  return;
488
+ }
465
489
  const existingImports = importMatch[1].split(',').map(x => x.trim()).filter(Boolean);
466
490
  const toAdd = needed.filter(n => !existingImports.includes(n));
467
491
  if (toAdd.length === 0)
468
492
  return;
469
493
  const newImports = [...existingImports, ...toAdd].join(', ');
470
- const newImportStatement = `import { ${newImports} } from 'react-i18next'`;
494
+ const newImportStatement = `import { ${newImports} } from '${module}'`;
471
495
  const matchStart = importMatch.index;
472
496
  const matchEnd = matchStart + importMatch[0].length;
473
497
  s.overwrite(matchStart, matchEnd, newImportStatement);
@@ -10,9 +10,12 @@ var logger = require('./utils/logger.js');
10
10
  var wrapOra = require('./utils/wrap-ora.js');
11
11
  var jsxAttributes = require('./utils/jsx-attributes.js');
12
12
  var astUtils = require('./extractor/parsers/ast-utils.js');
13
+ var jsxParser = require('./extractor/parsers/jsx-parser.js');
13
14
  var functionMatcher = require('./extractor/utils/function-matcher.js');
14
15
  var astVisitors = require('./extractor/core/ast-visitors.js');
15
16
  var nestedObject = require('./utils/nested-object.js');
17
+ var fileUtils = require('./utils/file-utils.js');
18
+ var htmlParseStringify = require('html-parse-stringify');
16
19
  var messageFormat = require('./utils/message-format.js');
17
20
  var lintBaseline = require('./utils/lint-baseline.js');
18
21
  var funnelMsgTracker = require('./utils/funnel-msg-tracker.js');
@@ -186,27 +189,12 @@ function lintInterpolationParams(ast, code, config, translationValues, analyze)
186
189
  return code.substring(0, pos).split('\n').length;
187
190
  };
188
191
  const callSites = [];
189
- // The keys the extractor resolves for each call (selector path, keyPrefix and namespace scope
190
- // included), walked once and only for a file with a selector call: `t($ => $.a.b)` → ['a.b']
192
+ // The keys the extractor resolves for each call, walked once and only for a file with a selector
193
+ // call: `t($ => $.a.b)` → ['a.b']
191
194
  let keysByCall;
192
195
  const keysOfCall = (call) => {
193
- if (!keysByCall) {
194
- const found = new Map();
195
- let current;
196
- const silent = { info() { }, warn() { }, error() { } };
197
- const context = {
198
- addKey: ({ key }) => { found.set(current, [...(found.get(current) ?? []), key]); },
199
- config,
200
- logger: silent,
201
- getVarFromScope: () => undefined,
202
- setVarInScope: () => { },
203
- };
204
- const visitors = new astVisitors.ASTVisitors(config, context, silent, { onBeforeVisitNode: (node) => { current = node; } });
205
- visitors.setCurrentFile('', code);
206
- visitors.visit(ast);
207
- keysByCall = found;
208
- }
209
- return keysByCall.get(call) ?? [];
196
+ keysByCall ??= extractedKeysByNode(ast, code, config);
197
+ return (keysByCall.get(call) ?? []).map(({ key }) => key);
210
198
  };
211
199
  // Traverse AST for CallExpressions matching t() or i18n.t()
212
200
  function walk(node, ancestors) {
@@ -530,6 +518,178 @@ function lintConcatenation(ast, code, config) {
530
518
  walk(ast, null);
531
519
  return issues;
532
520
  }
521
+ // The keys the extractor resolves per node (a t() call, a <Trans> element): selector path, keyPrefix,
522
+ // namespace scope, context and plural forms included
523
+ function extractedKeysByNode(ast, code, config) {
524
+ const found = new Map();
525
+ let current;
526
+ const silent = { info() { }, warn() { }, error() { } };
527
+ const context = {
528
+ addKey: (key) => { found.set(current, [...(found.get(current) ?? []), key]); },
529
+ config,
530
+ logger: silent,
531
+ getVarFromScope: () => undefined,
532
+ setVarInScope: () => { },
533
+ };
534
+ const visitors = new astVisitors.ASTVisitors(config, context, silent, { onBeforeVisitNode: (node) => { current = node; } });
535
+ visitors.setCurrentFile('', code);
536
+ visitors.visit(ast);
537
+ return found;
538
+ }
539
+ // The children as the extractor counts them for the default value (swcChildrenToReactNodes in jsx-parser.ts):
540
+ // whitespace with a line break and {/* comments */} are no children, a {' '} is one
541
+ function transChildren(children) {
542
+ const result = [];
543
+ for (const child of children) {
544
+ if (child.type === 'JSXText') {
545
+ const text = jsxParser.trimTextNode(child.value);
546
+ if (text !== null)
547
+ result.push({ kind: 'text', text });
548
+ }
549
+ else if (child.type === 'JSXElement' || child.type === 'JSXFragment') {
550
+ const opening = child.type === 'JSXElement' ? child.opening : undefined;
551
+ result.push({
552
+ kind: 'element',
553
+ // only an HTML element (<p>) matches a kept HTML tag of the translation
554
+ name: opening?.name.type === 'Identifier' && /^[a-z]/.test(opening.name.value) ? opening.name.value : undefined,
555
+ children: transChildren(child.children),
556
+ dynamicList: !!opening?.attributes.some(a => a.type === 'JSXAttribute' && a.name.type === 'Identifier' && a.name.value === 'i18nIsDynamicList'),
557
+ });
558
+ }
559
+ else if (child.type === 'JSXExpressionContainer') {
560
+ let expr = child.expression;
561
+ while (expr.type === 'TsAsExpression' || expr.type === 'ParenthesisExpression')
562
+ expr = expr.expression;
563
+ if (expr.type === 'JSXEmptyExpression')
564
+ continue;
565
+ if (expr.type === 'StringLiteral')
566
+ result.push({ kind: 'text', text: expr.value });
567
+ else if (expr.type === 'TemplateLiteral' && astUtils.isSimpleTemplateLiteral(expr))
568
+ result.push({ kind: 'text', text: expr.quasis[0].raw });
569
+ else
570
+ result.push({ kind: 'other' });
571
+ }
572
+ else {
573
+ result.push({ kind: 'other' });
574
+ }
575
+ }
576
+ return result;
577
+ }
578
+ // The HTML elements React allows no children for
579
+ const voidElements = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
580
+ /**
581
+ * Resolves the tags of a translation against the <Trans> children like react-i18next's renderNodes and returns
582
+ * those that do not render what they wrap: a tag with content on a text child renders that text instead, a tag
583
+ * past the last child loses its markup, an empty tag drops the text of its element, and content on a `<br/>`
584
+ * makes React throw.
585
+ */
586
+ function transTagProblems(children, value, keep) {
587
+ const problems = [];
588
+ const walk = (scope, nodes, path) => {
589
+ // an expression as the only child ({items}) may be an array, which react-i18next indexes into
590
+ if (scope.length === 1 && scope[0].kind === 'other')
591
+ return;
592
+ const keptSeen = {};
593
+ for (const node of nodes) {
594
+ if (node.type !== 'tag')
595
+ continue;
596
+ const hasContent = node.children.length > 0;
597
+ const tag = `${path}<${node.name}${hasContent ? '' : '/'}>`;
598
+ if (/^\d+$/.test(node.name)) {
599
+ const child = scope[Number(node.name)];
600
+ if (!child) {
601
+ problems.push(`${tag} points past the last child (${scope.length} ${scope.length === 1 ? 'child' : 'children'}), so it renders without its markup`);
602
+ }
603
+ else if (child.kind === 'text') {
604
+ if (hasContent)
605
+ problems.push(`${tag} points to the text ${JSON.stringify(child.text)}, which replaces its content`);
606
+ }
607
+ else if (child.kind === 'element' && !child.dynamicList) {
608
+ if (hasContent && child.name && voidElements.has(child.name))
609
+ problems.push(`${tag} points to <${child.name}/>, which cannot have content (React throws)`);
610
+ else if (!hasContent && child.children.some(c => c.kind === 'text'))
611
+ problems.push(`${tag} is empty, so the element it points to renders without its text`);
612
+ else
613
+ walk(child.children, node.children, `${tag} > `);
614
+ }
615
+ }
616
+ else if (!node.voidElement) {
617
+ // a kept HTML tag (<p>, the only other tag parsed) opens the children of the n-th element of that
618
+ // name at its level (react-i18next#1919), or keeps the scope when there is none
619
+ const n = keptSeen[node.name] = (keptSeen[node.name] ?? -1) + 1;
620
+ const matched = scope.filter(c => c.kind === 'element' && c.name === node.name)[n];
621
+ walk(matched?.kind === 'element' ? matched.children : scope, node.children, `${tag} > `);
622
+ }
623
+ }
624
+ };
625
+ // parsed like react-i18next does: wrapped in <0>, only numbered and kept HTML tags are markup
626
+ const [root] = htmlParseStringify.parse(`<0>${value}</0>`, { allowedTags: (name) => /^\d+$/.test(name) || keep.includes(name) });
627
+ if (root?.type === 'tag')
628
+ walk(children, root.children, '');
629
+ return problems;
630
+ }
631
+ // The primary language's value of a key, from the file `extract` writes it to: one per namespace, or a merged one
632
+ function primaryValueLookup(config) {
633
+ const { output, mergeNamespaces } = config.extract;
634
+ const primary = config.extract.primaryLanguage || config.locales[0] || 'en';
635
+ const keySeparator = config.extract.keySeparator ?? '.';
636
+ const merged = mergeNamespaces || (typeof output === 'string' && !output.includes('{{namespace}}'));
637
+ const files = new Map();
638
+ return async (namespace, key) => {
639
+ const file = fileUtils.getOutputPath(output, primary, merged ? undefined : namespace);
640
+ // a file that does not parse makes `extract`, `sync` and `status` fail loudly, so `lint` skips it
641
+ if (!files.has(file))
642
+ files.set(file, fileUtils.loadTranslationFile(file).catch(() => null));
643
+ let resources = await files.get(file);
644
+ // a merged file holds one object per namespace, unless it is flat (the rule of translation-manager.ts)
645
+ const namespaced = config.extract.defaultNS !== false && config.extract.nsSeparator !== false &&
646
+ Object.values(resources ?? {}).some(v => typeof v === 'object' && v !== null && !Array.isArray(v));
647
+ if (merged && namespace && namespaced)
648
+ resources = resources?.[namespace];
649
+ return resources ? nestedObject.getNestedValue(resources, key, keySeparator) : undefined;
650
+ };
651
+ }
652
+ /**
653
+ * `lint.checkTransIndices`: the tags of the primary language's translations of every <Trans> with children,
654
+ * context and plural forms included, against those children. A <Trans> with `components` is skipped.
655
+ * ponytail: keys resolve per file like keysOfCall, without extract's cross-file pre-scan, so a namespace or
656
+ * keyPrefix from an imported constant reads the defaultNS file; one findKeys pass per run if that matters.
657
+ */
658
+ async function lintTransIndices(ast, code, config, primaryValue, severity) {
659
+ const transComponents = config.extract.transComponents || ['Trans'];
660
+ // ponytail: a file using react-i18next/icu.macro is skipped as a whole, its <Trans> compiles to `components`
661
+ if (!transComponents.some(name => code.includes(`<${name}`)) || code.includes('icu.macro'))
662
+ return [];
663
+ const keep = config.extract.transKeepBasicHtmlNodesFor ?? ['br', 'strong', 'i', 'p'];
664
+ const aliases = jsxAttributes.importAliases(ast);
665
+ const issues = [];
666
+ for (const [node, keys] of extractedKeysByNode(ast, code, config)) {
667
+ if (node?.type !== 'JSXElement' || !transComponents.includes(jsxAttributes.jsxElementName(node.opening.name, aliases) ?? ''))
668
+ continue;
669
+ if (node.opening.attributes.some((a) => a.type === 'JSXAttribute' && a.name?.value === 'components'))
670
+ continue;
671
+ const children = transChildren(node.children);
672
+ if (!children.length)
673
+ continue;
674
+ const line = astUtils.lineColumnFromOffset(code, node.span.start)?.line ?? 0;
675
+ const checked = new Set();
676
+ for (const { key, ns } of keys) {
677
+ // `defaultNS: false` writes the keys without a namespace
678
+ const namespace = ns === false ? undefined : ns || 'translation';
679
+ const label = namespace ? `${namespace}:${key}` : key;
680
+ if (checked.has(label))
681
+ continue;
682
+ checked.add(label);
683
+ const value = await primaryValue(namespace, key);
684
+ if (typeof value !== 'string')
685
+ continue;
686
+ for (const problem of transTagProblems(children, value, keep)) {
687
+ issues.push({ text: `${label}: ${problem}`, line, type: 'transIndex', severity });
688
+ }
689
+ }
690
+ }
691
+ return issues;
692
+ }
533
693
  const recommendedAcceptedTags = jsxAttributes.acceptedTags.map(s => s.toLowerCase());
534
694
  const recommendedAcceptedAttributes = jsxAttributes.translatableAttributes.map(s => s.toLowerCase());
535
695
  const defaultIgnoredAttributes = jsxAttributes.ignoredAttributeLowerSet;
@@ -577,6 +737,8 @@ class Linter extends node_events.EventEmitter {
577
737
  const translationValues = await loadPrimaryTranslationValues(config);
578
738
  const { messageFormat: messageFormat$1 } = config.extract;
579
739
  const analyze = messageFormat$1 === 'icu' || messageFormat$1 === 'mf2' ? await messageFormat.loadMessageAnalyzer(messageFormat$1) : undefined;
740
+ const transSetting = config.lint?.checkTransIndices;
741
+ const primaryValue = transSetting === false || transSetting === 'off' ? undefined : primaryValueLookup(config);
580
742
  const plugins = config.plugins || [];
581
743
  const lintPluginContext = this.createLintPluginContext(config);
582
744
  await this.initializeLintPlugins(plugins, lintPluginContext);
@@ -644,9 +806,10 @@ class Linter extends node_events.EventEmitter {
644
806
  }
645
807
  }
646
808
  // Normalise AST spans to file-relative character indices so the ignore
647
- // directive can resolve the line range of the JSX element it precedes.
809
+ // directive can resolve the line range of the JSX element it precedes,
810
+ // and lintTransIndices reports the line of a <Trans>.
648
811
  // (findHardcodedStrings/lintInterpolationParams locate issues via text
649
- // search and don't read spans, so this only affects ignore handling.)
812
+ // search and don't read spans.)
650
813
  try {
651
814
  astUtils.normalizeSpansToCharIndices(ast, code);
652
815
  }
@@ -660,7 +823,9 @@ class Linter extends node_events.EventEmitter {
660
823
  const interpolationIssues = lintInterpolationParams(ast, code, config, translationValues, analyze);
661
824
  // Collect string-concatenation issues
662
825
  const concatenationIssues = lintConcatenation(ast, code, config);
663
- let allIssues = [...hardcodedStrings, ...interpolationIssues, ...concatenationIssues];
826
+ // Collect <Trans> tags of the primary translation that miss their children
827
+ const transIndexIssues = primaryValue ? await lintTransIndices(ast, code, config, primaryValue, transSetting === 'error' ? 'error' : 'warning') : [];
828
+ let allIssues = [...hardcodedStrings, ...interpolationIssues, ...concatenationIssues, ...transIndexIssues];
664
829
  // Filter issues suppressed by ignore-directive comments.
665
830
  // i18next-instrument-ignore-next-line → suppresses the single next line
666
831
  // i18next-instrument-ignore → suppresses the whole next JSX element
@@ -861,7 +1026,9 @@ async function runLinterCli(config, options = {}) {
861
1026
  ? `${config.extract.messageFormat === 'mf2' ? 'MF2' : 'ICU'} message`
862
1027
  : type === 'placeholder'
863
1028
  ? 'Placeholder mismatch'
864
- : 'Found hardcoded string';
1029
+ : type === 'transIndex'
1030
+ ? '<Trans> tag'
1031
+ : 'Found hardcoded string';
865
1032
  const tag = severity === 'warning' ? node_util.styleText('yellow', 'Warning:') : node_util.styleText('red', 'Error:');
866
1033
  // line 0: a translation file whose format has no line lookup (YAML, JS)
867
1034
  const detail = ` ${line ? `${node_util.styleText('gray', `${line}:`)} ` : ''}${tag} ${label}: "${text}"`;
@@ -52,8 +52,11 @@ all commands.
52
52
  for future agent sessions.
53
53
  3. Instrument: run \`npx i18next-cli instrument --dry-run\` and review the
54
54
  planned changes; then \`npx i18next-cli instrument\` to apply. Inspect the
55
- git diff carefully: fix any t() wrapping inside Next.js *server components*
56
- (add 'use client' or refactor to a server-side t() pattern). Commit.
55
+ git diff carefully and the warnings it prints. In a Next.js app it writes
56
+ next-i18next's calls (await getT() in Server Components, useT() in Client
57
+ Components); texts it left (components that Server and Client Components
58
+ both render, texts outside components) are listed: move them or give the
59
+ component a t prop. If it printed next-i18next setup steps, do them. Commit.
57
60
  4. Extract: run \`npx i18next-cli extract\`. Verify the locale JSON files were
58
61
  written (check the extract.output path in the config). If the developer
59
62
  chose repository files only: translate the extracted keys yourself or
@@ -49,6 +49,7 @@ async function detectStack(findInitFile) {
49
49
  initFile: await findInitFile(),
50
50
  hasAppRouter,
51
51
  hasParaglide,
52
+ usesNextI18next: framework === 'next' && (has('next-i18next') || !(has('i18next') || has('react-i18next'))),
52
53
  };
53
54
  }
54
55
  /** File extensions associated with frameworks the instrumenter cannot transform natively. */
@@ -140,12 +140,33 @@ function printCompleteness(completeness) {
140
140
  console.log(node_util.styleText(color, ` ${locale}: ${translated}/${total} (${pct}%)`));
141
141
  }
142
142
  }
143
- function printEpilogue(config) {
143
+ function printEpilogue(config, nextApp = false) {
144
144
  const projectId = config.locize?.projectId || '<your-project-id>';
145
145
  console.log(node_util.styleText('green', '\n✅ Done. Your app is localized.'));
146
146
  console.log(node_util.styleText('cyan', '\nYour AI translations come with confidence scores; low-confidence ones are flagged for review in Locize.'));
147
147
  console.log('\nOptional — switch to CDN delivery so translation fixes go live without redeploying your app:');
148
148
  console.log(node_util.styleText('cyan', ' npm install i18next-locize-backend'));
149
+ if (nextApp) {
150
+ // next-i18next takes the backend in its config (and, for the browser, in I18nProvider's `use`: see the docs)
151
+ console.log(node_util.styleText('gray', `
152
+ // in your next-i18next config (i18n.config):
153
+ import LocizeBackend from 'i18next-locize-backend'
154
+
155
+ export default defineConfig({
156
+ // ...
157
+ use: [LocizeBackend],
158
+ i18nextOptions: {
159
+ backend: {
160
+ projectId: '${projectId}',
161
+ version: 'latest', // no apiKey in production!
162
+ },
163
+ },
164
+ })
165
+ `));
166
+ console.log('Docs: https://github.com/i18next/next-i18next#i18next-locize-backend');
167
+ console.log('Your current setup (local translation files) keeps working either way; run `i18next-cli locize-download` in CI to refresh the files.');
168
+ return;
169
+ }
149
170
  console.log(node_util.styleText('gray', `
150
171
  // in your i18n init file:
151
172
  import LocizeBackend from 'i18next-locize-backend'
@@ -270,8 +291,8 @@ async function runLocalize(options = {}, configPath) {
270
291
  if (!proceed)
271
292
  skipInstrument = true;
272
293
  }
273
- if (stack.hasAppRouter) {
274
- warn("Next.js App Router detected: instrument injects useTranslation(), which is client-only. Review the diff for server components — add 'use client' or switch those to a server-side t() pattern.");
294
+ if (stack.usesNextI18next) {
295
+ warn('Next.js: instrument writes next-i18next calls, await getT() in Server Components and useT() in Client Components. Review the diff and the texts it lists as left.');
275
296
  }
276
297
  if (!skipInstrument) {
277
298
  const results = await instrumenter.runInstrumenter(config$1, {
@@ -472,7 +493,7 @@ async function runLocalize(options = {}, configPath) {
472
493
  else if (completeness.length > 0) {
473
494
  ok('All languages translated and downloaded.');
474
495
  }
475
- printEpilogue(config$1);
496
+ printEpilogue(config$1, stack.usesNextI18next);
476
497
  }
477
498
 
478
499
  exports.runLocalize = runLocalize;