i18next-cli 1.89.0 → 1.90.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 (44) hide show
  1. package/README.md +46 -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/heuristic-config.js +51 -6
  6. package/dist/cjs/init.js +5 -0
  7. package/dist/cjs/instrumenter/core/instrumenter.js +272 -23
  8. package/dist/cjs/instrumenter/core/key-generator.js +1 -0
  9. package/dist/cjs/instrumenter/core/next-files.js +104 -0
  10. package/dist/cjs/instrumenter/core/transformer.js +97 -73
  11. package/dist/cjs/localize/agent-prompt.js +5 -2
  12. package/dist/cjs/localize/detect.js +1 -0
  13. package/dist/cjs/localize/localize.js +25 -4
  14. package/dist/esm/cli.js +8 -4
  15. package/dist/esm/config.js +13 -12
  16. package/dist/esm/extractor/core/extractor.js +1 -3
  17. package/dist/esm/heuristic-config.js +52 -7
  18. package/dist/esm/init.js +5 -0
  19. package/dist/esm/instrumenter/core/instrumenter.js +273 -24
  20. package/dist/esm/instrumenter/core/key-generator.js +1 -0
  21. package/dist/esm/instrumenter/core/next-files.js +101 -0
  22. package/dist/esm/instrumenter/core/transformer.js +97 -73
  23. package/dist/esm/localize/agent-prompt.js +5 -2
  24. package/dist/esm/localize/detect.js +1 -0
  25. package/dist/esm/localize/localize.js +25 -4
  26. package/package.json +1 -1
  27. package/types/cli.d.ts.map +1 -1
  28. package/types/config.d.ts.map +1 -1
  29. package/types/extractor/core/extractor.d.ts.map +1 -1
  30. package/types/heuristic-config.d.ts.map +1 -1
  31. package/types/init.d.ts.map +1 -1
  32. package/types/instrumenter/core/instrumenter.d.ts.map +1 -1
  33. package/types/instrumenter/core/key-generator.d.ts.map +1 -1
  34. package/types/instrumenter/core/next-files.d.ts +25 -0
  35. package/types/instrumenter/core/next-files.d.ts.map +1 -0
  36. package/types/instrumenter/core/transformer.d.ts +6 -0
  37. package/types/instrumenter/core/transformer.d.ts.map +1 -1
  38. package/types/localize/agent-prompt.d.ts +1 -1
  39. package/types/localize/agent-prompt.d.ts.map +1 -1
  40. package/types/localize/detect.d.ts +2 -0
  41. package/types/localize/detect.d.ts.map +1 -1
  42. package/types/localize/localize.d.ts.map +1 -1
  43. package/types/types.d.ts +39 -0
  44. package/types/types.d.ts.map +1 -1
@@ -16,6 +16,7 @@ var astUtils = require('../../extractor/parsers/ast-utils.js');
16
16
  var fileUtils = require('../../utils/file-utils.js');
17
17
  var keyFinder = require('../../extractor/core/key-finder.js');
18
18
  var functionMatcher = require('../../extractor/utils/function-matcher.js');
19
+ var nextFiles = require('./next-files.js');
19
20
  var messageFormat = require('../../utils/message-format.js');
20
21
 
21
22
  /**
@@ -67,6 +68,20 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
67
68
  // Detect framework and language
68
69
  const hasReact = await isProjectUsingReact();
69
70
  const hasTypeScript = await isProjectUsingTypeScript();
71
+ // A Next.js app gets next-i18next's calls: getT() in Server Components, useT() in Client Components,
72
+ // useTranslation() from next-i18next/pages in the Pages Router. Also one with i18next not set up at all,
73
+ // whose Server Components no plain react-i18next hook would work in; one with an i18next setup of its own
74
+ // keeps it.
75
+ const contents = new Map();
76
+ for (const file of sourceFiles)
77
+ contents.set(file, await promises.readFile(file, 'utf-8'));
78
+ const deps = await fileUtils.readProjectDeps();
79
+ const code = [...contents.values()];
80
+ const nextI18next = !!deps['next-i18next'] || code.some(c => NEXT_I18NEXT_IMPORT_RE.test(c)) ||
81
+ (!!deps.next && !deps.i18next && !deps['react-i18next'] && !code.some(c => I18NEXT_IMPORT_RE.test(c)));
82
+ const nextFiles$1 = nextI18next ? await nextFiles.classifyNextFiles(contents) : undefined;
83
+ const nextKinds = nextFiles$1?.kinds;
84
+ const serverModule = nextI18next ? findServerModule(contents) : undefined;
70
85
  // Initialize plugins
71
86
  const plugins = config.plugins || [];
72
87
  await initializeInstrumentPlugins(plugins, { config, logger: logger$1 });
@@ -88,14 +103,15 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
88
103
  }
89
104
  for (const file of sourceFiles) {
90
105
  try {
91
- let content = await promises.readFile(file, 'utf-8');
106
+ let content = contents.get(file);
92
107
  // Run instrumentOnLoad plugin pipeline
93
108
  const loadResult = await runInstrumentOnLoadPipeline(content, file, plugins, logger$1);
94
109
  if (loadResult === null)
95
110
  continue; // plugin says skip this file
96
111
  content = loadResult;
97
- i18nextInUse ||= I18NEXT_IMPORT_RE.test(content);
98
- const scanResult = await scanFileForCandidates(content, file, config);
112
+ i18nextInUse ||= I18NEXT_IMPORT_RE.test(content) || NEXT_I18NEXT_IMPORT_RE.test(content);
113
+ const nextKind = nextKinds?.get(file);
114
+ const scanResult = await scanFileForCandidates(content, file, config, nextKind);
99
115
  let { candidates } = scanResult;
100
116
  const { components, languageChangeSites, imports, memoHooks, pluralHelperImports } = scanResult;
101
117
  // Run instrumentOnResult plugin pipeline
@@ -105,6 +121,11 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
105
121
  totalSkipped += scanResult.ownTSkipped;
106
122
  warnFor(`${file} (${scanResult.ownTSkipped})`, 'Skipped the texts of components that declare a `t` of their own (not a translation function): rename it, then run instrument again.');
107
123
  }
124
+ for (const { message, count, lines } of scanResult.dropped ?? []) {
125
+ totalCandidates += count;
126
+ totalSkipped += count;
127
+ warnFor(lines ? lines.map(line => `${file}:${line}`).join(', ') : `${file} (${count})`, message);
128
+ }
108
129
  if (scanResult.moduleScopeSkipped > 0) {
109
130
  totalCandidates += scanResult.moduleScopeSkipped;
110
131
  totalSkipped += scanResult.moduleScopeSkipped;
@@ -191,7 +212,8 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
191
212
  languageChangeSites,
192
213
  imports,
193
214
  memoHooks,
194
- pluralHelperImports
215
+ pluralHelperImports,
216
+ next: nextKind && { kind: nextKind, serverModule: serverModuleFor(serverModule, file) }
195
217
  });
196
218
  if (!options.isDryRun && transformResult.modified) {
197
219
  // Write the transformed file
@@ -230,11 +252,29 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
230
252
  const head = message === MODULE_SCOPE_WARNING ? `Skipped ${moduleScopeTotal} module-scope string(s). ${message}` : message;
231
253
  logger$1.warn(`${head}\n${where.map(w => ` ${w}`).join('\n')}`);
232
254
  }
255
+ if (nextI18next && totalTransformed > 0) {
256
+ // next-i18next sets i18next up itself (its config, the proxy, the root layout or appWithTranslation)
257
+ // a page loads its namespaces itself, with serverSideTranslations() (or a helper it imports that calls it)
258
+ const loads = (file) => [file, ...nextFiles$1.imports.get(file) ?? []].some(f => contents.get(f).includes('serverSideTranslations'));
259
+ const pagesWithoutProps = results.filter(r => nextKinds?.get(r.file) === 'pages' && isPagesRoute(r.file) && !loads(r.file)).map(r => r.file);
260
+ if (pagesWithoutProps.length) {
261
+ logger$1.warn(`These pages need serverSideTranslations() in getStaticProps or getServerSideProps, or their texts render untranslated (https://github.com/i18next/next-i18next#pages-router-setup):\n${pagesWithoutProps.map(f => ` ${f}`).join('\n')}`);
262
+ }
263
+ if (!i18nextInUse && !await nextI18nextConfigured()) {
264
+ const kinds = new Set(results.map(r => nextKinds?.get(r.file)));
265
+ logger$1.info([
266
+ 'The code now uses next-i18next. Set it up:',
267
+ ` npm install next-i18next i18next react-i18next${config.extract.messageFormat === 'icu' ? ' i18next-icu intl-messageformat' : config.extract.messageFormat === 'mf2' ? ' i18next-mf2' : ''}`,
268
+ ...(kinds.has('server') || kinds.has('client') ? [' App Router: i18n.config, proxy and root layout, https://github.com/i18next/next-i18next#app-router-setup (no [lng] folder: localeInPath: false)'] : []),
269
+ ...(kinds.has('pages') ? [' Pages Router: next-i18next.config.js, appWithTranslation and serverSideTranslations, https://github.com/i18next/next-i18next#pages-router-setup'] : [])
270
+ ].join('\n'));
271
+ }
272
+ }
233
273
  // Generate i18n init file if needed and any transformations were made
234
- if ((totalTransformed > 0 || totalLanguageChanges > 0) && !options.isDryRun && i18nextInUse) {
274
+ if ((totalTransformed > 0 || totalLanguageChanges > 0) && !options.isDryRun && !nextI18next && i18nextInUse) {
235
275
  logger$1.info('Your code imports i18next already, so it is set up somewhere: no i18n init file generated.');
236
276
  }
237
- if ((totalTransformed > 0 || totalLanguageChanges > 0) && !options.isDryRun && !i18nextInUse) {
277
+ if ((totalTransformed > 0 || totalLanguageChanges > 0) && !options.isDryRun && !nextI18next && !i18nextInUse) {
238
278
  const initFilePath = await ensureI18nInitFile(hasReact, hasTypeScript, config, logger$1, usesI18nextT);
239
279
  if (initFilePath) {
240
280
  await injectI18nImportIntoEntryFile(initFilePath, logger$1);
@@ -259,6 +299,45 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
259
299
  function keySourceOf(candidate) {
260
300
  return candidate.transValue?.replace(/<\/?\d+>/g, '') ?? candidate.content;
261
301
  }
302
+ /** An import of next-i18next, which sets i18next up itself. */
303
+ const NEXT_I18NEXT_IMPORT_RE = /\bfrom\s*['"]next-i18next(?:\/[\w/]+)?['"]|\brequire\(\s*['"]next-i18next(?:\/[\w/]+)?['"]\s*\)/;
304
+ /**
305
+ * The module the app imports `getT` from when it is not `next-i18next/server` (`createServerI18next` in its
306
+ * own `i18n.server.ts`, so no init order matters): an alias as written, a relative one as an absolute path.
307
+ */
308
+ function findServerModule(contents) {
309
+ for (const [file, code] of contents) {
310
+ for (const [, names, source] of code.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
311
+ if (!/\bgetT\b/.test(names) || source === 'next-i18next/server')
312
+ continue;
313
+ return source.startsWith('.') ? node_path.resolve(node_path.dirname(file), source) : source;
314
+ }
315
+ }
316
+ return undefined;
317
+ }
318
+ /** The specifier a file imports `getT` with: `next-i18next/server`, the app's alias, or a path relative to it. */
319
+ function serverModuleFor(serverModule, file) {
320
+ if (!serverModule)
321
+ return 'next-i18next/server';
322
+ if (!node_path.isAbsolute(serverModule))
323
+ return serverModule;
324
+ const rel = node_path.relative(node_path.dirname(node_path.resolve(file)), serverModule).replace(/\\/g, '/').replace(/\.(?:tsx?|jsx?|mjs)$/, '');
325
+ return rel.startsWith('.') ? rel : `./${rel}`;
326
+ }
327
+ /** A page of the Pages Router (not `_app`, `_document`, `_error` or an API route), which loads its own translations. */
328
+ function isPagesRoute(file) {
329
+ const rel = nextFiles.projectPath(file);
330
+ return rel.startsWith('pages/') && !/^pages\/(?:_app|_document|_error|api\/)/.test(rel);
331
+ }
332
+ /** next-i18next has a config of its own already: `i18n.config.*` (App Router) or `next-i18next.config.*` (Pages Router). */
333
+ async function nextI18nextConfigured() {
334
+ const names = ['i18n.config', 'next-i18next.config'].flatMap(name => ['ts', 'js', 'mjs', 'cjs'].map(ext => `${name}.${ext}`));
335
+ for (const name of names) {
336
+ if (await fileExists(node_path.join(process.cwd(), name)) || await fileExists(node_path.join(process.cwd(), 'src', name)))
337
+ return true;
338
+ }
339
+ return false;
340
+ }
262
341
  /** An import of i18next or react-i18next (`.init()` alone is any library's: `Sentry.init()`). */
263
342
  const I18NEXT_IMPORT_RE = /\bfrom\s*['"](?:i18next|react-i18next)['"]|\brequire\(\s*['"](?:i18next|react-i18next)['"]\s*\)/;
264
343
  const MODULE_SCOPE_WARNING = 'A t() call there runs once at import time — before i18next may be initialized — and never updates on language change. ' +
@@ -267,7 +346,7 @@ const MODULE_SCOPE_WARNING = 'A t() call there runs once at import time — befo
267
346
  /**
268
347
  * Scans a source file for hardcoded string candidates and React component boundaries.
269
348
  */
270
- async function scanFileForCandidates(content, file, config) {
349
+ async function scanFileForCandidates(content, file, config, nextKind) {
271
350
  const candidates = [];
272
351
  const components = [];
273
352
  const languageChangeSites = [];
@@ -276,6 +355,7 @@ async function scanFileForCandidates(content, file, config) {
276
355
  let imports;
277
356
  const memoHooks = [];
278
357
  let pluralHelperImports;
358
+ const dropped = [];
279
359
  const fileExt = node_path.extname(file).toLowerCase();
280
360
  const isTypeScriptFile = ['.ts', '.tsx', '.mts', '.cts'].includes(fileExt);
281
361
  const isTSX = fileExt === '.tsx';
@@ -333,10 +413,18 @@ async function scanFileForCandidates(content, file, config) {
333
413
  }));
334
414
  collectMemoHooks(ast, memoHooks);
335
415
  // Detect React function component boundaries
336
- detectComponentBoundaries(ast, content, components);
416
+ detectComponentBoundaries(ast, content, components, nextKind === 'server');
337
417
  // Collect function spans so module-scope strings can be excluded below
338
418
  const functionSpans = [];
339
419
  collectFunctionSpans(ast, functionSpans);
420
+ // Next.js reads the texts of `export const metadata` once; generateMetadata() can get them with getT()
421
+ if (nextKind === 'server' && !/\bgenerateMetadata\b/.test(content)) {
422
+ const metadata = metadataExport(ast, content);
423
+ if (metadata) {
424
+ components.push(metadata);
425
+ functionSpans.push({ start: metadata.bodyStart, end: metadata.bodyEnd });
426
+ }
427
+ }
340
428
  // Visit AST to find string literals; the object form of extract.acceptedAttributes
341
429
  // sets which attributes hold text per JSX element
342
430
  const attributeRules = config.extract.acceptedAttributes;
@@ -386,6 +474,15 @@ async function scanFileForCandidates(content, file, config) {
386
474
  candidates.length = 0;
387
475
  candidates.push(...keep);
388
476
  }
477
+ if (nextKind) {
478
+ dropped.push(...dropForNextI18next(candidates, components, nextKind, isApiRoute(file), serverDirectiveSpans(ast)));
479
+ // next-i18next switches the language through the route or useChangeLanguage(): `i18n.changeLanguage()`
480
+ // would change the client instance alone. A call of that switch is no site at all.
481
+ const sites = languageChangeSites.filter(site => !/^(?:\w+\.)?changeLanguage\(/.test(content.slice(site.callStart, site.callEnd)));
482
+ if (sites.length)
483
+ dropped.push({ message: NEXT_LANGUAGE_CHANGE, count: sites.length, lines: sites.map(site => site.line) });
484
+ languageChangeSites.length = 0;
485
+ }
389
486
  // Annotate language change sites with their enclosing component (if any)
390
487
  for (const site of languageChangeSites) {
391
488
  for (const comp of components) {
@@ -435,7 +532,111 @@ async function scanFileForCandidates(content, file, config) {
435
532
  catch (err) {
436
533
  // Silently skip files that can't be parsed
437
534
  }
438
- return { candidates, components, languageChangeSites, moduleScopeSkipped, ownTSkipped, imports, memoHooks, pluralHelperImports };
535
+ return { candidates, components, languageChangeSites, moduleScopeSkipped, ownTSkipped, imports, memoHooks, pluralHelperImports, dropped };
536
+ }
537
+ /** `export const metadata = { title: '…' }` (with or without a type) as the scope of a generateMetadata() to be. */
538
+ function metadataExport(ast, content) {
539
+ for (const item of ast.body ?? []) {
540
+ const decl = item.type === 'ExportDeclaration' ? item.declaration : null;
541
+ const [declarator] = decl?.type === 'VariableDeclaration' && decl.declarations?.length === 1 ? decl.declarations : [];
542
+ if (declarator?.id?.value !== 'metadata' || declarator.init?.type !== 'ObjectExpression')
543
+ continue;
544
+ const annotation = declarator.id.typeAnnotation?.typeAnnotation;
545
+ return {
546
+ name: `metadata@${declarator.init.span.start}`,
547
+ bodyStart: declarator.init.span.start,
548
+ bodyEnd: declarator.init.span.end,
549
+ hasUseTranslation: false,
550
+ expressionBody: true,
551
+ isAsync: true,
552
+ metadataHead: {
553
+ start: decl.span.start,
554
+ end: declarator.init.span.start,
555
+ type: annotation?.span ? content.slice(annotation.span.start, annotation.span.end) : undefined
556
+ }
557
+ };
558
+ }
559
+ return null;
560
+ }
561
+ /** A route handler (`route.ts` under `app/`, a file under `pages/api/`): its texts are responses of an API, not of a page. */
562
+ function isApiRoute(file) {
563
+ const rel = nextFiles.projectPath(file);
564
+ return /^app\/(?:.*\/)?route\.[cm]?[jt]sx?$/.test(rel) || rel.startsWith('pages/api/');
565
+ }
566
+ /**
567
+ * The functions that run as Server Actions or cached (`'use server'`, `'use cache'` as their first statement), all
568
+ * of the file for such a directive at its top: they have no root params, so getT() there needs `{ lng }` passed in.
569
+ */
570
+ function serverDirectiveSpans(ast) {
571
+ const directive = (stmts) => stmts.some((st) => st.type === 'ExpressionStatement' &&
572
+ st.expression?.type === 'StringLiteral' && /^use (?:server|cache)\b/.test(st.expression.value));
573
+ // the directive prologue: the string statements a body or module starts with
574
+ const leading = (stmts = []) => {
575
+ const end = stmts.findIndex((st) => st.type !== 'ExpressionStatement' || st.expression?.type !== 'StringLiteral');
576
+ return end < 0 ? stmts : stmts.slice(0, end);
577
+ };
578
+ if (directive(leading(ast.body)))
579
+ return [{ start: 0, end: Infinity }];
580
+ const spans = [];
581
+ const walk = (node) => {
582
+ if (!node || typeof node !== 'object')
583
+ return;
584
+ if (FUNCTION_LIKE.has(node.type) && isBlockBody(node.body) && directive(leading(node.body.stmts))) {
585
+ spans.push({ start: node.body.span.start, end: node.body.span.end });
586
+ return;
587
+ }
588
+ for (const key in node) {
589
+ const value = node[key];
590
+ if (Array.isArray(value))
591
+ value.forEach(walk);
592
+ else if (value && typeof value === 'object' && key !== 'span')
593
+ walk(value);
594
+ }
595
+ };
596
+ walk(ast);
597
+ return spans;
598
+ }
599
+ const NEXT_API = 'Left API routes as they are: their texts are responses, not pages (getT() there needs { lng } from the request).';
600
+ const NEXT_DIRECTIVE = "Left Server Actions and cached functions ('use server', 'use cache') as they are: getT() there needs { lng } passed in.";
601
+ const NEXT_UNKNOWN = "Skipped the texts of files that no page or layout imports (as far as the imports resolve), so it is not known whether Server or Client Components render them: add 'use client' to a Client Component, then run instrument again.";
602
+ const NEXT_OUTSIDE = 'Skipped texts outside components: next-i18next has no global t(). Move them into a component (or, in a Server Component file, an async function), then run instrument again.';
603
+ const NEXT_SHARED = 'Skipped the texts of components that Server and Client Components both render, where neither getT() nor a hook works: give them a `t` prop (from getT() or useT() in the callers), then run instrument again.';
604
+ const NEXT_WRAPPED = 'Skipped the texts of Server Components wrapped in a call (memo, forwardRef), which cannot become async for getT().';
605
+ const NEXT_LANGUAGE_CHANGE = 'Language switches left as they are: next-i18next changes the language through the route (/de/…) or useChangeLanguage() from next-i18next/client. Wire these by hand.';
606
+ /**
607
+ * Takes out the candidates next-i18next cannot translate where they are: outside a component (no global `t`), in
608
+ * a component rendered on both sides without a `t` prop, a <Trans> there, in a Server Component that cannot
609
+ * become async. Returns what it dropped, by reason.
610
+ */
611
+ function dropForNextI18next(candidates, components, kind, apiRoute, directiveSpans) {
612
+ const componentOf = (c) => components.find(comp => comp.name === c.insideComponent);
613
+ const reasonOf = (c) => {
614
+ if (apiRoute)
615
+ return NEXT_API;
616
+ if (directiveSpans.some(span => c.offset >= span.start && c.endOffset <= span.end))
617
+ return NEXT_DIRECTIVE;
618
+ const comp = componentOf(c);
619
+ // a <Trans> takes its `t` from the React context, in any render code of a Client Component
620
+ if (!comp)
621
+ return c.type === 'jsx-mixed' && (kind === 'client' || kind === 'pages') ? null : NEXT_OUTSIDE;
622
+ // with `t` and `i18n` props, a <Trans> takes them both and works on either side
623
+ if ((kind === 'shared' || kind === 'unknown') && (!comp.hasUseTranslation || (c.type === 'jsx-mixed' && !comp.i18nParam))) {
624
+ return kind === 'shared' ? NEXT_SHARED : NEXT_UNKNOWN;
625
+ }
626
+ if (kind === 'server' && comp.wrapped && !comp.hasUseTranslation)
627
+ return NEXT_WRAPPED;
628
+ return null;
629
+ };
630
+ const counts = new Map();
631
+ const keep = candidates.filter(c => {
632
+ const reason = reasonOf(c);
633
+ if (reason)
634
+ counts.set(reason, (counts.get(reason) ?? 0) + 1);
635
+ return !reason;
636
+ });
637
+ candidates.length = 0;
638
+ candidates.push(...keep);
639
+ return [...counts].map(([message, count]) => ({ message, count }));
439
640
  }
440
641
  /**
441
642
  * Node types whose span delimits deferred (call-time) evaluation. A string
@@ -498,7 +699,7 @@ function lineOfOffset(content, offset) {
498
699
  * - forwardRef wrappers: `const Greeting = React.forwardRef((props, ref) => { ... })`
499
700
  * - memo wrappers: `const Greeting = React.memo(() => { ... })`
500
701
  */
501
- function detectComponentBoundaries(node, content, components) {
702
+ function detectComponentBoundaries(node, content, components, serverFile = false) {
502
703
  if (!node)
503
704
  return;
504
705
  // FunctionDeclaration with uppercase name
@@ -509,7 +710,8 @@ function detectComponentBoundaries(node, content, components) {
509
710
  name: node.identifier.value,
510
711
  bodyStart: body.span.start,
511
712
  bodyEnd: body.span.end,
512
- ...tBinding(node, body)
713
+ ...tBinding(node, body),
714
+ ...functionFacts(node)
513
715
  });
514
716
  }
515
717
  }
@@ -527,7 +729,8 @@ function detectComponentBoundaries(node, content, components) {
527
729
  name: node.identifier.value,
528
730
  bodyStart: body.span.start,
529
731
  bodyEnd: body.span.end,
530
- ...tBinding(node, body)
732
+ ...tBinding(node, body),
733
+ ...functionFacts(node)
531
734
  });
532
735
  }
533
736
  }
@@ -553,25 +756,59 @@ function detectComponentBoundaries(node, content, components) {
553
756
  if (isWrapper && init.arguments?.length > 0) {
554
757
  const arg = init.arguments[0]?.expression || init.arguments[0];
555
758
  if (arg && (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression')) {
556
- addComponentFromFunctionNode(node.id.value, arg, content, components);
759
+ addComponentFromFunctionNode(node.id.value, arg, content, components, true);
557
760
  }
558
761
  }
559
762
  }
560
763
  }
561
764
  }
765
+ // Not a component, but a function with a `t` of its own (`const { t } = await getT()` in `generateMetadata`,
766
+ // a custom hook), or in a Server Component file one that can await getT(): an async one, or the metadata
767
+ // functions Next.js awaits
768
+ if (FUNCTION_LIKE.has(node.type) && node.body?.span && !components.some(c => c.bodyStart === node.body.span.start)) {
769
+ const name = node.identifier?.value;
770
+ const ownHook = isBlockBody(node.body) && bindsT({}, node.body) === 'translation';
771
+ if (ownHook || (serverFile && (node.async || /^generate(?:Metadata|Viewport)$/.test(name ?? '')))) {
772
+ addComponentFromFunctionNode(`${name ?? 'function'}@${node.body.span.start}`, node, content, components, false, true);
773
+ }
774
+ }
562
775
  // Recurse into children
563
776
  for (const key in node) {
564
777
  const value = node[key];
565
778
  if (value && typeof value === 'object') {
566
779
  if (Array.isArray(value)) {
567
- value.forEach(item => detectComponentBoundaries(item, content, components));
780
+ value.forEach(item => detectComponentBoundaries(item, content, components, serverFile));
568
781
  }
569
782
  else {
570
- detectComponentBoundaries(value, content, components);
783
+ detectComponentBoundaries(value, content, components, serverFile);
571
784
  }
572
785
  }
573
786
  }
574
787
  }
788
+ const FUNCTION_LIKE = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
789
+ /** Where a function starts, whether it is async, and the translation hook it calls without taking `t`. */
790
+ function functionFacts(fnNode, wrapped = false) {
791
+ const facts = { start: fnNode.span?.start, isAsync: !!fnNode.async };
792
+ if (wrapped)
793
+ facts.wrapped = true;
794
+ if ((fnNode.params ?? []).some((p) => patternBinds(p, 'i18n')))
795
+ facts.i18nParam = true;
796
+ const returnType = fnNode.returnType?.typeAnnotation?.span;
797
+ if (returnType)
798
+ facts.returnType = { start: returnType.start, end: returnType.end };
799
+ for (const stmt of isBlockBody(fnNode.body) ? fnNode.body.stmts ?? [] : []) {
800
+ for (const d of stmt.type === 'VariableDeclaration' ? stmt.declarations ?? [] : []) {
801
+ const call = d.init?.type === 'AwaitExpression' ? d.init.argument : d.init;
802
+ const hook = call?.type === 'CallExpression' ? dottedName(call.callee)?.split('.').pop() : null;
803
+ const props = d.id?.type === 'ObjectPattern' ? d.id.properties ?? [] : [];
804
+ if (!hook || !HOOK_CALL_RE.test(hook) || !props.length || props.some((p) => p.type === 'RestElement'))
805
+ continue;
806
+ facts.hookPattern = { statement: stmt.span.start, first: props[0].span.start, last: props[props.length - 1].span.end, names: props.map((p) => p.key?.value).filter(Boolean) };
807
+ return facts;
808
+ }
809
+ }
810
+ return facts;
811
+ }
575
812
  /**
576
813
  * swc >=1.16 types function bodies as 'FunctionBody'; older versions used 'BlockStatement'.
577
814
  */
@@ -582,23 +819,26 @@ function isBlockBody(body) {
582
819
  * Helper: extracts a ComponentBoundary from an ArrowFunctionExpression or FunctionExpression
583
820
  * that has a block body.
584
821
  */
585
- function addComponentFromFunctionNode(name, fnNode, content, components) {
822
+ function addComponentFromFunctionNode(name, fnNode, content, components, wrapped = false, anyExpressionBody = false) {
586
823
  const body = fnNode.body;
587
824
  if (isBlockBody(body) && body.span) {
588
825
  components.push({
589
826
  name,
590
827
  bodyStart: body.span.start,
591
828
  bodyEnd: body.span.end,
592
- ...tBinding(fnNode, body)
829
+ ...tBinding(fnNode, body),
830
+ ...functionFacts(fnNode, wrapped)
593
831
  });
594
832
  }
595
- else if (isJSXExpression(body) && body.span) {
833
+ else if ((isJSXExpression(body) || anyExpressionBody) && body?.span) {
596
834
  // `const Hint = () => <p>…</p>`: a component too; its body becomes a block when it needs the hook
835
+ // (as does `async () => ({ title: … })`, a server function)
597
836
  components.push({
598
837
  name,
599
838
  bodyStart: body.span.start,
600
839
  bodyEnd: body.span.end,
601
840
  ...tBinding(fnNode, {}),
841
+ ...functionFacts(fnNode, wrapped),
602
842
  expressionBody: true
603
843
  });
604
844
  }
@@ -627,11 +867,16 @@ function bindsT(fnNode, body) {
627
867
  continue;
628
868
  const call = d.init?.type === 'AwaitExpression' ? d.init.argument : d.init;
629
869
  const hook = call?.type === 'CallExpression' ? dottedName(call.callee)?.split('.').pop() : null;
870
+ // `const t = i18n.getFixedT(lng, 'footer')` is one too
871
+ if (d.id.type === 'Identifier' && hook === 'getFixedT')
872
+ return 'translation';
630
873
  return d.id.type === 'ObjectPattern' && hook && TRANSLATION_HOOK_RE.test(hook) ? 'translation' : 'other';
631
874
  }
632
875
  }
633
876
  return null;
634
877
  }
878
+ /** The translation hooks a call to which can take `t` as well; an app's own `useRoleTranslations()` returns data. */
879
+ const HOOK_CALL_RE = /^(?:useTranslation|useT|getT)$/;
635
880
  /** Names of the hooks and functions that give a translation `t`. */
636
881
  const TRANSLATION_HOOK_RE = /^(?:use|get)\w*(?:Translation|T|I18n|Intl)\w*$/;
637
882
  /** A component's `hasUseTranslation`, and `ownT` when its `t` is something else (see `bindsT`). */
@@ -1219,7 +1464,8 @@ function hasWordsBesidePlaceholders(text) {
1219
1464
  if (/^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(bare.replace(/\uE000/g, ' ').trim()))
1220
1465
  return false;
1221
1466
  return bare.split(/\s+/).some(token => {
1222
- const word = /^[^\p{L}\p{N}\uE000_.-]*(\p{L}{2,}(?:['’-]\p{L}+)*)[^\p{L}\p{N}_]*$/u.exec(token)?.[1];
1467
+ // (a name with digits in a later part counts: `next-i18next v{{version}}`)
1468
+ const word = /^[^\p{L}\p{N}\uE000_.-]*(\p{L}{2,}(?:['’-]\p{N}*\p{L}[\p{L}\p{N}]*)*)[^\p{L}\p{N}_]*$/u.exec(token)?.[1];
1223
1469
  // `zh-{{country}}`, `{{a}}/{{b}}`: a placeholder joined to the word by a separator makes an id, not a phrase
1224
1470
  if (/[-_./:#@=&?|\\]\uE000/.test(token))
1225
1471
  return false;
@@ -1667,10 +1913,11 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
1667
1913
  // Recurse into children
1668
1914
  forEachChild(node, parts, child => detectJSXInterpolation(child, content, file, config, candidates));
1669
1915
  }
1670
- /** A run without the whitespace-only text and `{' '}` pieces at its two ends. */
1916
+ /** A run without the whitespace-only text, `{' '}` pieces and empty elements (`<hr />`, `<br />`) at its two ends. */
1671
1917
  function trimRun(run) {
1672
1918
  const blank = (c) => (c.type === 'JSXText' && !c.value?.trim()) ||
1673
- (c.type === 'JSXExpressionContainer' && c.expression?.type === 'StringLiteral' && !c.expression.value.trim());
1919
+ (c.type === 'JSXExpressionContainer' && c.expression?.type === 'StringLiteral' && !c.expression.value.trim()) ||
1920
+ (c.type === 'JSXElement' && !c.children?.length);
1674
1921
  let start = 0;
1675
1922
  let end = run.length;
1676
1923
  while (start < end && blank(run[start]))
@@ -1796,14 +2043,16 @@ function isTransComponent(node, transComponents = []) {
1796
2043
  if (!opening)
1797
2044
  return false;
1798
2045
  const name = opening.name;
2046
+ // react-i18next's own: Trans, IcuTrans and their WithoutContext variants for Server Components
1799
2047
  if (name?.type === 'Identifier')
1800
- return name.value === 'Trans' || transComponents.includes(name.value);
2048
+ return TRANS_RE.test(name.value) || transComponents.includes(name.value);
1801
2049
  if (name?.type === 'JSXMemberExpression' && name.property?.type === 'Identifier') {
1802
2050
  const object = name.object?.type === 'Identifier' ? name.object.value : '';
1803
- return name.property.value === 'Trans' || transComponents.includes(`${object}.${name.property.value}`);
2051
+ return TRANS_RE.test(name.property.value) || transComponents.includes(`${object}.${name.property.value}`);
1804
2052
  }
1805
2053
  return false;
1806
2054
  }
2055
+ const TRANS_RE = /^(?:Icu)?Trans(?:WithoutContext)?$/;
1807
2056
  /**
1808
2057
  * An icon: an element whose name ends in `Icon`, or one with a Material icon class. Its text is a ligature
1809
2058
  * (`<Icon>delete</Icon>`, `<span className='material-icons'>search</span>`) that a translation would break.
@@ -17,6 +17,7 @@ function generateKeyFromContent(content) {
17
17
  // A placeholder's name gives words of its own: `{{unreadNews}}` → unread News
18
18
  .replace(/\{\{\s*([^}]*?)\s*\}\}/g, (_, name) => ` ${name.replace(/([a-z0-9])([A-Z])/g, '$1 $2')} `)
19
19
  .replace(/_/g, ' ') // `_` separates plural and context suffixes in i18next keys: none in a generated one
20
+ .normalize('NFD').replace(/[\u0300-\u036f]/g, '') // `Français` → Francais, not Franais
20
21
  .replace(/[^\w\s\d]/g, '') // Remove punctuation
21
22
  .trim();
22
23
  if (!normalized) {
@@ -0,0 +1,104 @@
1
+ 'use strict';
2
+
3
+ var node_fs = require('node:fs');
4
+ var node_path = require('node:path');
5
+ var config = require('../../config.js');
6
+
7
+ /** A `'use client'` directive: the first statement, after comments only. */
8
+ const USE_CLIENT_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*(['"])use client\1/;
9
+ /** The module specifiers of a file's static, dynamic and `require` imports and its re-exports. */
10
+ const IMPORT_RE = /\bfrom\s*['"]([^'"\n]+)['"]|\bimport\s*\(?\s*['"]([^'"\n]+)['"]|\brequire\(\s*['"]([^'"\n]+)['"]\s*\)/g;
11
+ const EXTENSIONS = ['', '.tsx', '.ts', '.jsx', '.js', '.mjs', '/index.tsx', '/index.ts', '/index.jsx', '/index.js'];
12
+ /**
13
+ * A file's absolute path with symbolic links resolved (`/var` is `/private/var` on macOS); one that does not exist
14
+ * (yet) resolves under the project root's real path.
15
+ */
16
+ function real(file, cwd) {
17
+ const abs = node_path.resolve(cwd, file);
18
+ try {
19
+ return node_fs.realpathSync(abs);
20
+ }
21
+ catch { }
22
+ try {
23
+ return abs.startsWith(cwd + node_path.sep) ? node_fs.realpathSync(cwd) + abs.slice(cwd.length) : abs;
24
+ }
25
+ catch {
26
+ return abs;
27
+ }
28
+ }
29
+ /** A file's path in the project, `/`-separated, without a leading `src/`: `app/page.tsx`, `pages/api/hello.js`. */
30
+ function projectPath(file, cwd = process.cwd()) {
31
+ return node_path.relative(real(cwd, cwd), real(file, cwd)).split(node_path.sep).join('/').replace(/^src\//, '');
32
+ }
33
+ /** The directory a file lies in under the project root: `app` or `src/app` (App Router), `pages` or `src/pages`. */
34
+ function routerOf(file, cwd) {
35
+ const top = projectPath(file, cwd).split('/')[0];
36
+ return top === 'app' || top === 'pages' ? top : null;
37
+ }
38
+ /**
39
+ * Classifies the files of a Next.js app by the components that render them, from the import graph: a file under
40
+ * `app/` is a Server Component unless it says `'use client'`; a `'use client'` file and all it imports are Client
41
+ * Components; a file under `pages/` and all it imports render with the Pages Router. Imports resolve relative,
42
+ * through the tsconfig `paths`, from the project root (a `baseUrl` import, `components/Card`) and with the `.js`
43
+ * of an ESM import for a `.ts` file; only the given files count.
44
+ *
45
+ * @param contents - The files' contents by path (relative to `cwd` or absolute)
46
+ * @returns The kind of each file and the files it imports, by the paths they were given with; a file nothing
47
+ * reaches is `unknown` (`pages` in an app without `app/`)
48
+ */
49
+ async function classifyNextFiles(contents, cwd = process.cwd()) {
50
+ const aliases = Object.entries(await config.getTsConfigAliases());
51
+ // by real path: the tsconfig aliases are real paths, and an absolute input glob may name a link (`/var/…`)
52
+ const byAbs = new Map([...contents.keys()].map(f => [real(f, cwd), f]));
53
+ const root = real(cwd, cwd);
54
+ const resolveImport = (from, spec) => {
55
+ const alias = aliases.find(([key]) => spec === key || spec.startsWith(key + '/'));
56
+ const bases = spec.startsWith('.')
57
+ ? [node_path.resolve(node_path.dirname(from), spec)]
58
+ : alias ? [node_path.resolve(alias[1], `.${spec.slice(alias[0].length)}`)] : [node_path.resolve(root, spec), node_path.resolve(root, 'src', spec)];
59
+ // resolve() again: an extension or `/index` joined to a Windows path
60
+ return bases.flatMap(base => [base, base.replace(/\.(?:m?js|jsx)$/, '')])
61
+ .flatMap(base => EXTENSIONS.map(ext => node_path.resolve(base + ext)))
62
+ .find(path => byAbs.has(path));
63
+ };
64
+ const imports = new Map();
65
+ const useClient = new Set();
66
+ for (const [abs, file] of byAbs) {
67
+ const code = contents.get(file);
68
+ if (USE_CLIENT_RE.test(code))
69
+ useClient.add(abs);
70
+ imports.set(abs, [...code.matchAll(IMPORT_RE)]
71
+ .map(m => resolveImport(abs, m[1] ?? m[2] ?? m[3]))
72
+ .filter((path) => !!path));
73
+ }
74
+ // Everything a set of files imports, transitively; a server walk stops at `'use client'`, the client boundary
75
+ const reach = (seeds, stopAtClient) => {
76
+ const seen = new Set();
77
+ const queue = [...seeds];
78
+ while (queue.length) {
79
+ const abs = queue.pop();
80
+ if (seen.has(abs) || (stopAtClient && useClient.has(abs)))
81
+ continue;
82
+ seen.add(abs);
83
+ queue.push(...imports.get(abs));
84
+ }
85
+ return seen;
86
+ };
87
+ const all = [...byAbs.keys()];
88
+ const server = reach(all.filter(abs => routerOf(abs, cwd) === 'app' && !useClient.has(abs)), true);
89
+ const appClient = reach([...useClient].filter(abs => routerOf(abs, cwd) !== 'pages'), false);
90
+ const pages = reach(all.filter(abs => routerOf(abs, cwd) === 'pages'), false);
91
+ const hasApp = all.some(abs => routerOf(abs, cwd) === 'app');
92
+ const kinds = new Map();
93
+ for (const [abs, file] of byAbs) {
94
+ // a file no route reaches may be rendered on either side, through an import that does not resolve
95
+ const kind = server.has(abs)
96
+ ? (appClient.has(abs) || pages.has(abs) ? 'shared' : 'server')
97
+ : appClient.has(abs) ? 'client' : pages.has(abs) || !hasApp ? 'pages' : 'unknown';
98
+ kinds.set(file, kind);
99
+ }
100
+ return { kinds, imports: new Map([...imports].map(([abs, paths]) => [byAbs.get(abs), paths.map(path => byAbs.get(path))])) };
101
+ }
102
+
103
+ exports.classifyNextFiles = classifyNextFiles;
104
+ exports.projectPath = projectPath;