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
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
const
|
|
151
|
-
const
|
|
152
|
-
|
|
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
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
const
|
|
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
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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
|
|
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,
|
|
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
|
-
|
|
346
|
-
const
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
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
|
-
//
|
|
357
|
-
const existing = imports?.find(i => i.source ===
|
|
358
|
-
|
|
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 (
|
|
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 '
|
|
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
|
|
454
|
-
const
|
|
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 '
|
|
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);
|
package/dist/esm/linter.js
CHANGED
|
@@ -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,
|
|
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
|
|
188
|
-
//
|
|
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
|
-
|
|
192
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
:
|
|
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
|
|
54
|
-
|
|
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.
|
|
268
|
-
warn(
|
|
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 };
|