i18next-cli 1.88.1 → 1.89.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 (46) hide show
  1. package/README.md +62 -9
  2. package/dist/cjs/cli.js +18 -3
  3. package/dist/cjs/extractor/core/translation-manager.js +9 -2
  4. package/dist/cjs/index.js +2 -1
  5. package/dist/cjs/init.js +3 -11
  6. package/dist/cjs/instrumenter/core/instrumenter.js +1114 -209
  7. package/dist/cjs/instrumenter/core/key-generator.js +19 -9
  8. package/dist/cjs/instrumenter/core/string-detector.js +106 -29
  9. package/dist/cjs/instrumenter/core/transformer.js +89 -31
  10. package/dist/cjs/localize/detect.js +2 -11
  11. package/dist/cjs/localize/localize.js +2 -1
  12. package/dist/cjs/utils/file-utils.js +48 -0
  13. package/dist/cjs/utils/jsx-attributes.js +3 -1
  14. package/dist/esm/cli.js +18 -3
  15. package/dist/esm/extractor/core/translation-manager.js +9 -2
  16. package/dist/esm/index.js +2 -1
  17. package/dist/esm/init.js +3 -11
  18. package/dist/esm/instrumenter/core/instrumenter.js +1117 -212
  19. package/dist/esm/instrumenter/core/key-generator.js +19 -9
  20. package/dist/esm/instrumenter/core/string-detector.js +107 -31
  21. package/dist/esm/instrumenter/core/transformer.js +89 -31
  22. package/dist/esm/localize/detect.js +3 -12
  23. package/dist/esm/localize/localize.js +2 -1
  24. package/dist/esm/utils/file-utils.js +49 -2
  25. package/dist/esm/utils/jsx-attributes.js +3 -1
  26. package/package.json +1 -1
  27. package/types/cli.d.ts.map +1 -1
  28. package/types/extractor/core/translation-manager.d.ts.map +1 -1
  29. package/types/index.d.ts +1 -1
  30. package/types/index.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 +2 -0
  34. package/types/instrumenter/core/key-generator.d.ts.map +1 -1
  35. package/types/instrumenter/core/string-detector.d.ts +5 -1
  36. package/types/instrumenter/core/string-detector.d.ts.map +1 -1
  37. package/types/instrumenter/core/transformer.d.ts +10 -1
  38. package/types/instrumenter/core/transformer.d.ts.map +1 -1
  39. package/types/instrumenter/index.d.ts +1 -1
  40. package/types/instrumenter/index.d.ts.map +1 -1
  41. package/types/localize/detect.d.ts.map +1 -1
  42. package/types/types.d.ts +48 -1
  43. package/types/types.d.ts.map +1 -1
  44. package/types/utils/file-utils.d.ts +7 -0
  45. package/types/utils/file-utils.d.ts.map +1 -1
  46. package/types/utils/jsx-attributes.d.ts.map +1 -1
@@ -14,24 +14,30 @@
14
14
  function generateKeyFromContent(content) {
15
15
  // Remove punctuation and split by whitespace and word boundaries
16
16
  const normalized = content
17
+ // A placeholder's name gives words of its own: `{{unreadNews}}` → unread News
18
+ .replace(/\{\{\s*([^}]*?)\s*\}\}/g, (_, name) => ` ${name.replace(/([a-z0-9])([A-Z])/g, '$1 $2')} `)
19
+ .replace(/_/g, ' ') // `_` separates plural and context suffixes in i18next keys: none in a generated one
17
20
  .replace(/[^\w\s\d]/g, '') // Remove punctuation
18
21
  .trim();
19
22
  if (!normalized) {
20
23
  return 'key';
21
24
  }
22
- // Split on whitespace and camelCase
25
+ // Split on whitespace and camelCase; whole words up to MAX_KEY_LENGTH, the first word always
23
26
  const words = normalized.split(/\s+/);
24
- const camelCased = words
25
- .map((word, index) => {
26
- if (index === 0) {
27
- return word.toLowerCase();
28
- }
29
- return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
30
- })
31
- .join('');
27
+ let camelCased = '';
28
+ for (const [index, word] of words.entries()) {
29
+ const part = index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
30
+ if (index > 0 && camelCased.length + part.length > MAX_KEY_LENGTH)
31
+ break;
32
+ camelCased += part;
33
+ }
32
34
  // If result is empty, use fallback
33
35
  return camelCased.length > 0 ? camelCased : 'key';
34
36
  }
37
+ /** A key names its text, it does not repeat it: a long sentence's key keeps its first words. */
38
+ const MAX_KEY_LENGTH = 40;
39
+ /** The content of a key reserved as the parent of nested keys: no text matches it. */
40
+ const PARENT_KEY = '\u0000';
35
41
  /**
36
42
  * Creates a new key registry with collision detection.
37
43
  */
@@ -39,6 +45,10 @@ function createKeyRegistry() {
39
45
  const keys = new Map();
40
46
  return {
41
47
  keys,
48
+ reserve(key, content) {
49
+ if (!keys.has(key))
50
+ keys.set(key, content ?? PARENT_KEY);
51
+ },
42
52
  add(baseKey, content) {
43
53
  const existing = keys.get(baseKey);
44
54
  // No collision - add the key
@@ -27,10 +27,12 @@ var jsxAttributes = require('../../utils/jsx-attributes.js');
27
27
  * @param config - Toolkit configuration
28
28
  * @param translatableAttributes - Lower-cased attribute names that hold text on the enclosing JSX element
29
29
  * (from the per-element `extract.acceptedAttributes` rules); defaults to the built-in list
30
+ * @param isJsxText - The string is JSX text, where a single lower-case word (`<Tag>expired</Tag>`) is text
31
+ * rather than an identifier
30
32
  * @returns CandidateString with confidence score, or null if should be skipped
31
33
  */
32
- function detectCandidate(content, offset, endOffset, file, code, config, translatableAttributes = jsxAttributes.translatableAttributeSet) {
33
- const skipReason = shouldSkip(content, file, code, offset, endOffset, translatableAttributes);
34
+ function detectCandidate(content, offset, endOffset, file, code, config, translatableAttributes = jsxAttributes.translatableAttributeSet, isJsxText = false) {
35
+ const skipReason = shouldSkip(content, file, code, offset, translatableAttributes, isJsxText);
34
36
  if (skipReason) {
35
37
  return null;
36
38
  }
@@ -71,12 +73,14 @@ function detectCandidate(content, offset, endOffset, file, code, config, transla
71
73
  column
72
74
  };
73
75
  }
76
+ /** An HTML character reference in JSX text: `&nbsp;`, `&#8212;`, `&#x2014;`. */
77
+ const HTML_ENTITY_RE = /&(?:#\d+|#x[\da-f]+|[a-z][a-z\d]*);/gi;
74
78
  /**
75
79
  * Determines if a string should be skipped from instrumentation.
76
80
  *
77
81
  * @returns Skip reason if should be skipped, null otherwise
78
82
  */
79
- function shouldSkip(content, file, code, offset, endOffset, translatableAttributes) {
83
+ function shouldSkip(content, file, code, offset, translatableAttributes, isJsxText) {
80
84
  // Skip test files
81
85
  if (file.match(/\.(test|spec)\.(ts|tsx|js|jsx)$/i)) {
82
86
  return 'Test file';
@@ -89,6 +93,10 @@ function shouldSkip(content, file, code, offset, endOffset, translatableAttribut
89
93
  if (/^\s+$/.test(content)) {
90
94
  return 'Whitespace only';
91
95
  }
96
+ // Skip separators, symbols and numbers with units: no letter outside HTML entities (` / `, `·`, `100%`)
97
+ if (!/\p{L}/u.test(content.replace(HTML_ENTITY_RE, ''))) {
98
+ return 'No letters';
99
+ }
92
100
  // Skip pure numbers (including decimals and negative numbers)
93
101
  if (/^-?\d+(\.\d+)?$/.test(content)) {
94
102
  return 'Pure number';
@@ -97,16 +105,21 @@ function shouldSkip(content, file, code, offset, endOffset, translatableAttribut
97
105
  if (isURLLike(content)) {
98
106
  return 'URL or path';
99
107
  }
100
- // Skip technical strings: attribute values, class names, technical IDs
101
- if (isTechnicalString(content)) {
108
+ // Skip technical strings: attribute values, class names, technical IDs; in a text slot (JSX text, a
109
+ // translatable attribute) a single word is text (`<Tag>expired</Tag>`, `aria-label='actions'`)
110
+ const textSlot = isJsxText || translatableAttributes.has(attributeNameBefore(code, offset) ?? '');
111
+ if (isTechnicalString(content) && !(textSlot && /^\p{L}+$/u.test(content) && !/\p{Ll}\p{Lu}/u.test(content))) {
102
112
  return 'Technical string';
103
113
  }
114
+ if (isCodeSnippet(content)) {
115
+ return 'Code snippet';
116
+ }
104
117
  // Skip developer-facing error codes (all-caps, underscore-delimited)
105
118
  if (isErrorCode(content)) {
106
119
  return 'Error code pattern';
107
120
  }
108
121
  // Skip strings that are already wrapped in t() or Trans components
109
- if (isAlreadyInstrumented(code, offset, endOffset)) {
122
+ if (isAlreadyInstrumented(code, offset)) {
110
123
  return 'Already instrumented';
111
124
  }
112
125
  // Skip console.log/warn/error arguments
@@ -129,8 +142,9 @@ function isURLLike(str) {
129
142
  // File paths: ./path, ../path, /absolute/path, C:\windows\path
130
143
  if (/^(\.\.?\/|\/|[A-Za-z]:\\)/.test(str))
131
144
  return true;
132
- // Import paths (common patterns) — must have no spaces to avoid false positives on sentences
133
- if (/^['"]?[@a-z][\w-]*/.test(str.toLowerCase()) && !str.includes(' ') && (str.includes('/') || str.includes('.'))) {
145
+ // Import paths and module ids (`react-dom/client`, `lodash.debounce`): no spaces, a `/` or a `.` inside;
146
+ // a word that ends a sentence (`Done.`, `first.`) is not one
147
+ if (/^['"]?[@a-z][\w-]*/.test(str) && !str.includes(' ') && /[./][\w@]/.test(str)) {
134
148
  return true;
135
149
  }
136
150
  return false;
@@ -139,8 +153,8 @@ function isURLLike(str) {
139
153
  * Checks if a string is technical (class name, HTML attribute, IDs, etc).
140
154
  */
141
155
  function isTechnicalString(str) {
142
- // kebab-case or camelCase all lowercase suggests CSS class or technical ID
143
- if (/^[a-z0-9-_]+$/.test(str) && str.length < 30) {
156
+ // kebab-case or snake_case, or one lowercase word: a CSS class or a technical ID, however long
157
+ if (/^[a-z0-9-_]+$/.test(str)) {
144
158
  return true;
145
159
  }
146
160
  // HTML attribute patterns like type="text", role="button", etc.
@@ -151,8 +165,58 @@ function isTechnicalString(str) {
151
165
  if (/^[A-Z]{2,3}$/.test(str)) {
152
166
  return true;
153
167
  }
168
+ // camelCase identifiers: object keys, event and feature names (`aiReview`, `apiKeys`)
169
+ if (/^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+$/.test(str)) {
170
+ return true;
171
+ }
172
+ if (isCSSValue(str)) {
173
+ return true;
174
+ }
175
+ // An HTTP authorization value (`Bearer ${token}`)
176
+ if (/^(?:Bearer|Basic|Digest|Token) \{\{\w+\}\}$/.test(str)) {
177
+ return true;
178
+ }
179
+ // One token holding `|`, `=` or an inner `:` is a rule, query or key path (`required|min:2`, `max:50`, `a=b`);
180
+ // a trailing colon is a label (`Note:`)
181
+ if (/^\S+$/.test(str) && /[|=]|:(?!$)/.test(str)) {
182
+ return true;
183
+ }
154
184
  return false;
155
185
  }
186
+ /** A CSS keyword or named color, the words a CSS value may hold besides numbers, colors and functions. */
187
+ const CSS_WORDS = new Set([
188
+ 'inset', 'solid', 'dashed', 'dotted', 'double', 'none', 'auto', 'inherit', 'initial', 'unset', 'transparent',
189
+ 'currentcolor', 'bold', 'normal', 'italic', 'center', 'left', 'right', 'top', 'bottom', 'flex', 'grid', 'block',
190
+ 'inline', 'absolute', 'relative', 'fixed', 'sticky', 'hidden', 'visible', 'ease', 'ease-in', 'ease-out',
191
+ 'ease-in-out', 'linear', 'black', 'white', 'red', 'green', 'blue', 'gray', 'grey', 'orange', 'yellow', 'purple'
192
+ ]);
193
+ /**
194
+ * Checks if a string is a CSS value: `var(--brand)`, `inset 0 0 5px 1px var(--shadow)`, `1px solid #ccc`. Only
195
+ * numbers (with a unit), colors, CSS functions and CSS keywords, at least one of them no keyword.
196
+ */
197
+ function isCSSValue(str) {
198
+ let rest = str.trim();
199
+ // CSS functions, nested ones from the inside out: var(--a, calc(1px + 2px))
200
+ for (let before = ''; before !== rest;) {
201
+ before = rest;
202
+ rest = rest.replace(/[a-z-]+\([^()]*\)/gi, ' \u0001 ');
203
+ }
204
+ const tokens = rest.split(/[\s,/]+/).filter(Boolean);
205
+ const valueToken = (t) => t === '\u0001' || /^#[\da-f]{3,8}$/i.test(t) ||
206
+ /^-?\d*\.?\d+(?:px|em|rem|%|vh|vw|vmin|vmax|ch|ex|pt|s|ms|deg|fr)?$/i.test(t);
207
+ return tokens.length > 0 &&
208
+ tokens.every(t => valueToken(t) || CSS_WORDS.has(t.toLowerCase()) || t === '!important') &&
209
+ tokens.some(t => valueToken(t) && !/^-?\d*\.?\d+$/.test(t));
210
+ }
211
+ /**
212
+ * Checks if a string is a code or shell snippet shown to the user as is: several lines, one of them code
213
+ * (a statement, a block brace or semicolon at its end, a comment, a command-line flag).
214
+ */
215
+ function isCodeSnippet(str) {
216
+ if (!str.includes('\n'))
217
+ return false;
218
+ return str.split('\n').some(line => /[{};]\s*$|^\s*(import|export|const|let|var|function|return|npm|npx|yarn|pnpm)\s|^\s*\/\/|\s--[a-z]/.test(line));
219
+ }
156
220
  /**
157
221
  * Checks if a string looks like a developer-facing error code.
158
222
  * Examples: ERROR_NOT_FOUND, ERR_INVALID_TOKEN, etc.
@@ -167,18 +231,12 @@ function isErrorCode(str) {
167
231
  /**
168
232
  * Checks if a string is already wrapped in a t() call or Trans component.
169
233
  */
170
- function isAlreadyInstrumented(code, offset, endOffset) {
171
- // Look backwards for t( — use 20 chars to cover patterns like `i18next.t(`
234
+ function isAlreadyInstrumented(code, offset) {
235
+ // The string is the first argument of t(), $t(), i18next.t(), props.t(): `t(` right before it, not just any
236
+ // name ending in t (`alert(`, `toast(`, `format(`). The instrumenter's AST walk skips whole t() calls and
237
+ // <Trans> elements, so their other arguments and children never get here.
172
238
  const beforeStr = code.substring(Math.max(0, offset - 20), offset);
173
- if (beforeStr.includes('t(') || beforeStr.includes('.t(')) {
174
- return true;
175
- }
176
- // Look forward for ) or Trans opening
177
- const afterStr = code.substring(endOffset, Math.min(code.length, endOffset + 20));
178
- if (afterStr.startsWith(')') || afterStr.includes('Trans')) {
179
- return true;
180
- }
181
- return false;
239
+ return /(?:^|[^\w$])\$?t\(\s*$/.test(beforeStr);
182
240
  }
183
241
  /**
184
242
  * Checks if this string is inside a console.log/warn/error call.
@@ -189,7 +247,18 @@ function isConsoleArgument(code, offset) {
189
247
  }
190
248
  // Translatable attribute and property sets are defined in
191
249
  // utils/jsx-attributes.ts and shared with the linter.
192
- const TRANSLATABLE_PROPERTIES = jsxAttributes.translatablePropertySet;
250
+ // lower-cased, as the property name is looked up lower-cased (`helpText` → `helptext`)
251
+ const TRANSLATABLE_PROPERTIES = new Set([...jsxAttributes.translatablePropertySet].map(p => p.toLowerCase()));
252
+ /** Object property names whose values are not text: headers, addresses, identifiers, styling. */
253
+ const TECHNICAL_PROPERTIES = new Set([
254
+ 'authorization', 'url', 'uri', 'href', 'src', 'path', 'pathname', 'endpoint', 'route', 'id', 'key',
255
+ 'class', 'classname', 'classes', 'cls', 'style', 'styles', 'method', 'mimetype', 'contenttype', 'accept', 'encoding',
256
+ 'icon', 'variant', 'color', 'type', 'code'
257
+ ]);
258
+ /** The lower-cased name of the JSX attribute whose value starts at `offset` (`title='…'`), or null. */
259
+ function attributeNameBefore(code, offset) {
260
+ return code.substring(Math.max(0, offset - 50), offset).match(/([\w-]+)=$/)?.[1].toLowerCase() ?? null;
261
+ }
193
262
  /**
194
263
  * Checks if the string appears to be an HTML/JSX attribute value.
195
264
  * Returns true only for *technical* attribute values that should be skipped.
@@ -234,7 +303,7 @@ function calculateConfidence(content, code, offset, translatableAttributes) {
234
303
  confidence += 0.1;
235
304
  }
236
305
  // Contains common sentence starters (user-facing)
237
- if (/^(the|a|an|you|your|we|our|hello|welcome|please|thank|sorry)/i.test(content)) {
306
+ if (/^(the|a|an|you|your|we|our|hello|welcome|please|thank|sorry)\b/i.test(content)) {
238
307
  confidence += 0.15;
239
308
  }
240
309
  // Contains punctuation (sentences)
@@ -250,7 +319,7 @@ function calculateConfidence(content, code, offset, translatableAttributes) {
250
319
  confidence += 0.05;
251
320
  }
252
321
  // Contains action verb (likely a button or instruction)
253
- if (/^(click|save|delete|create|update|submit|continue|back|next|yes|no|ok|close|open|download|upload|add|edit|remove|cancel|confirm|send|search|find|apply|reset|clear|done|finish|start|stop|retry|sign|log)/i.test(content)) {
322
+ if (/^(click|save|delete|create|update|submit|continue|back|next|yes|no|ok|close|open|download|upload|add|edit|remove|cancel|confirm|send|search|find|apply|reset|clear|done|finish|start|stop|retry|sign|log)\b/i.test(content)) {
254
323
  confidence += 0.1;
255
324
  }
256
325
  // Reduce confidence if appears in specific technical contexts
@@ -265,20 +334,27 @@ function calculateConfidence(content, code, offset, translatableAttributes) {
265
334
  if (attrCtxMatch) {
266
335
  const attrName = attrCtxMatch[1].toLowerCase();
267
336
  if (translatableAttributes.has(attrName)) {
268
- confidence += 0.15; // Translatable attribute — boost
337
+ confidence += 0.2; // Translatable attribute: its value is text, a single word too (`title='Publishing'`)
269
338
  }
270
339
  else {
271
340
  confidence -= 0.2;
272
341
  }
273
342
  }
274
343
  // Object-property context: { label: 'All', description: 'Some text' }
275
- // When the property name is a translatable-sounding key, boost confidence
276
- const propMatch = beforeContext.match(/(\w+)\s*:\s*$/);
277
- if (propMatch && !attrCtxMatch) {
278
- const propName = propMatch[1].toLowerCase();
344
+ // When the property name is a translatable-sounding key, boost confidence;
345
+ // a technical one ({ Authorization: `Bearer ${token}` }, { iconName: 'Lock' }) lowers it
346
+ // …and so does a variable a technical name is given (`const classes = …`, `cls = …`)
347
+ // (a quoted key has both quotes: `'…API key' :`, a ternary's string before its `:`, names no property)
348
+ const keyMatch = beforeContext.match(/(?:(['"])([\w-]+)\1|([A-Za-z_$][\w$]*))\s*:\s*$/);
349
+ const rawName = keyMatch ? (keyMatch[2] ?? keyMatch[3]) : beforeContext.match(/(\w+)\s+=\s*$/)?.[1];
350
+ if (rawName && !attrCtxMatch) {
351
+ const propName = rawName.toLowerCase().replace(/-/g, ''); // 'Content-Type' → contenttype
279
352
  if (TRANSLATABLE_PROPERTIES.has(propName)) {
280
353
  confidence += 0.25;
281
354
  }
355
+ else if (TECHNICAL_PROPERTIES.has(propName) || /[a-z0-9](Id|ID|Key|Url|URL|Path|Class|ClassName|Classes|Icon|Type)$/.test(rawName)) {
356
+ confidence -= 0.3;
357
+ }
282
358
  }
283
359
  // Regular expressions or patterns
284
360
  if (/\//.test(content) && /regex|pattern|match|search/i.test(beforeContext + afterContext)) {
@@ -288,4 +364,5 @@ function calculateConfidence(content, code, offset, translatableAttributes) {
288
364
  return Math.max(0, Math.min(1, confidence));
289
365
  }
290
366
 
367
+ exports.HTML_ENTITY_RE = HTML_ENTITY_RE;
291
368
  exports.detectCandidate = detectCandidate;
@@ -27,11 +27,14 @@ function transformFile(content, file, candidates, options) {
27
27
  importAdded: false,
28
28
  hookInjected: false
29
29
  };
30
+ // <Trans> attributes in the quotes the file's JSX attributes use (`title='…'` or `title="…"`)
31
+ // (a file without quoted attributes: the quotes of its imports)
32
+ const singleQuoted = (single, double) => Math.sign((content.match(single)?.length ?? 0) - (content.match(double)?.length ?? 0));
33
+ const jsxQuote = (singleQuoted(/\s[\w-]+='/g, /\s[\w-]+="/g) || singleQuoted(/\sfrom '/g, /\sfrom "/g)) > 0 ? "'" : '"';
30
34
  // Filter high-confidence candidates
31
35
  const highConfidenceCandidates = candidates.filter(c => c.confidence >= 0.7);
32
36
  // Track which components have transformed candidates
33
37
  const transformedComponents = new Set();
34
- let hasComponentCandidates = false;
35
38
  let hasNonComponentCandidates = false;
36
39
  let hasTransCandidates = false;
37
40
  // ── Language-change site injections ────────────────────────────────────
@@ -65,7 +68,6 @@ function transformFile(content, file, candidates, options) {
65
68
  if (site.insideComponent) {
66
69
  componentsNeedingI18n.add(site.insideComponent);
67
70
  transformedComponents.add(site.insideComponent);
68
- hasComponentCandidates = true;
69
71
  }
70
72
  else {
71
73
  hasNonComponentCandidates = true;
@@ -75,6 +77,7 @@ function transformFile(content, file, candidates, options) {
75
77
  errors.push(`Failed to inject changeLanguage at offset ${site.callStart}: ${err}`);
76
78
  }
77
79
  }
80
+ const rewrittenHelperCalls = new Map();
78
81
  // Apply transformations in reverse order (to maintain correct offsets)
79
82
  for (let i = highConfidenceCandidates.length - 1; i >= 0; i--) {
80
83
  const candidate = highConfidenceCandidates[i];
@@ -83,22 +86,26 @@ function transformFile(content, file, candidates, options) {
83
86
  const useHookStyle = !!candidate.insideComponent;
84
87
  const defaultNS = options.config.extract?.defaultNS ?? 'translation';
85
88
  const nsForReplacement = (options.namespace && options.namespace !== defaultNS) ? options.namespace : undefined;
86
- const replacement = buildReplacement(candidate, key, useHookStyle, nsForReplacement);
89
+ // <Trans> works in any render code, a helper outside a component too; without React the text stays
90
+ if (candidate.type === 'jsx-mixed' && !options.hasReact)
91
+ continue;
92
+ const replacement = buildReplacement(candidate, key, useHookStyle, nsForReplacement, jsxQuote);
87
93
  if (replacement) {
88
94
  s.overwrite(candidate.offset, candidate.endOffset, replacement);
89
95
  transformCount++;
96
+ if (candidate.pluralHelper)
97
+ rewrittenHelperCalls.set(candidate.pluralHelper, (rewrittenHelperCalls.get(candidate.pluralHelper) ?? 0) + 1);
90
98
  if (candidate.type === 'jsx-mixed') {
91
99
  hasTransCandidates = true;
92
100
  }
93
- if (candidate.insideComponent) {
94
- // jsx-mixed candidates use <Trans>, not t(), so they don't need useTranslation
95
- if (candidate.type !== 'jsx-mixed') {
101
+ // jsx-mixed candidates use <Trans>, not t(), so they need neither useTranslation nor i18next
102
+ if (candidate.type !== 'jsx-mixed') {
103
+ if (candidate.insideComponent) {
96
104
  transformedComponents.add(candidate.insideComponent);
97
- hasComponentCandidates = true;
98
105
  }
99
- }
100
- else {
101
- hasNonComponentCandidates = true;
106
+ else {
107
+ hasNonComponentCandidates = true;
108
+ }
102
109
  }
103
110
  }
104
111
  }
@@ -106,6 +113,19 @@ function transformFile(content, file, candidates, options) {
106
113
  errors.push(`Failed to transform candidate at offset ${candidate.offset}: ${err}`);
107
114
  }
108
115
  }
116
+ // A plural helper whose every call became a plural t() is no longer used: its import goes
117
+ for (const helper of options.pluralHelperImports ?? []) {
118
+ const rewritten = rewrittenHelperCalls.get(helper.name) ?? 0;
119
+ if (rewritten > 0 && rewritten === helper.references)
120
+ s.remove(helper.removeStart, helper.removeEnd);
121
+ }
122
+ // A memoized callback that now calls t() must run again when the language changes: `t` joins its dependencies
123
+ for (const hook of options.memoHooks ?? []) {
124
+ const usesT = highConfidenceCandidates.some(c => c.insideComponent && c.type !== 'jsx-mixed' &&
125
+ c.offset >= hook.callbackStart && c.endOffset <= hook.callbackEnd);
126
+ if (usesT && !hook.hasT)
127
+ s.appendLeft(hook.insertAt, hook.hasDeps ? ', t' : 't');
128
+ }
109
129
  // Add necessary imports and hooks if any transformations were made
110
130
  if (transformCount > 0 || languageChangeCount > 0) {
111
131
  const components = options.components || [];
@@ -115,8 +135,19 @@ function transformFile(content, file, candidates, options) {
115
135
  const affectedComponents = components
116
136
  .filter(c => transformedComponents.has(c.name) && !c.hasUseTranslation)
117
137
  .sort((a, b) => b.bodyStart - a.bodyStart);
138
+ const addHookLine = (comp, line) => {
139
+ const indent = comp.expressionBody ? lineIndent(content, comp.bodyStart) + ' ' : detectIndent(content, comp.bodyStart);
140
+ if (comp.expressionBody) {
141
+ // `() => <p>…</p>` becomes `() => { const { t } = useTranslation(); return <p>…</p> }`
142
+ s.prependLeft(comp.bodyStart, `{\n${indent}${line}\n${indent}return `);
143
+ s.appendRight(comp.bodyEnd, `\n${indent.slice(2)}}`);
144
+ }
145
+ else {
146
+ s.appendRight(comp.bodyStart + 1, `\n${indent}${line}`);
147
+ }
148
+ injections.hookInjected = true;
149
+ };
118
150
  for (const comp of affectedComponents) {
119
- const indent = detectIndent(content, comp.bodyStart);
120
151
  const defaultNS = options.config.extract?.defaultNS ?? 'translation';
121
152
  const nsArg = (options.namespace && options.namespace !== defaultNS) ? `'${options.namespace}'` : '';
122
153
  // Build destructuring: include `t` if the component has string candidates
@@ -133,9 +164,7 @@ function transformFile(content, file, candidates, options) {
133
164
  // (e.g. component only has jsx-mixed / <Trans> candidates)
134
165
  if (!needsT && !needsI18n)
135
166
  continue;
136
- const destructured = `{ ${parts.join(', ')} }`;
137
- s.appendRight(comp.bodyStart + 1, `\n${indent}const ${destructured} = useTranslation(${nsArg})`);
138
- injections.hookInjected = true;
167
+ addHookLine(comp, `const { ${parts.join(', ')} } = useTranslation(${nsArg})`);
139
168
  }
140
169
  // For components that already have useTranslation but need i18n added,
141
170
  // try to upgrade `const { t } = useTranslation(...)` → `const { t, i18n } = useTranslation(...)`
@@ -156,15 +185,20 @@ function transformFile(content, file, candidates, options) {
156
185
  const upgraded = hookMatch[0].replace(/\{\s*t\s*\}/, '{ t, i18n }');
157
186
  s.overwrite(absStart, absEnd, upgraded);
158
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
+ }
159
192
  }
160
193
  }
161
194
  }
162
195
  // Add import statements
163
196
  addImportStatements(s, content, {
164
- needsUseTranslation: hasComponentCandidates && options.hasReact,
197
+ // only for a hook injected here: a component with a `t` of its own (a prop) needs none
198
+ needsUseTranslation: injections.hookInjected,
165
199
  needsI18next: hasNonComponentCandidates || !options.hasReact,
166
200
  needsTrans: hasTransCandidates && options.hasReact
167
- });
201
+ }, options.imports);
168
202
  injections.importAdded = true;
169
203
  }
170
204
  // Warn when i18next.t() is used in React projects (translations may not be loaded yet)
@@ -196,7 +230,7 @@ function transformFile(content, file, candidates, options) {
196
230
  * @param useHookStyle - If true, uses t() (from useTranslation hook); otherwise uses i18next.t()
197
231
  * @param namespace - Optional namespace (only set when different from defaultNS)
198
232
  */
199
- function buildReplacement(candidate, key, useHookStyle, namespace) {
233
+ function buildReplacement(candidate, key, useHookStyle, namespace, jsxQuote = '"') {
200
234
  const tFunc = useHookStyle ? 't' : 'i18next.t';
201
235
  const escapedContent = escapeString(candidate.content);
202
236
  // ── Plural form: t('key', { defaultValue_zero: '…', …, count: expr }) ──
@@ -245,12 +279,10 @@ function buildReplacement(candidate, key, useHookStyle, namespace) {
245
279
  case 'jsx-text':
246
280
  case 'jsx-attribute':
247
281
  return `{${tCall}}`;
248
- case 'jsx-mixed':
249
- if (useHookStyle) {
250
- const nsAttr = namespace ? ` ns="${namespace}"` : '';
251
- return `<Trans i18nKey="${key}"${nsAttr}>${candidate.content}</Trans>`;
252
- }
253
- return candidate.content;
282
+ case 'jsx-mixed': {
283
+ const nsAttr = namespace ? ` ns=${jsxQuote}${namespace}${jsxQuote}` : '';
284
+ return `<Trans i18nKey=${jsxQuote}${key}${jsxQuote}${nsAttr}>${candidate.content}</Trans>`;
285
+ }
254
286
  case 'template-literal':
255
287
  case 'string-literal':
256
288
  default:
@@ -280,6 +312,11 @@ function hasImport(content, moduleName) {
280
312
  * Detects the indentation level used after an opening brace.
281
313
  * Skips blank lines and reads the whitespace of the first line that has actual content.
282
314
  */
315
+ /** The indentation of the line `offset` is on. */
316
+ function lineIndent(content, offset) {
317
+ const lineStart = content.lastIndexOf('\n', offset - 1) + 1;
318
+ return /^[ \t]*/.exec(content.slice(lineStart))[0];
319
+ }
283
320
  function detectIndent(content, braceOffset) {
284
321
  let searchFrom = braceOffset;
285
322
  while (searchFrom < content.length) {
@@ -304,24 +341,31 @@ function detectIndent(content, braceOffset) {
304
341
  /**
305
342
  * Adds necessary import statements (useTranslation, Trans, and/or i18next).
306
343
  */
307
- function addImportStatements(s, content, needs) {
344
+ function addImportStatements(s, content, needs, imports) {
308
345
  let importStatement = '';
346
+ const imported = (moduleName) => imports
347
+ ? imports.some(i => i.source === moduleName) || new RegExp(`require\\(['"]${moduleName}['"]\\)`).test(content)
348
+ : hasImport(content, moduleName);
349
+ // A name the file imports already, from any module (`useTranslation` re-exported by a shared package)
350
+ const bound = (name) => !!imports?.some(i => i.locals?.includes(name));
309
351
  // Build a combined react-i18next import
310
352
  const reactI18nextImports = [];
311
- if (needs.needsUseTranslation)
353
+ if (needs.needsUseTranslation && !bound('useTranslation'))
312
354
  reactI18nextImports.push('useTranslation');
313
- if (needs.needsTrans)
355
+ if (needs.needsTrans && !bound('Trans'))
314
356
  reactI18nextImports.push('Trans');
315
357
  if (reactI18nextImports.length > 0) {
316
- if (!hasImport(content, 'react-i18next')) {
358
+ if (!imported('react-i18next')) {
317
359
  importStatement += `import { ${reactI18nextImports.join(', ')} } from 'react-i18next'\n`;
318
360
  }
319
361
  else {
320
362
  // react-i18next is already imported — augment with any missing named exports
321
- augmentReactI18nextImport(s, content, reactI18nextImports);
363
+ const existing = imports?.find(i => i.source === 'react-i18next');
364
+ augmentReactI18nextImport(s, content, reactI18nextImports, existing?.start ?? 0);
322
365
  }
323
366
  }
324
- if (needs.needsI18next && !hasImport(content, 'i18next')) {
367
+ // `i18next.t()` needs that name: with the AST, an import of i18next under another name does not count
368
+ if (needs.needsI18next && (imports ? !bound('i18next') : !imported('i18next'))) {
325
369
  importStatement += "import i18next from 'i18next'\n";
326
370
  }
327
371
  if (!importStatement)
@@ -332,6 +376,18 @@ function addImportStatements(s, content, needs) {
332
376
  if (content.startsWith('#!')) {
333
377
  insertPos = content.indexOf('\n') + 1;
334
378
  }
379
+ if (imports) {
380
+ // After the last import declaration's line
381
+ const lastEnd = Math.max(...imports.map(i => i.end), -1);
382
+ if (lastEnd >= 0) {
383
+ const newline = content.indexOf('\n', lastEnd);
384
+ insertPos = newline === -1 ? content.length : newline + 1;
385
+ }
386
+ if (insertPos > 0 && content[insertPos - 1] !== '\n')
387
+ importStatement = `\n${importStatement}`;
388
+ s.appendRight(insertPos, importStatement);
389
+ return;
390
+ }
335
391
  // Find the end of the last import statement. Imports may span multiple lines
336
392
  // (e.g. `import {\n CCol,\n} from '...'`), so we can't treat each `import`
337
393
  // line as a complete statement — we scan to the real end of each declaration.
@@ -400,8 +456,10 @@ function findImportStatementEnd(content, start) {
400
456
  * Augments an existing `import { ... } from 'react-i18next'` with any missing
401
457
  * named exports (e.g. adds `Trans` when only `useTranslation` is imported).
402
458
  */
403
- function augmentReactI18nextImport(s, content, needed) {
404
- const importMatch = /import\s*\{([^}]*)\}\s*from\s*['"]react-i18next['"]/.exec(content);
459
+ function augmentReactI18nextImport(s, content, needed, from = 0) {
460
+ const importRegex = /import\s*\{([^}]*)\}\s*from\s*['"]react-i18next['"]/g;
461
+ importRegex.lastIndex = from;
462
+ const importMatch = importRegex.exec(content);
405
463
  if (!importMatch)
406
464
  return;
407
465
  const existingImports = importMatch[1].split(',').map(x => x.trim()).filter(Boolean);
@@ -2,6 +2,7 @@
2
2
 
3
3
  var promises = require('node:fs/promises');
4
4
  var node_path = require('node:path');
5
+ var fileUtils = require('../utils/file-utils.js');
5
6
 
6
7
  async function pathExists(path) {
7
8
  try {
@@ -12,16 +13,6 @@ async function pathExists(path) {
12
13
  return false;
13
14
  }
14
15
  }
15
- async function readPackageDeps() {
16
- try {
17
- const content = await promises.readFile(node_path.join(process.cwd(), 'package.json'), 'utf-8');
18
- const packageJson = JSON.parse(content);
19
- return { ...packageJson.dependencies, ...packageJson.devDependencies };
20
- }
21
- catch {
22
- return {};
23
- }
24
- }
25
16
  /**
26
17
  * Detects the project stack relevant to the `localize` orchestrator:
27
18
  * frontend framework, i18next presence, an existing i18n init file,
@@ -34,7 +25,7 @@ async function readPackageDeps() {
34
25
  * (injected to reuse the instrumenter's implementation)
35
26
  */
36
27
  async function detectStack(findInitFile) {
37
- const deps = await readPackageDeps();
28
+ const deps = await fileUtils.readProjectDeps();
38
29
  const has = (name) => !!deps[name];
39
30
  let framework = 'unknown';
40
31
  if (has('next'))
@@ -10,6 +10,7 @@ var heuristicConfig = require('../heuristic-config.js');
10
10
  var extractor = require('../extractor/core/extractor.js');
11
11
  require('node:path');
12
12
  require('jsonc-parser');
13
+ require('minimatch');
13
14
  require('jiti');
14
15
  require('@croct/json5-parser');
15
16
  require('yaml');
@@ -17,7 +18,7 @@ require('node:module');
17
18
  require('@swc/core');
18
19
  var nestedObject = require('../utils/nested-object.js');
19
20
  var instrumenter = require('../instrumenter/core/instrumenter.js');
20
- require('../utils/jsx-attributes.js');
21
+ require('../instrumenter/core/string-detector.js');
21
22
  require('magic-string');
22
23
  var locize = require('../locize.js');
23
24
  var locizeOnboarding = require('../utils/locize-onboarding.js');