i18next-cli 1.46.4 → 1.47.0

package/dist/esm/instrumenter/core/instrumenter.js

@@ -0,0 +1,1630 @@
+import { readFile, mkdir, writeFile, access } from 'node:fs/promises';
+import { glob } from 'glob';
+import { dirname, extname, join, relative, isAbsolute, resolve } from 'node:path';
+import { parse } from '@swc/core';
+import inquirer from 'inquirer';
+import { styleText } from 'node:util';
+import { detectCandidate } from './string-detector.js';
+import { transformFile } from './transformer.js';
+import { createKeyRegistry, generateKeyFromContent } from './key-generator.js';
+import { createSpinnerLike } from '../../utils/wrap-ora.js';
+import { ConsoleLogger } from '../../utils/logger.js';
+import { ignoredAttributeSet } from '../../utils/jsx-attributes.js';
+import { findFirstTokenIndex, normalizeASTSpans } from '../../extractor/parsers/ast-utils.js';
+import { getOutputPath } from '../../utils/file-utils.js';
+
+/**
+ * Main orchestrator for the instrument command.
+ * Scans source files for hardcoded strings and instruments them with i18next calls.
+ *
+ * @param config - Toolkit configuration
+ * @param options - Instrumentation options (dry-run, interactive, etc.)
+ * @param logger - Logger instance
+ * @returns Instrumentation results
+ */
+async function runInstrumenter(config, options, logger = new ConsoleLogger()) {
+    config.extract.primaryLanguage ||= config.locales[0] || 'en';
+    config.extract.secondaryLanguages ||= config.locales.filter((l) => l !== config?.extract?.primaryLanguage);
+    const spinner = createSpinnerLike('Scanning for hardcoded strings...\n', { quiet: !!options.quiet, logger });
+    try {
+        // Get list of source files
+        const sourceFiles = await getSourceFilesForInstrumentation(config);
+        spinner.text = `Scanning ${sourceFiles.length} files for hardcoded strings...`;
+        // Scan files for candidate strings
+        const results = [];
+        const keyRegistry = createKeyRegistry();
+        let totalCandidates = 0;
+        let totalTransformed = 0;
+        let totalSkipped = 0;
+        let totalLanguageChanges = 0;
+        // Detect framework and language
+        const hasReact = await isProjectUsingReact();
+        const hasTypeScript = await isProjectUsingTypeScript();
+        // Initialize plugins
+        const plugins = config.plugins || [];
+        await initializeInstrumentPlugins(plugins, { config, logger });
+        // Resolve target namespace
+        let targetNamespace = options.namespace;
+        if (!targetNamespace && options.isInteractive) {
+            const defaultNS = config.extract.defaultNS ?? 'translation';
+            const { ns } = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'ns',
+                    message: 'Target namespace for extracted keys:',
+                    default: typeof defaultNS === 'string' ? defaultNS : 'translation'
+                }
+            ]);
+            if (ns && ns !== defaultNS) {
+                targetNamespace = ns;
+            }
+        }
+        for (const file of sourceFiles) {
+            try {
+                let content = await readFile(file, 'utf-8');
+                // Run instrumentOnLoad plugin pipeline
+                const loadResult = await runInstrumentOnLoadPipeline(content, file, plugins, logger);
+                if (loadResult === null)
+                    continue; // plugin says skip this file
+                content = loadResult;
+                const scanResult = await scanFileForCandidates(content, file, config);
+                let { candidates } = scanResult;
+                const { components, languageChangeSites } = scanResult;
+                // Run instrumentOnResult plugin pipeline
+                candidates = await runInstrumentOnResultPipeline(file, candidates, plugins, logger);
+                if (candidates.length === 0 && languageChangeSites.length === 0) {
+                    continue;
+                }
+                totalCandidates += candidates.length;
+                // Handle interactive mode
+                if (options.isInteractive) {
+                    // Ask user about each candidate
+                    for (const candidate of candidates) {
+                        const { action } = await inquirer.prompt([
+                            {
+                                type: 'list',
+                                name: 'action',
+                                message: `Translate: "${candidate.content}" (${candidate.line}:${candidate.column})?`,
+                                choices: [
+                                    { name: 'Approve', value: 'approve' },
+                                    { name: 'Skip', value: 'skip' },
+                                    { name: 'Edit key', value: 'edit-key' },
+                                    { name: 'Edit value', value: 'edit-value' }
+                                ]
+                            }
+                        ]);
+                        switch (action) {
+                            case 'approve':
+                                candidate.key = generateKeyFromContent(candidate.content);
+                                break;
+                            case 'skip':
+                                candidate.skipReason = 'User skipped';
+                                break;
+                            case 'edit-key': {
+                                const { key } = await inquirer.prompt([
+                                    {
+                                        type: 'input',
+                                        name: 'key',
+                                        message: 'New key:',
+                                        default: generateKeyFromContent(candidate.content)
+                                    }
+                                ]);
+                                candidate.key = key;
+                                break;
+                            }
+                            case 'edit-value': {
+                                const { value } = await inquirer.prompt([
+                                    {
+                                        type: 'input',
+                                        name: 'value',
+                                        message: 'New value:',
+                                        default: candidate.content
+                                    }
+                                ]);
+                                candidate.content = value;
+                                candidate.key = generateKeyFromContent(value);
+                                break;
+                            }
+                        }
+                    }
+                }
+                // Filter candidates that were skipped by user
+                const approvedCandidates = candidates.filter(c => !c.skipReason);
+                if (approvedCandidates.length > 0 || languageChangeSites.length > 0) {
+                    // Generate keys for approved candidates
+                    for (const candidate of approvedCandidates) {
+                        if (!candidate.key) {
+                            candidate.key = keyRegistry.add(generateKeyFromContent(candidate.content), candidate.content);
+                        }
+                    }
+                    // Transform the file
+                    const transformResult = transformFile(content, file, approvedCandidates, {
+                        isDryRun: options.isDryRun,
+                        hasReact,
+                        isPrimaryLanguageFile: true,
+                        config,
+                        components,
+                        namespace: targetNamespace,
+                        languageChangeSites
+                    });
+                    if (!options.isDryRun && transformResult.modified) {
+                        // Write the transformed file
+                        await mkdir(dirname(file), { recursive: true });
+                        await writeFile(file, transformResult.newContent || content);
+                    }
+                    totalTransformed += transformResult.transformCount;
+                    totalLanguageChanges += transformResult.languageChangeCount;
+                    totalSkipped += candidates.length - approvedCandidates.length;
+                    // Log any warnings (e.g. i18next.t() in React files)
+                    if (transformResult.warnings?.length) {
+                        for (const warning of transformResult.warnings) {
+                            logger.warn(warning);
+                        }
+                    }
+                    results.push({
+                        file,
+                        candidates: approvedCandidates,
+                        result: transformResult
+                    });
+                }
+                else {
+                    totalSkipped += candidates.length;
+                }
+            }
+            catch (err) {
+                logger.warn(`Error processing ${file}:`, err);
+            }
+        }
+        const langChangeSuffix = totalLanguageChanges > 0 ? `, ${totalLanguageChanges} language-change site(s)` : '';
+        spinner.succeed(styleText('bold', `Scanned complete: ${totalCandidates} candidates, ${totalTransformed} approved${langChangeSuffix}`));
+        // Generate i18n init file if needed and any transformations were made
+        if ((totalTransformed > 0 || totalLanguageChanges > 0) && !options.isDryRun) {
+            const initFilePath = await ensureI18nInitFile(hasReact, hasTypeScript, config, logger);
+            if (initFilePath) {
+                await injectI18nImportIntoEntryFile(initFilePath, logger);
+            }
+        }
+        // Return summary
+        return {
+            files: results,
+            totalCandidates,
+            totalTransformed,
+            totalSkipped,
+            totalLanguageChanges,
+            extractedKeys: new Map()
+        };
+    }
+    catch (error) {
+        spinner.fail(styleText('red', 'Instrumentation failed'));
+        throw error;
+    }
+}
+/**
+ * Scans a source file for hardcoded string candidates and React component boundaries.
+ */
+async function scanFileForCandidates(content, file, config) {
+    const candidates = [];
+    const components = [];
+    const languageChangeSites = [];
+    const fileExt = extname(file).toLowerCase();
+    const isTypeScriptFile = ['.ts', '.tsx', '.mts', '.cts'].includes(fileExt);
+    const isTSX = fileExt === '.tsx';
+    const isJSX = fileExt === '.jsx';
+    try {
+        // Parse the file
+        let ast;
+        try {
+            ast = await parse(content, {
+                syntax: isTypeScriptFile ? 'typescript' : 'ecmascript',
+                tsx: isTSX,
+                jsx: isJSX,
+                decorators: true,
+                dynamicImport: true,
+                comments: true
+            });
+        }
+        catch (err) {
+            // Fallback parsing for .ts with JSX
+            if (fileExt === '.ts' && !isTSX) {
+                ast = await parse(content, {
+                    syntax: 'typescript',
+                    tsx: true,
+                    decorators: true,
+                    dynamicImport: true,
+                    comments: true
+                });
+            }
+            else if (fileExt === '.js' && !isJSX) {
+                ast = await parse(content, {
+                    syntax: 'ecmascript',
+                    jsx: true,
+                    decorators: true,
+                    dynamicImport: true,
+                    comments: true
+                });
+            }
+            else {
+                throw err;
+            }
+        }
+        // Normalize spans
+        const firstTokenIdx = findFirstTokenIndex(content);
+        const spanBase = ast.span.start - firstTokenIdx;
+        normalizeASTSpans(ast, spanBase);
+        // Convert byte offsets → char indices for files with multi-byte characters.
+        // SWC reports spans as UTF-8 byte offsets, but JavaScript strings and
+        // MagicString use UTF-16 code-unit indices. Without this conversion,
+        // every emoji / accented char / CJK char shifts all subsequent offsets.
+        const byteToChar = buildByteToCharMap(content);
+        if (byteToChar) {
+            convertSpansToCharIndices(ast, byteToChar);
+        }
+        // Detect React function component boundaries
+        detectComponentBoundaries(ast, content, components);
+        // Visit AST to find string literals
+        visitNodeForStrings(ast, content, file, config, candidates);
+        // Detect JSX interpolation patterns (merge adjacent text + expression children)
+        detectJSXInterpolation(ast, content, file, config, candidates);
+        // Detect plural conditional patterns (ternary chains checking count === 0/1/other)
+        detectPluralPatterns(ast, content, file, config, candidates);
+        // Detect language-change call sites (e.g. updateSettings({ language: code }))
+        detectLanguageChangeSites(ast, content, languageChangeSites);
+        // Annotate candidates with their enclosing component (if any)
+        for (const candidate of candidates) {
+            for (const comp of components) {
+                if (candidate.offset >= comp.bodyStart && candidate.endOffset <= comp.bodyEnd) {
+                    candidate.insideComponent = comp.name;
+                    break;
+                }
+            }
+        }
+        // Annotate language change sites with their enclosing component (if any)
+        for (const site of languageChangeSites) {
+            for (const comp of components) {
+                if (site.callStart >= comp.bodyStart && site.callEnd <= comp.bodyEnd) {
+                    site.insideComponent = comp.name;
+                    break;
+                }
+            }
+        }
+        // Filter out candidates suppressed by ignore-comment directives.
+        // Supported comments (line or block):
+        //   // i18next-instrument-ignore-next-line
+        //   // i18next-instrument-ignore
+        //   /* i18next-instrument-ignore-next-line */
+        //   /* i18next-instrument-ignore */
+        const ignoredLines = collectIgnoredLines(content);
+        if (ignoredLines.size > 0) {
+            const keep = [];
+            for (const c of candidates) {
+                const line = lineOfOffset(content, c.offset);
+                if (!ignoredLines.has(line)) {
+                    keep.push(c);
+                }
+            }
+            candidates.length = 0;
+            candidates.push(...keep);
+        }
+    }
+    catch (err) {
+        // Silently skip files that can't be parsed
+    }
+    return { candidates, components, languageChangeSites };
+}
+// ─── Ignore-comment helpers ──────────────────────────────────────────────────
+/**
+ * Regex that matches a directive comment requesting the instrumenter to skip
+ * the **next** line. Works with both line comments (`// ...`) and block
+ * comments. The supported directives are:
+ *
+ *   i18next-instrument-ignore-next-line
+ *   i18next-instrument-ignore
+ */
+const IGNORE_RE = /i18next-instrument-ignore(?:-next-line)?/;
+/**
+ * Scans `content` for ignore-directive comments and returns a Set of 1-based
+ * line numbers whose strings should be excluded from instrumentation.
+ */
+function collectIgnoredLines(content) {
+    const ignored = new Set();
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (IGNORE_RE.test(lines[i])) {
+            // Directive on line i → suppress the *following* line (i + 1)
+            // We store 1-based line numbers, so the suppressed line is i + 2
+            ignored.add(i + 2);
+        }
+    }
+    return ignored;
+}
+/**
+ * Returns the 1-based line number for a character offset.
+ */
+function lineOfOffset(content, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === '\n')
+            line++;
+    }
+    return line;
+}
+// ─── Component boundary detection ───────────────────────────────────────────
+/**
+ * Recursively detects React function component boundaries in the AST.
+ *
+ * Identifies:
+ * - FunctionDeclaration with uppercase name: `function Greeting() { ... }`
+ * - FunctionExpression with uppercase name: `export default function Greeting() { ... }`
+ * - VariableDeclarator with uppercase name + arrow/function expression:
+ *   `const Greeting = () => { ... }` or `const Greeting = function() { ... }`
+ * - forwardRef wrappers: `const Greeting = React.forwardRef((props, ref) => { ... })`
+ * - memo wrappers: `const Greeting = React.memo(() => { ... })`
+ */
+function detectComponentBoundaries(node, content, components) {
+    if (!node)
+        return;
+    // FunctionDeclaration with uppercase name
+    if (node.type === 'FunctionDeclaration' && node.identifier?.value && /^[A-Z]/.test(node.identifier.value)) {
+        const body = node.body;
+        if (body?.type === 'BlockStatement' && body.span) {
+            components.push({
+                name: node.identifier.value,
+                bodyStart: body.span.start,
+                bodyEnd: body.span.end,
+                hasUseTranslation: content.slice(body.span.start, body.span.end).includes('useTranslation')
+            });
+        }
+    }
+    // FunctionExpression with uppercase name.
+    // Covers `export default function TasksPage() { ... }` — SWC represents the
+    // function inside ExportDefaultDeclaration as a FunctionExpression, not a
+    // FunctionDeclaration. Deduplicate against bodies already registered by the
+    // VariableDeclarator path (e.g. `const Foo = function Foo() {}`).
+    if (node.type === 'FunctionExpression' && node.identifier?.value && /^[A-Z]/.test(node.identifier.value)) {
+        const body = node.body;
+        if (body?.type === 'BlockStatement' && body.span) {
+            const alreadyRegistered = components.some(c => c.bodyStart === body.span.start && c.bodyEnd === body.span.end);
+            if (!alreadyRegistered) {
+                components.push({
+                    name: node.identifier.value,
+                    bodyStart: body.span.start,
+                    bodyEnd: body.span.end,
+                    hasUseTranslation: content.slice(body.span.start, body.span.end).includes('useTranslation')
+                });
+            }
+        }
+    }
+    // VariableDeclarator with uppercase name
+    if (node.type === 'VariableDeclarator' && node.id?.value && /^[A-Z]/.test(node.id.value)) {
+        const init = node.init;
+        if (init) {
+            // Direct arrow/function expression: const Greeting = () => { ... }
+            if (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') {
+                addComponentFromFunctionNode(node.id.value, init, content, components);
+            }
+            // Wrapped in a call: React.memo(...), React.forwardRef(...), memo(...), forwardRef(...)
+            if (init.type === 'CallExpression') {
+                const callee = init.callee;
+                const isWrapper = 
+                // React.forwardRef, React.memo
+                (callee?.type === 'MemberExpression' &&
+                    (callee.property?.value === 'forwardRef' || callee.property?.value === 'memo')) ||
+                    // forwardRef, memo (direct import)
+                    (callee?.type === 'Identifier' &&
+                        (callee.value === 'forwardRef' || callee.value === 'memo'));
+                if (isWrapper && init.arguments?.length > 0) {
+                    const arg = init.arguments[0]?.expression || init.arguments[0];
+                    if (arg && (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression')) {
+                        addComponentFromFunctionNode(node.id.value, arg, content, components);
+                    }
+                }
+            }
+        }
+    }
+    // Recurse into children
+    for (const key in node) {
+        const value = node[key];
+        if (value && typeof value === 'object') {
+            if (Array.isArray(value)) {
+                value.forEach(item => detectComponentBoundaries(item, content, components));
+            }
+            else {
+                detectComponentBoundaries(value, content, components);
+            }
+        }
+    }
+}
+/**
+ * Helper: extracts a ComponentBoundary from an ArrowFunctionExpression or FunctionExpression
+ * that has a BlockStatement body.
+ */
+function addComponentFromFunctionNode(name, fnNode, content, components) {
+    const body = fnNode.body;
+    if (body?.type === 'BlockStatement' && body.span) {
+        components.push({
+            name,
+            bodyStart: body.span.start,
+            bodyEnd: body.span.end,
+            hasUseTranslation: content.slice(body.span.start, body.span.end).includes('useTranslation')
+        });
+    }
+}
+// Non-translatable JSX attributes are defined in utils/jsx-attributes.ts
+// and shared with the linter. The instrumenter uses `ignoredAttributeSet`
+// to skip recursing into non-translatable attribute values.
+/**
+ * Recursively visits AST nodes to find string literals.
+ */
+function visitNodeForStrings(node, content, file, config, candidates) {
+    if (!node)
+        return;
+    // Skip non-translatable JSX attributes entirely (e.g. className={...})
+    if (node.type === 'JSXAttribute') {
+        const nameNode = node.name;
+        let attrName = null;
+        if (nameNode?.type === 'Identifier') {
+            attrName = nameNode.value;
+        }
+        else if (nameNode?.type === 'JSXNamespacedName') {
+            // e.g. data-testid
+            attrName = `${nameNode.namespace?.value ?? ''}:${nameNode.name?.value ?? ''}`;
+        }
+        if (attrName && ignoredAttributeSet.has(attrName))
+            return;
+        // For hyphenated names (data-testid), also check with the raw text
+        if (attrName?.includes(':')) {
+            const hyphenated = attrName.replace(':', '-');
+            if (ignoredAttributeSet.has(hyphenated))
+                return;
+        }
+    }
+    // Check if this is a string literal
+    if (node.type === 'StringLiteral') {
+        const stringNode = node;
+        if (stringNode.span && typeof stringNode.span.start === 'number') {
+            const candidate = detectCandidate(stringNode.value, stringNode.span.start, stringNode.span.end, file, content, config);
+            if (candidate && candidate.confidence >= 0.7) {
+                // Detect JSX attribute context: in JSX, attr="value" has = right before the opening quote
+                if (stringNode.span.start > 0 && content[stringNode.span.start - 1] === '=') {
+                    candidate.type = 'jsx-attribute';
+                }
+                candidates.push(candidate);
+            }
+        }
+    }
+    // Template literals
+    if (node.type === 'TemplateLiteral') {
+        const quasis = node.quasis;
+        const expressions = node.expressions;
+        if (quasis?.length === 1 && (!expressions || expressions.length === 0)) {
+            // Static template literal (no interpolation), e.g. `Welcome back`
+            const raw = quasis[0].raw || quasis[0].cooked || '';
+            const trimmed = raw.trim();
+            if (trimmed && node.span && typeof node.span.start === 'number') {
+                const candidate = detectCandidate(trimmed, node.span.start, node.span.end, file, content, config);
+                if (candidate && candidate.confidence >= 0.7) {
+                    candidate.type = 'template-literal';
+                    if (node.span.start > 0 && content[node.span.start - 1] === '=') {
+                        candidate.type = 'jsx-attribute';
+                    }
+                    candidates.push(candidate);
+                }
+            }
+        }
+        else if (quasis?.length > 1 && expressions?.length > 0 && node.span) {
+            // Template literal with interpolation, e.g. `${count}-day streak`
+            const result = buildInterpolatedTemplate(quasis, expressions, content);
+            if (result) {
+                const trimmed = result.text.trim();
+                if (trimmed) {
+                    const candidate = detectCandidate(trimmed, node.span.start, node.span.end, file, content, config);
+                    if (candidate) {
+                        candidate.content = trimmed;
+                        candidate.type = 'template-literal';
+                        candidate.interpolations = result.interpolations;
+                        // Template literals mixing text + expressions are likely user-facing
+                        candidate.confidence = Math.min(1, candidate.confidence + 0.15);
+                        if (node.span.start > 0 && content[node.span.start - 1] === '=') {
+                            candidate.type = 'jsx-attribute';
+                        }
+                        if (candidate.confidence >= 0.7) {
+                            candidates.push(candidate);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Check if this is JSX text content (e.g. <h1>Hello World</h1>)
+    if (node.type === 'JSXText') {
+        if (node.span && typeof node.span.start === 'number') {
+            const raw = content.slice(node.span.start, node.span.end);
+            const trimmed = raw.trim();
+            if (trimmed) {
+                const trimmedStart = raw.indexOf(trimmed);
+                const offset = node.span.start + trimmedStart;
+                const endOffset = offset + trimmed.length;
+                const candidate = detectCandidate(trimmed, offset, endOffset, file, content, config);
+                if (candidate) {
+                    candidate.type = 'jsx-text';
+                    // JSXText is almost always user-visible content; boost confidence
+                    candidate.confidence = Math.min(1, candidate.confidence + 0.2);
+                    if (candidate.confidence >= 0.7) {
+                        candidates.push(candidate);
+                    }
+                }
+            }
+        }
+    }
+    // Recursively visit children
+    for (const key in node) {
+        const value = node[key];
+        if (value && typeof value === 'object') {
+            if (Array.isArray(value)) {
+                value.forEach(item => visitNodeForStrings(item, content, file, config, candidates));
+            }
+            else {
+                visitNodeForStrings(value, content, file, config, candidates);
+            }
+        }
+    }
+}
+// ─── Template-literal interpolation helpers ──────────────────────────────────
+/**
+ * Builds a merged text with `{{var}}` placeholders from a template literal's
+ * quasis and expressions arrays.
+ */
+function buildInterpolatedTemplate(quasis, expressions, content) {
+    const interpolations = [];
+    const usedNames = new Set();
+    let text = '';
+    for (let i = 0; i < quasis.length; i++) {
+        const quasi = quasis[i];
+        text += quasi.cooked ?? quasi.raw ?? '';
+        if (i < expressions.length) {
+            const info = resolveExpressionName(expressions[i], content, usedNames);
+            if (!info)
+                return null; // un-resolvable expression — bail
+            text += `{{${info.name}}}`;
+            interpolations.push(info);
+        }
+    }
+    return interpolations.length > 0 ? { text, interpolations } : null;
+}
+/**
+ * Resolves a human-friendly interpolation name from an AST expression node.
+ *
+ * - `Identifier`        → uses the identifier value (`count`)
+ * - `MemberExpression`  → uses the deepest property name (`profile.name` → `name`)
+ * - anything else       → generated placeholder (`val`, `val2`, ...)
+ */
+function resolveExpressionName(expr, content, usedNames) {
+    if (!expr?.span)
+        return null;
+    const expression = content.slice(expr.span.start, expr.span.end);
+    let baseName;
+    if (expr.type === 'Identifier') {
+        baseName = expr.value;
+    }
+    else if (expr.type === 'MemberExpression' && !expr.computed && expr.property?.type === 'Identifier') {
+        baseName = expr.property.value;
+    }
+    else {
+        baseName = 'val';
+    }
+    let name = baseName;
+    let counter = 2;
+    while (usedNames.has(name)) {
+        name = `${baseName}${counter++}`;
+    }
+    usedNames.add(name);
+    return { name, expression };
+}
+// ─── JSX sibling interpolation merging ───────────────────────────────────────
+/**
+ * Walks the AST looking for JSXElement / JSXFragment nodes whose children
+ * contain a mergeable mix of `JSXText` and `JSXExpressionContainer` with simple
+ * expressions (Identifier / MemberExpression).  When found, a single merged
+ * `CandidateString` is created and any overlapping individual candidates are
+ * removed.
+ */
+function detectJSXInterpolation(node, content, file, config, candidates) {
+    if (!node)
+        return;
+    const children = (node.type === 'JSXElement' || node.type === 'JSXFragment') ? node.children : null;
+    if (children?.length > 1) {
+        // Build "runs" of consecutive JSXText + simple-expression containers
+        const runs = [];
+        let currentRun = [];
+        for (const child of children) {
+            if (child.type === 'JSXText') {
+                currentRun.push(child);
+            }
+            else if (child.type === 'JSXExpressionContainer' && isSimpleJSXExpression(child.expression)) {
+                currentRun.push(child);
+            }
+            else {
+                // JSXElement, complex expression, etc. — break the run
+                if (currentRun.length > 0) {
+                    runs.push(currentRun);
+                    currentRun = [];
+                }
+            }
+        }
+        if (currentRun.length > 0) {
+            runs.push(currentRun);
+        }
+        for (const run of runs) {
+            const hasText = run.some(c => c.type === 'JSXText' && c.value?.trim());
+            const hasExpr = run.some(c => c.type === 'JSXExpressionContainer');
+            if (!hasText || !hasExpr || run.length < 2)
+                continue;
+            // Build the interpolated text from the run
+            const usedNames = new Set();
+            const interpolations = [];
+            let text = '';
+            let valid = true;
+            for (const child of run) {
+                if (child.type === 'JSXText') {
+                    text += content.slice(child.span.start, child.span.end);
+                }
+                else {
+                    const info = resolveExpressionName(child.expression, content, usedNames);
+                    if (!info) {
+                        valid = false;
+                        break;
+                    }
+                    text += `{{${info.name}}}`;
+                    interpolations.push(info);
+                }
+            }
+            if (!valid)
+                continue;
+            const trimmed = text.trim();
+            if (!trimmed || interpolations.length === 0)
+                continue;
+            const spanStart = run[0].span.start;
+            const spanEnd = run[run.length - 1].span.end;
+            const candidate = detectCandidate(trimmed, spanStart, spanEnd, file, content, config);
+            if (candidate) {
+                candidate.type = 'jsx-text';
+                candidate.content = trimmed;
+                candidate.interpolations = interpolations;
+                // Mixed text + expressions in JSX is almost always user-facing
+                candidate.confidence = Math.min(1, candidate.confidence + 0.2);
+                if (candidate.confidence >= 0.7) {
+                    // Remove individual candidates that overlap with the merged span
+                    for (let i = candidates.length - 1; i >= 0; i--) {
+                        if (candidates[i].offset >= spanStart && candidates[i].endOffset <= spanEnd) {
+                            candidates.splice(i, 1);
+                        }
+                    }
+                    candidates.push(candidate);
+                }
+            }
+        }
+    }
+    // Recurse into children
+    for (const key in node) {
+        const value = node[key];
+        if (value && typeof value === 'object') {
+            if (Array.isArray(value)) {
+                value.forEach(item => detectJSXInterpolation(item, content, file, config, candidates));
+            }
+            else {
+                detectJSXInterpolation(value, content, file, config, candidates);
+            }
+        }
+    }
+}
+/**
+ * Returns true when the expression is a simple Identifier or non-computed
+ * MemberExpression (i.e. dot notation like `profile.name`).
+ */
+function isSimpleJSXExpression(expr) {
+    if (!expr)
+        return false;
+    if (expr.type === 'Identifier')
+        return true;
+    if (expr.type === 'MemberExpression' && !expr.computed && expr.property?.type === 'Identifier')
+        return true;
+    return false;
+}
+// ─── Plural conditional pattern detection ────────────────────────────────────
+/**
+ * Extracts the text value from a string literal or static template literal node.
+ * Returns `null` for anything else.
+ */
+function extractStaticText(node) {
+    if (!node)
+        return null;
+    if (node.type === 'StringLiteral')
+        return node.value;
+    if (node.type === 'TemplateLiteral') {
+        const quasis = node.quasis;
+        if (quasis?.length === 1 && (!node.expressions || node.expressions.length === 0)) {
+            return quasis[0].cooked ?? quasis[0].raw ?? null;
+        }
+    }
+    return null;
+}
+/**
+ * Extracts text from a node that may contain the count variable as an
+ * interpolation (e.g. `${activeTasks} tasks left`).  The count variable
+ * is replaced with `{{count}}` in the returned text.
+ * Returns `null` when the node isn't a recognised textual form.
+ */
+function extractTextWithCount(node, countIdentifier, content) {
+    // Static text (no variable at all — still valid for zero/one forms)
+    const staticText = extractStaticText(node);
+    if (staticText !== null)
+        return staticText;
+    // Template literal with interpolation
+    if (node?.type === 'TemplateLiteral') {
+        const quasis = node.quasis ?? [];
+        const expressions = node.expressions ?? [];
+        if (quasis.length === 0 || expressions.length === 0)
+            return null;
+        let text = '';
+        for (let i = 0; i < quasis.length; i++) {
+            text += quasis[i].cooked ?? quasis[i].raw ?? '';
+            if (i < expressions.length) {
+                const expr = expressions[i];
+                const exprText = content.slice(expr.span.start, expr.span.end);
+                if (exprText === countIdentifier) {
+                    text += '{{count}}';
+                }
+                else {
+                    // Unknown expression — bail
+                    return null;
+                }
+            }
+        }
+        return text;
+    }
+    return null;
+}
+/**
+ * Resolves the count variable name from a `BinaryExpression` test of the form
+ * `identifier === <number>`.  Returns `{ identifier, number }` or `null`.
+ */
+function parseCountTest(test, content) {
+    if (test?.type !== 'BinaryExpression')
+        return null;
+    if (test.operator !== '===' && test.operator !== '==')
+        return null;
+    let identSide;
+    let numSide;
+    if (test.left?.type === 'NumericLiteral') {
+        numSide = test.left;
+        identSide = test.right;
+    }
+    else if (test.right?.type === 'NumericLiteral') {
+        numSide = test.right;
+        identSide = test.left;
+    }
+    else {
+        return null;
+    }
+    if (!identSide?.span)
+        return null;
+    const identifier = content.slice(identSide.span.start, identSide.span.end);
+    return { identifier, value: numSide.value };
+}
+/**
+ * Walks the AST looking for conditional (ternary) expression chains that
+ * correspond to a count-based pluralisation pattern, e.g.
+ *
+ * ```
+ * tasks === 0
+ *   ? 'No tasks'
+ *   : tasks === 1
+ *     ? 'One task'
+ *     : `${tasks} tasks`
+ * ```
+ *
+ * When such a pattern is detected a single `CandidateString` is emitted with
+ * `pluralForms` populated and any individual candidates that overlap with the
+ * ternary's span are removed.
+ */
+function detectPluralPatterns(node, content, file, config, candidates) {
+    if (!node)
+        return;
+    if (node.type === 'ConditionalExpression') {
+        const plural = tryParsePluralTernary(node, content);
+        if (plural) {
+            // Use the "other" form as the candidate content (with {{count}})
+            const spanStart = node.span.start;
+            const spanEnd = node.span.end;
+            const candidate = detectCandidate(plural.other, spanStart, spanEnd, file, content, config);
+            if (candidate) {
+                candidate.type = 'string-literal';
+                candidate.content = plural.other;
+                candidate.pluralForms = {
+                    countExpression: plural.countExpression,
+                    zero: plural.zero,
+                    one: plural.one,
+                    other: plural.other
+                };
+                // Plural patterns are always user-facing text — boost confidence
+                candidate.confidence = Math.min(1, candidate.confidence + 0.3);
+                if (candidate.confidence >= 0.7) {
+                    // Remove individual candidates that overlap with the ternary span
+                    for (let i = candidates.length - 1; i >= 0; i--) {
+                        if (candidates[i].offset >= spanStart && candidates[i].endOffset <= spanEnd) {
+                            candidates.splice(i, 1);
+                        }
+                    }
+                    candidates.push(candidate);
+                    // Don't recurse into children — we already consumed the whole ternary
+                    return;
+                }
+            }
+        }
+    }
+    // Recurse into children
+    for (const key in node) {
+        const value = node[key];
+        if (value && typeof value === 'object') {
+            if (Array.isArray(value)) {
+                value.forEach(item => detectPluralPatterns(item, content, file, config, candidates));
+            }
+            else {
+                detectPluralPatterns(value, content, file, config, candidates);
+            }
+        }
+    }
+}
+/**
+ * Attempts to parse a `ConditionalExpression` tree into a plural pattern.
+ *
+ * Supported shapes:
+ *   count === 0 ? zeroText : count === 1 ? oneText : otherText   (3-way)
+ *   count === 1 ? oneText  : otherText                           (2-way)
+ *
+ * Returns `null` when the node doesn't match any recognised plural shape.
+ */
+function tryParsePluralTernary(node, content) {
+    if (node?.type !== 'ConditionalExpression')
+        return null;
+    const outerTest = parseCountTest(node.test, content);
+    if (!outerTest)
+        return null;
+    const countExpr = outerTest.identifier;
+    // ──── 3-way:  count === 0 ? zero : count === 1 ? one : other ──────────
+    if (outerTest.value === 0) {
+        const zeroText = extractTextWithCount(node.consequent, countExpr, content);
+        if (zeroText === null)
+            return null;
+        const alt = node.alternate;
+        if (alt?.type === 'ConditionalExpression') {
+            const innerTest = parseCountTest(alt.test, content);
+            if (!innerTest || innerTest.identifier !== countExpr || innerTest.value !== 1)
+                return null;
+            const oneText = extractTextWithCount(alt.consequent, countExpr, content);
+            const otherText = extractTextWithCount(alt.alternate, countExpr, content);
+            if (oneText === null || otherText === null)
+                return null;
+            return { countExpression: countExpr, zero: zeroText, one: oneText, other: otherText };
+        }
+        // 2-way zero/other:  count === 0 ? zero : other
+        const otherText = extractTextWithCount(node.alternate, countExpr, content);
+        if (otherText === null)
+            return null;
+        return { countExpression: countExpr, zero: zeroText, other: otherText };
+    }
+    // ──── 2-way:  count === 1 ? one : other ───────────────────────────────
+    if (outerTest.value === 1) {
+        const oneText = extractTextWithCount(node.consequent, countExpr, content);
+        const otherText = extractTextWithCount(node.alternate, countExpr, content);
+        if (oneText === null || otherText === null)
+            return null;
+        return { countExpression: countExpr, one: oneText, other: otherText };
+    }
+    return null;
+}
+// ─── Language-change detection ───────────────────────────────────────────────
+/**
+ * Property names that indicate a "language" value in an object literal.
+ * When a function call passes an object with one of these keys, we treat
+ * the call as a language-change site.
+ */
+const LANGUAGE_PROP_NAMES = new Set(['language', 'lang', 'locale', 'lng']);
+/**
+ * Function-name patterns that indicate a direct language setter.
+ * Matched against the full function name (case-insensitive).
+ *
+ * Examples: `setLanguage(code)`, `setLocale(lng)`, `changeLanguage(x)`
+ */
+const LANGUAGE_SETTER_RE = /^(?:set|change|update|select)(?:Language|Lang|Locale|Lng)$/i;
+/**
+ * Walks the AST looking for call expressions that appear to change the
+ * application language.  Detected sites will later be augmented with an
+ * `i18n.changeLanguage()` call by the transformer.
+ *
+ * Recognised patterns:
+ *
+ * 1. Object-property setters:
+ *    `updateSettings({ language: lang.code })`
+ *    `setState({ locale: selectedLng })`
+ *
+ * 2. Direct setters:
+ *    `setLanguage(code)`
+ *    `setLocale(lng)`
+ *    `changeLanguage(selectedLng)`
+ */
+function detectLanguageChangeSites(node, content, sites) {
+    if (!node)
+        return;
+    if (node.type === 'CallExpression' && node.span) {
+        const detected = tryParseLanguageChangeCall(node, content);
+        if (detected) {
+            // Check if changeLanguage() already exists nearby (e.g. same arrow body)
+            const lookbackStart = Math.max(0, detected.callStart - 200);
+            const nearbyBefore = content.slice(lookbackStart, detected.callStart);
+            if (nearbyBefore.includes('changeLanguage')) ;
+            else {
+                // Compute 1-based line and 0-based column from offset
+                let line = 1;
+                let lastNewline = -1;
+                for (let i = 0; i < detected.callStart && i < content.length; i++) {
+                    if (content[i] === '\n') {
+                        line++;
+                        lastNewline = i;
+                    }
+                }
+                sites.push({
+                    ...detected,
+                    line,
+                    column: detected.callStart - lastNewline - 1
+                });
+            }
+            // Don't return — keep recursing for nested calls
+        }
+    }
+    // Recurse into children
+    for (const key in node) {
+        const value = node[key];
+        if (value && typeof value === 'object') {
+            if (Array.isArray(value)) {
+                value.forEach(item => detectLanguageChangeSites(item, content, sites));
+            }
+            else {
+                detectLanguageChangeSites(value, content, sites);
+            }
+        }
+    }
+}
+/**
+ * Inspects a single CallExpression node to determine if it is a language-change
+ * call.  Returns the detected site data (without line/column) or `null`.
+ */
+function tryParseLanguageChangeCall(node, content) {
+    if (node.type !== 'CallExpression')
+        return null;
+    if (!node.arguments?.length)
+        return null;
+    const calleeName = getCalleeName(node.callee);
+    // Skip calls that are already i18next API calls (e.g. i18n.changeLanguage())
+    if (node.callee?.type === 'MemberExpression' && node.callee.object?.type === 'Identifier') {
+        const objName = node.callee.object.value;
+        if (objName === 'i18n' || objName === 'i18next')
+            return null;
+    }
+    // ── Pattern 1: direct setter — setLanguage(expr), changeLocale(expr) etc. ──
+    if (calleeName && LANGUAGE_SETTER_RE.test(calleeName)) {
+        const firstArg = node.arguments[0]?.expression;
+        if (firstArg?.span) {
+            const langExpr = content.slice(firstArg.span.start, firstArg.span.end);
+            // Skip if the argument is already an i18next.changeLanguage call
+            if (langExpr.includes('changeLanguage'))
+                return null;
+            return {
+                languageExpression: langExpr,
+                callStart: node.span.start,
+                callEnd: node.span.end
+            };
+        }
+    }
+    // ── Pattern 2: object with language property — fn({ language: expr }) ──
+    for (const arg of node.arguments) {
+        const expr = arg.expression ?? arg;
+        if (expr?.type !== 'ObjectExpression')
+            continue;
+        if (!Array.isArray(expr.properties))
+            continue;
+        for (const prop of expr.properties) {
+            if (prop.type !== 'KeyValueProperty')
+                continue;
+            const keyName = (prop.key?.type === 'Identifier' && prop.key.value) ||
+                (prop.key?.type === 'StringLiteral' && prop.key.value);
+            if (typeof keyName !== 'string')
+                continue;
+            if (!LANGUAGE_PROP_NAMES.has(keyName.toLowerCase()))
+                continue;
+            // Found a language property — extract the value expression
+            const valNode = prop.value;
+            if (valNode?.span) {
+                const langExpr = content.slice(valNode.span.start, valNode.span.end);
+                // Skip if value is a static string (e.g. `{ language: 'en' }` in a config)
+                if (valNode.type === 'StringLiteral')
+                    continue;
+                // Skip if already contains changeLanguage
+                if (langExpr.includes('changeLanguage'))
+                    continue;
+                return {
+                    languageExpression: langExpr,
+                    callStart: node.span.start,
+                    callEnd: node.span.end
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Extracts a simple function name from a CallExpression callee.
+ * Handles `Identifier` (e.g. `setLanguage`) and `MemberExpression`
+ * (extracts the final property, e.g. `settings.setLanguage` → `setLanguage`).
+ */
+function getCalleeName(callee) {
+    if (!callee)
+        return null;
+    if (callee.type === 'Identifier')
+        return callee.value;
+    if (callee.type === 'MemberExpression' && !callee.computed && callee.property?.type === 'Identifier') {
+        return callee.property.value;
+    }
+    return null;
+}
+/**
+ * Gets the list of source files to instrument.
+ */
+async function getSourceFilesForInstrumentation(config) {
+    const defaultIgnore = ['node_modules/**', 'dist/**', 'build/**', '.next/**'];
+    const userIgnore = Array.isArray(config.extract.ignore)
+        ? config.extract.ignore
+        : config.extract.ignore ? [config.extract.ignore] : [];
+    return await glob(config.extract.input, {
+        ignore: [...defaultIgnore, ...userIgnore],
+        cwd: process.cwd()
+    });
+}
+/**
+ * Checks if the project uses React.
+ */
+async function isProjectUsingReact() {
+    try {
+        const packageJsonPath = process.cwd() + '/package.json';
+        const content = await readFile(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(content);
+        const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+        return !!deps.react || !!deps['react-i18next'];
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if the project uses TypeScript (looks for tsconfig.json).
+ */
+async function isProjectUsingTypeScript() {
+    try {
+        await access(process.cwd() + '/tsconfig.json');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if a file exists.
+ */
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Common i18n init file names to check for.
+ */
+const I18N_INIT_FILE_NAMES = [
+    'i18n.ts', 'i18n.js', 'i18n.mjs', 'i18n.mts',
+    'i18next.ts', 'i18next.js', 'i18next.mjs', 'i18next.mts',
+    'i18n/index.ts', 'i18n/index.js', 'i18n/index.mjs',
+    'i18next/index.ts', 'i18next/index.js'
+];
+/**
+ * Computes a POSIX-style relative path from the init-file directory to the
+ * output template path (which still contains {{language}} / {{namespace}} placeholders).
+ */
+function buildDynamicImportPath(outputTemplate, initDir) {
+    const cwd = process.cwd();
+    const absTemplate = isAbsolute(outputTemplate) ? outputTemplate : resolve(cwd, outputTemplate);
+    let rel = relative(initDir, absTemplate);
+    if (!rel.startsWith('.')) {
+        rel = './' + rel;
+    }
+    return rel.replace(/\\/g, '/');
+}
+/**
+ * Ensures that an i18n initialization file exists in the project.
+ * If no existing init file is found, generates a sensible default.
+ *
+ * When extract.output is a string template, the generated file uses
+ * i18next-resources-to-backend with a dynamic import derived from the
+ * output path — making i18next ready to load translations out of the box.
+ *
+ * For React projects: creates i18n.ts with react-i18next integration.
+ * For non-React projects: creates i18n.ts with basic i18next init.
+ */
+async function ensureI18nInitFile(hasReact, hasTypeScript, config, logger) {
+    const cwd = process.cwd();
+    // Check for existing init files in common locations
+    const searchDirs = ['src', '.'];
+    for (const dir of searchDirs) {
+        for (const name of I18N_INIT_FILE_NAMES) {
+            if (await fileExists(join(cwd, dir, name))) {
+                return null; // Init file already exists
+            }
+        }
+    }
+    // Check if i18next.init() is called anywhere in the source
+    try {
+        const sourceFiles = await getSourceFilesForInstrumentation(config);
+        for (const file of sourceFiles) {
+            try {
+                const content = await readFile(file, 'utf-8');
+                if (content.includes('i18next.init') || content.includes('.init(') || content.includes('i18n.init')) {
+                    return null; // Init is already present somewhere
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+    }
+    catch {
+        // Skip if file scanning fails
+    }
+    // Determine output location — prefer src/ if it exists
+    const srcExists = await fileExists(join(cwd, 'src'));
+    const initDir = srcExists ? join(cwd, 'src') : cwd;
+    const initFileExt = hasTypeScript ? '.ts' : '.js';
+    const initFilePath = join(initDir, 'i18n' + initFileExt);
+    const primaryLang = config.extract.primaryLanguage ?? config.locales[0] ?? 'en';
+    const defaultNS = config.extract.defaultNS !== false ? (config.extract.defaultNS || 'translation') : null;
+    // Build the .init({...}) options block
+    const initOptions = [
+        '    returnEmptyString: false, // allows empty string as valid translation',
+        `    // lng: ${config.locales.at(-1)}, // or add a language detector to detect the preferred language of your user`,
+        `    fallbackLng: '${primaryLang}'`,
+    ];
+    if (defaultNS) {
+        initOptions.push(`    defaultNS: '${defaultNS}'`);
+    }
+    const initBlock = initOptions.join(',\n');
+    let initContent;
+    if (typeof config.extract.output === 'string') {
+        // Derive a dynamic import path so the generated init file loads translations automatically
+        const dynamicImportPath = buildDynamicImportPath(config.extract.output, initDir);
+        const importPathTemplate = dynamicImportPath
+            // eslint-disable-next-line no-template-curly-in-string
+            .replace(/\{\{language\}\}|\{\{lng\}\}/g, '${language}')
+            // eslint-disable-next-line no-template-curly-in-string
+            .replace(/\{\{namespace\}\}/g, '${namespace}');
+        const hasNamespace = config.extract.output.includes('{{namespace}}');
+        const callbackParams = hasNamespace ? hasTypeScript ? 'language: string, namespace: string' : 'language, namespace' : hasTypeScript ? 'language: string' : 'language';
+        const backendUseLine = '  .use(resourcesToBackend((' + callbackParams + ') => import(`' + importPathTemplate + '`)))';
+        if (hasReact) {
+            initContent = `// Generated by i18next-cli — review and adapt to your project's needs.
+// You may need to install dependencies: npm install i18next react-i18next i18next-resources-to-backend
+//
+// Other translation loading approaches:
+//   • Static imports or bundled JSON: https://www.i18next.com/how-to/add-or-load-translations
+//   • Lazy-load from a server: https://github.com/i18next/i18next-http-backend
+//   • Manage translations with your team via Locize: https://www.locize.com
+//     (see i18next-locize-backend: https://github.com/locize/i18next-locize-backend)
+import i18next from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import resourcesToBackend from 'i18next-resources-to-backend'
+
+i18next
+  .use(initReactI18next)
+${backendUseLine}
+  .init({
+${initBlock}
+  })
+
+export default i18next
+`;
+        }
+        else {
+            initContent = `// Generated by i18next-cli — review and adapt to your project's needs.
+// You may need to install the dependency: npm install i18next i18next-resources-to-backend
+//
+// Other translation loading approaches:
+//   • Static imports or bundled JSON: https://www.i18next.com/how-to/add-or-load-translations
+//   • Lazy-load from a server: https://github.com/i18next/i18next-http-backend
+//   • Manage translations with your team via Locize: https://www.locize.com
+//     (see i18next-locize-backend: https://github.com/locize/i18next-locize-backend)
+import i18next from 'i18next'
+import resourcesToBackend from 'i18next-resources-to-backend'
+
+i18next
+${backendUseLine}
+  .init({
+${initBlock}
+  })
+
+export default i18next
+`;
+        }
+    }
+    else {
+        // Output is a function — can't derive import path, fall back to comments only
+        if (hasReact) {
+            initContent = `// Generated by i18next-cli — review and adapt to your project's needs.
+// You may need to install dependencies: npm install i18next react-i18next
+//
+// Loading translations:
+//   • Static imports or bundled JSON: https://www.i18next.com/how-to/add-or-load-translations
+//   • Lazy-load in memory with dynamic imports: https://github.com/i18next/i18next-resources-to-backend
+//   • Lazy-load from a backend: https://github.com/i18next/i18next-http-backend
+//   • Manage translations with your team via Locize: https://www.locize.com
+//     (see i18next-locize-backend: https://github.com/locize/i18next-locize-backend)
+import i18next from 'i18next'
+import { initReactI18next } from 'react-i18next'
+
+i18next
+  .use(initReactI18next)
+  .init({
+    returnEmptyString: false, // allows empty string as valid translation
+    // lng: ${config.locales.at(-1)}, // or add a language detector to detect the preferred language of your user
+    fallbackLng: '${primaryLang}'
+    // resources: { ... }  — or use a backend plugin to load translations
+  })
+
+export default i18next
+`;
+        }
+        else {
+            initContent = `// Generated by i18next-cli — review and adapt to your project's needs.
+// You may need to install the dependency: npm install i18next
+//
+// Loading translations:
+//   • Static imports or bundled JSON: https://www.i18next.com/how-to/add-or-load-translations
+//   • Lazy-load in memory with dynamic imports: https://github.com/i18next/i18next-resources-to-backend
+//   • Lazy-load from a backend: https://github.com/i18next/i18next-http-backend
+//   • Manage translations with your team via Locize: https://www.locize.com
+//     (see i18next-locize-backend: https://github.com/locize/i18next-locize-backend)
+import i18next from 'i18next'
+
+i18next.init({
+  returnEmptyString: false, // allows empty string as valid translation
+  // lng: ${config.locales.at(-1)}, // or add a language detector to detect the preferred language of your user
+  fallbackLng: '${primaryLang}'
+  // resources: { ... }  — or use a backend plugin to load translations
+})
+
+export default i18next
+`;
+        }
+    }
+    try {
+        await mkdir(initDir, { recursive: true });
+        await writeFile(initFilePath, initContent);
+        logger.info(`Generated i18n init file: ${initFilePath}`);
+        return initFilePath;
+    }
+    catch (err) {
+        logger.warn(`Failed to generate i18n init file: ${err}`);
+        return null;
+    }
+}
+/**
+ * Common entry-point file names, checked in priority order.
+ */
+const ENTRY_FILE_CANDIDATES = [
+    'src/main.tsx', 'src/main.ts', 'src/main.jsx', 'src/main.js',
+    'src/index.tsx', 'src/index.ts', 'src/index.jsx', 'src/index.js',
+    'src/App.tsx', 'src/App.ts', 'src/App.jsx', 'src/App.js',
+    'pages/_app.tsx', 'pages/_app.ts', 'pages/_app.jsx', 'pages/_app.js',
+    'app/layout.tsx', 'app/layout.ts', 'app/layout.jsx', 'app/layout.js',
+    'index.tsx', 'index.ts', 'index.jsx', 'index.js',
+    'main.tsx', 'main.ts', 'main.jsx', 'main.js'
+];
+/**
+ * Attempts to inject a side-effect import of the i18n init file into the
+ * project's main entry file.  If no recognisable entry file is found, or the
+ * import already exists, the function silently returns.
+ */
+async function injectI18nImportIntoEntryFile(initFilePath, logger) {
+    const cwd = process.cwd();
+    // 1. Find the first existing entry file
+    let entryFilePath = null;
+    for (const candidate of ENTRY_FILE_CANDIDATES) {
+        const abs = join(cwd, candidate);
+        if (await fileExists(abs)) {
+            entryFilePath = abs;
+            break;
+        }
+    }
+    if (!entryFilePath) {
+        logger.info('No recognisable entry file found — please import the i18n init file manually.');
+        return;
+    }
+    // 2. Compute the relative import path (POSIX-style, without extension)
+    const entryDir = dirname(entryFilePath);
+    let rel = relative(entryDir, initFilePath).replace(/\\/g, '/');
+    // Strip file extension for a cleaner import
+    rel = rel.replace(/\.(tsx?|jsx?|mjs|mts)$/, '');
+    if (!rel.startsWith('.')) {
+        rel = './' + rel;
+    }
+    // 3. Check whether the import is already present
+    let content;
+    try {
+        content = await readFile(entryFilePath, 'utf-8');
+    }
+    catch {
+        logger.warn(`Could not read entry file: ${entryFilePath}`);
+        return;
+    }
+    // Check for existing import of the i18n init file (with or without extension)
+    const importBase = rel.replace(/^\.\//, '');
+    const importPatterns = [
+        `import '${rel}'`, `import "${rel}"`,
+        `import './${importBase}'`, `import "./${importBase}"`,
+        `import '${rel}.`, `import "${rel}.`,
+        // Also check for require or named imports
+        `from '${rel}'`, `from "${rel}"`,
+        `from './${importBase}'`, `from "./${importBase}"`,
+        // Bare 'i18n' import
+        "import './i18n'", 'import "./i18n"',
+        "import '../i18n'", 'import "../i18n"',
+        "from './i18n'", 'from "./i18n"',
+        "from '../i18n'", 'from "../i18n"'
+    ];
+    for (const pattern of importPatterns) {
+        if (content.includes(pattern)) {
+            return; // Already imported
+        }
+    }
+    // 4. Insert the import at the top, right after any existing import block
+    const importStatement = `import '${rel}'\n`;
+    // Find the best insertion point: after the last top-level import statement
+    const lines = content.split('\n');
+    let lastImportLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trimStart();
+        if (trimmed.startsWith('import ') || trimmed.startsWith('import\t') || trimmed.startsWith('import{')) {
+            // Walk past multi-line imports
+            lastImportLine = i;
+        }
+    }
+    let newContent;
+    if (lastImportLine >= 0) {
+        // Insert after the last import line
+        lines.splice(lastImportLine + 1, 0, importStatement.trimEnd());
+        newContent = lines.join('\n');
+    }
+    else {
+        // No imports found — prepend at the very top
+        newContent = importStatement + content;
+    }
+    try {
+        await writeFile(entryFilePath, newContent);
+        logger.info(`Injected i18n import into entry file: ${entryFilePath}`);
+    }
+    catch (err) {
+        logger.warn(`Failed to inject i18n import into entry file: ${err}`);
+    }
+}
+/**
+ * Extracts and writes translation keys discovered during instrumentation.
+ */
+async function writeExtractedKeys(candidates, config, namespace, logger = new ConsoleLogger()) {
+    if (candidates.length === 0)
+        return;
+    const primaryLanguage = config.extract.primaryLanguage ?? config.locales[0] ?? 'en';
+    const ns = namespace ?? config.extract.defaultNS ?? 'translation';
+    // Build a map of keys from candidates
+    const translations = {};
+    for (const candidate of candidates) {
+        if (candidate.key) {
+            if (candidate.pluralForms) {
+                // Write separate plural-suffix entries for i18next
+                const pf = candidate.pluralForms;
+                if (pf.zero != null) {
+                    translations[`${candidate.key}_zero`] = pf.zero;
+                }
+                if (pf.one != null) {
+                    translations[`${candidate.key}_one`] = pf.one;
+                }
+                translations[`${candidate.key}_other`] = pf.other;
+            }
+            else {
+                translations[candidate.key] = candidate.content;
+            }
+        }
+    }
+    if (Object.keys(translations).length === 0)
+        return;
+    // Get the output path
+    const outputPath = getOutputPath(config.extract.output, primaryLanguage, typeof ns === 'string' ? ns : 'translation');
+    try {
+        // Load existing translations
+        let existingContent = {};
+        try {
+            const content = await readFile(outputPath, 'utf-8');
+            existingContent = JSON.parse(content);
+        }
+        catch {
+            existingContent = {};
+        }
+        // Merge with new translations
+        const merged = { ...existingContent, ...translations };
+        // Write the file
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, JSON.stringify(merged, null, 2));
+        logger.info(`Updated ${outputPath}`);
+    }
+    catch (err) {
+        logger.warn(`Failed to write translated keys: ${err}`);
+    }
+}
+// ─── Plugin pipeline helpers ───────────────────────────────────────────────
+/**
+ * Normalizes a file extension to lowercase with a leading dot.
+ */
+function normalizeExtension(ext) {
+    const trimmed = ext.trim().toLowerCase();
+    if (!trimmed)
+        return '';
+    return trimmed.startsWith('.') ? trimmed : `.${trimmed}`;
+}
+/**
+ * Checks whether an instrument plugin should run for a given file,
+ * based on its `instrumentExtensions` hint.
+ */
+function shouldRunInstrumentPluginForFile(plugin, filePath) {
+    const hints = plugin.instrumentExtensions;
+    if (!hints || hints.length === 0)
+        return true;
+    const fileExt = normalizeExtension(extname(filePath));
+    if (!fileExt)
+        return false;
+    const normalizedHints = hints.map(h => normalizeExtension(h)).filter(Boolean);
+    if (normalizedHints.length === 0)
+        return true;
+    return normalizedHints.includes(fileExt);
+}
+/**
+ * Runs `instrumentSetup` for every plugin that implements it.
+ */
+async function initializeInstrumentPlugins(plugins, context) {
+    for (const plugin of plugins) {
+        try {
+            await plugin.instrumentSetup?.(context);
+        }
+        catch (err) {
+            context.logger.warn(`Plugin ${plugin.name} instrumentSetup failed:`, err);
+        }
+    }
+}
+/**
+ * Runs the `instrumentOnLoad` pipeline for a file.
+ * Returns `null` if a plugin wants to skip the file, otherwise the
+ * (possibly transformed) source code.
+ */
+async function runInstrumentOnLoadPipeline(initialCode, filePath, plugins, logger) {
+    let code = initialCode;
+    for (const plugin of plugins) {
+        if (!shouldRunInstrumentPluginForFile(plugin, filePath))
+            continue;
+        try {
+            const result = await plugin.instrumentOnLoad?.(code, filePath);
+            if (result === null)
+                return null;
+            if (typeof result === 'string')
+                code = result;
+        }
+        catch (err) {
+            logger.warn(`Plugin ${plugin.name} instrumentOnLoad failed:`, err);
+        }
+    }
+    return code;
+}
+/**
+ * Runs the `instrumentOnResult` pipeline for a file's candidates.
+ * Returns the (possibly modified) array of candidates.
+ */
+async function runInstrumentOnResultPipeline(filePath, initialCandidates, plugins, logger) {
+    let candidates = initialCandidates;
+    for (const plugin of plugins) {
+        if (!shouldRunInstrumentPluginForFile(plugin, filePath))
+            continue;
+        try {
+            const result = await plugin.instrumentOnResult?.(filePath, candidates);
+            if (Array.isArray(result)) {
+                candidates = result;
+            }
+        }
+        catch (err) {
+            logger.warn(`Plugin ${plugin.name} instrumentOnResult failed:`, err);
+        }
+    }
+    return candidates;
+}
+// ─── Byte → char offset helpers ────────────────────────────────────────────
+/**
+ * Builds a lookup table from UTF-8 byte offsets to JavaScript string character
+ * indices (UTF-16 code-unit positions).
+ *
+ * SWC internally represents source as UTF-8 and reports AST spans as byte
+ * offsets into that representation.  MagicString and all JavaScript String
+ * methods operate on UTF-16 code-unit indices.  For files that contain only
+ * ASCII characters the two coincide, so this function returns `null` as a
+ * fast path.  For files with multi-byte characters (emoji, accented letters,
+ * CJK, etc.) the returned array allows O(1) conversion of any byte offset.
+ */
+function buildByteToCharMap(content) {
+    // Fast path: pure ASCII means byte offset ≡ char index
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(content))
+        return null;
+    const map = [];
+    let byteIdx = 0;
+    for (let charIdx = 0; charIdx < content.length;) {
+        const cp = content.codePointAt(charIdx);
+        const byteLen = cp <= 0x7F ? 1 : cp <= 0x7FF ? 2 : cp <= 0xFFFF ? 3 : 4;
+        const charLen = cp > 0xFFFF ? 2 : 1; // surrogate pair
+        // Every byte belonging to this character maps to the same char index
+        for (let b = 0; b < byteLen; b++) {
+            map[byteIdx + b] = charIdx;
+        }
+        byteIdx += byteLen;
+        charIdx += charLen;
+    }
+    // Sentinel so that span.end (one-past-the-last-byte) resolves correctly
+    map[byteIdx] = content.length;
+    return map;
+}
+/**
+ * Recursively converts every `span.start` / `span.end` in an SWC AST from
+ * UTF-8 byte offsets to JavaScript string character indices using the
+ * pre-built lookup table.
+ */
+function convertSpansToCharIndices(node, byteToChar) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (node.span && typeof node.span.start === 'number') {
+        const charStart = byteToChar[node.span.start];
+        const charEnd = byteToChar[node.span.end];
+        if (charStart !== undefined && charEnd !== undefined) {
+            node.span = { ...node.span, start: charStart, end: charEnd };
+        }
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'span')
+            continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const item of child) {
+                if (item && typeof item === 'object') {
+                    convertSpansToCharIndices(item, byteToChar);
+                }
+            }
+        }
+        else if (child && typeof child === 'object') {
+            convertSpansToCharIndices(child, byteToChar);
+        }
+    }
+}
+
+export { runInstrumenter, writeExtractedKeys };