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