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