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.
- package/README.md +57 -7
- package/dist/cjs/cli.js +8 -4
- package/dist/cjs/config.js +13 -12
- package/dist/cjs/extractor/core/extractor.js +1 -3
- package/dist/cjs/extractor/parsers/jsx-parser.js +4 -2
- package/dist/cjs/heuristic-config.js +51 -6
- package/dist/cjs/init.js +5 -0
- package/dist/cjs/instrumenter/core/instrumenter.js +272 -23
- package/dist/cjs/instrumenter/core/key-generator.js +1 -0
- package/dist/cjs/instrumenter/core/next-files.js +104 -0
- package/dist/cjs/instrumenter/core/transformer.js +97 -73
- package/dist/cjs/linter.js +190 -23
- package/dist/cjs/localize/agent-prompt.js +5 -2
- package/dist/cjs/localize/detect.js +1 -0
- package/dist/cjs/localize/localize.js +25 -4
- package/dist/esm/cli.js +8 -4
- package/dist/esm/config.js +13 -12
- package/dist/esm/extractor/core/extractor.js +1 -3
- package/dist/esm/extractor/parsers/jsx-parser.js +4 -3
- package/dist/esm/heuristic-config.js +52 -7
- package/dist/esm/init.js +5 -0
- package/dist/esm/instrumenter/core/instrumenter.js +273 -24
- package/dist/esm/instrumenter/core/key-generator.js +1 -0
- package/dist/esm/instrumenter/core/next-files.js +101 -0
- package/dist/esm/instrumenter/core/transformer.js +97 -73
- package/dist/esm/linter.js +192 -25
- package/dist/esm/localize/agent-prompt.js +5 -2
- package/dist/esm/localize/detect.js +1 -0
- package/dist/esm/localize/localize.js +25 -4
- package/package.json +2 -1
- package/types/cli.d.ts.map +1 -1
- package/types/config.d.ts.map +1 -1
- package/types/extractor/core/extractor.d.ts.map +1 -1
- package/types/extractor/parsers/jsx-parser.d.ts +1 -0
- package/types/extractor/parsers/jsx-parser.d.ts.map +1 -1
- package/types/heuristic-config.d.ts.map +1 -1
- package/types/init.d.ts.map +1 -1
- package/types/instrumenter/core/instrumenter.d.ts.map +1 -1
- package/types/instrumenter/core/key-generator.d.ts.map +1 -1
- package/types/instrumenter/core/next-files.d.ts +25 -0
- package/types/instrumenter/core/next-files.d.ts.map +1 -0
- package/types/instrumenter/core/transformer.d.ts +6 -0
- package/types/instrumenter/core/transformer.d.ts.map +1 -1
- package/types/linter.d.ts.map +1 -1
- package/types/localize/agent-prompt.d.ts +1 -1
- package/types/localize/agent-prompt.d.ts.map +1 -1
- package/types/localize/detect.d.ts +2 -0
- package/types/localize/detect.d.ts.map +1 -1
- package/types/localize/localize.d.ts.map +1 -1
- package/types/types.d.ts +54 -2
- 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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
const
|
|
157
|
-
const
|
|
158
|
-
|
|
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
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
const
|
|
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
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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
|
|
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,
|
|
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
|
-
|
|
352
|
-
const
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
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
|
-
//
|
|
363
|
-
const existing = imports?.find(i => i.source ===
|
|
364
|
-
|
|
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 (
|
|
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 '
|
|
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
|
|
460
|
-
const
|
|
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 '
|
|
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);
|
package/dist/cjs/linter.js
CHANGED
|
@@ -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
|
|
190
|
-
//
|
|
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
|
-
|
|
194
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
:
|
|
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
|
|
56
|
-
|
|
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.
|
|
274
|
-
warn(
|
|
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;
|