i18next-cli 1.47.7 → 1.47.9

package/dist/cjs/cli.js

@@ -31,7 +31,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.47.7'); // This string is replaced with the actual version at build time by rollup
+    .version('1.47.9'); // This string is replaced with the actual version at build time by rollup
 // new: global config override option
 program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
 program

package/dist/cjs/instrumenter/core/instrumenter.js

@@ -39,6 +39,7 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
         let totalTransformed = 0;
         let totalSkipped = 0;
         let totalLanguageChanges = 0;
+        let usesI18nextT = false;
         // Detect framework and language
         const hasReact = await isProjectUsingReact();
         const hasTypeScript = await isProjectUsingTypeScript();
@@ -157,6 +158,10 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
                     totalTransformed += transformResult.transformCount;
                     totalLanguageChanges += transformResult.languageChangeCount;
                     totalSkipped += candidates.length - approvedCandidates.length;
+                    // Track whether any non-component candidate was transformed (i.e. i18next.t() was used)
+                    if (!usesI18nextT && approvedCandidates.some(c => !c.insideComponent && c.confidence >= 0.7)) {
+                        usesI18nextT = true;
+                    }
                     // Log any warnings (e.g. i18next.t() in React files)
                     if (transformResult.warnings?.length) {
                         for (const warning of transformResult.warnings) {
@@ -181,7 +186,7 @@ async function runInstrumenter(config, options, logger$1 = new logger.ConsoleLog
         spinner.succeed(node_util.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$1);
+            const initFilePath = await ensureI18nInitFile(hasReact, hasTypeScript, config, logger$1, usesI18nextT);
             if (initFilePath) {
                 await injectI18nImportIntoEntryFile(initFilePath, logger$1);
             }
@@ -454,12 +459,41 @@ function addComponentFromFunctionNode(name, fnNode, content, components) {
 // 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.
+/**
+ * Returns true when the AST node is a `t(...)` or `i18next.t(...)` call
+ * expression — i.e. code that was already instrumented.
+ */
+function isTranslationCall(node) {
+    const callee = node.callee;
+    if (!callee)
+        return false;
+    // t(...)
+    if (callee.type === 'Identifier' && callee.value === 't')
+        return true;
+    // i18next.t(...)
+    if (callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        callee.property?.type === 'Identifier' &&
+        callee.property.value === 't' &&
+        callee.object?.type === 'Identifier' &&
+        callee.object.value === 'i18next')
+        return true;
+    return false;
+}
 /**
  * Recursively visits AST nodes to find string literals.
  */
 function visitNodeForStrings(node, content, file, config, candidates) {
     if (!node)
         return;
+    // Skip already-instrumented t() / i18next.t() calls entirely so that
+    // strings inside the options object (defaultValue_one, etc.) are not
+    // picked up as new candidates on a second run.
+    if (node.type === 'CallExpression' && isTranslationCall(node))
+        return;
+    // Skip <Trans> elements (already instrumented)
+    if (node.type === 'JSXElement' && isTransComponent(node))
+        return;
     // Skip non-translatable JSX attributes entirely (e.g. className={...})
     if (node.type === 'JSXAttribute') {
         const nameNode = node.name;
@@ -633,6 +667,9 @@ function resolveExpressionName(expr, content, usedNames) {
 function detectJSXInterpolation(node, content, file, config, candidates) {
     if (!node)
         return;
+    // Skip <Trans> elements (already instrumented)
+    if (node.type === 'JSXElement' && isTransComponent(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
@@ -651,6 +688,10 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
                 // Plural ternary expression — include in the run for merged handling
                 currentRun.push(child);
             }
+            else if (child.type === 'JSXElement' && isSimpleJSXElement(child)) {
+                // Simple HTML element — include in the run for Trans detection
+                currentRun.push(child);
+            }
             else {
                 // JSXElement, complex expression, etc. — break the run
                 if (currentRun.length > 0) {
@@ -665,7 +706,11 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
         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)
+            const hasElement = run.some(c => c.type === 'JSXElement');
+            // Require at least one text node plus either an expression or element
+            if (!hasText || run.length < 2)
+                continue;
+            if (!hasExpr && !hasElement)
                 continue;
             // Check if any expression container in this run is a plural ternary
             let pluralChild = null;
@@ -681,7 +726,77 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
                     }
                 }
             }
-            if (pluralChild && pluralData) {
+            if (hasElement) {
+                // ── JSX sibling run with nested HTML elements → <Trans> ──
+                const spanStart = run[0].span.start;
+                const spanEnd = run[run.length - 1].span.end;
+                // Build the translation string (with indexed tags) and text-only version (for scoring)
+                const usedNames = new Set();
+                const interpolations = [];
+                let transValue = '';
+                let textOnly = '';
+                let transContent = '';
+                let childIndex = 0;
+                let valid = true;
+                for (const child of run) {
+                    if (child.type === 'JSXText') {
+                        const raw = content.slice(child.span.start, child.span.end);
+                        transValue += raw;
+                        textOnly += raw;
+                        transContent += raw;
+                        childIndex++;
+                    }
+                    else if (child.type === 'JSXExpressionContainer') {
+                        const info = resolveExpressionName(child.expression, content, usedNames);
+                        if (!info) {
+                            valid = false;
+                            break;
+                        }
+                        transValue += `{{${info.name}}}`;
+                        textOnly += info.name;
+                        // In <Trans> children, simple expressions become {{ obj }} syntax
+                        const objExpr = info.name === info.expression ? info.name : `${info.name}: ${info.expression}`;
+                        transContent += `{{ ${objExpr} }}`;
+                        interpolations.push(info);
+                        childIndex++;
+                    }
+                    else if (child.type === 'JSXElement') {
+                        const innerText = getJSXElementTextContent(child, content);
+                        transValue += `<${childIndex}>${innerText}</${childIndex}>`;
+                        textOnly += innerText;
+                        // Keep the original JSX element source for the <Trans> children
+                        transContent += content.slice(child.span.start, child.span.end);
+                        childIndex++;
+                    }
+                }
+                if (!valid)
+                    continue;
+                const trimmedText = textOnly.trim();
+                const trimmedTransValue = transValue.trim();
+                if (!trimmedText || !trimmedTransValue)
+                    continue;
+                const candidate = stringDetector.detectCandidate(trimmedText, spanStart, spanEnd, file, content, config);
+                if (candidate) {
+                    candidate.type = 'jsx-mixed';
+                    candidate.content = transContent.trim();
+                    candidate.transValue = trimmedTransValue;
+                    if (interpolations.length > 0) {
+                        candidate.interpolations = interpolations;
+                    }
+                    // Mixed text + elements in JSX is almost always user-facing
+                    candidate.confidence = Math.min(1, candidate.confidence + 0.25);
+                    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);
+                    }
+                }
+            }
+            else if (pluralChild && pluralData) {
                 // ── JSX sibling run with embedded plural ternary ──
                 const countExpr = pluralData.countExpression;
                 // Resolve names for non-count, non-plural expressions
@@ -768,7 +883,7 @@ function detectJSXInterpolation(node, content, file, config, candidates) {
                 }
             }
             else {
-                // ── Original JSX sibling merging (no plural) ──
+                // ── Original JSX sibling merging (text + expressions, no elements) ──
                 // Build the interpolated text from the run
                 const usedNames = new Set();
                 const interpolations = [];
@@ -841,6 +956,59 @@ function isSimpleJSXExpression(expr) {
         return true;
     return false;
 }
+/**
+ * Returns true when a JSXElement is "simple" enough to be included in a
+ * `<Trans>` JSX sibling run.  Accepts:
+ * - Self-closing elements (`<br />`, `<img />`)
+ * - Elements whose only children are `JSXText` nodes
+ * Only HTML-like elements (lowercase tag name) are accepted; React
+ * components (uppercase, e.g. `<Button />`) break the run.
+ */
+function isSimpleJSXElement(node) {
+    if (node.type !== 'JSXElement')
+        return false;
+    const namePart = node.opening?.name;
+    if (!namePart)
+        return false;
+    // Only include HTML-like elements (lowercase first char)
+    let tagName = null;
+    if (namePart.type === 'Identifier') {
+        tagName = namePart.value;
+    }
+    if (!tagName || tagName[0] !== tagName[0].toLowerCase())
+        return false;
+    // Self-closing elements are simple
+    if (node.opening?.selfClosing)
+        return true;
+    // Elements with only text children (or empty) are simple
+    const children = node.children || [];
+    return children.length === 0 || children.every((c) => c.type === 'JSXText');
+}
+/**
+ * Returns the text content of a simple JSXElement's children.
+ */
+function getJSXElementTextContent(node, content) {
+    const children = node.children || [];
+    return children
+        .filter((c) => c.type === 'JSXText')
+        .map((c) => content.slice(c.span.start, c.span.end))
+        .join('');
+}
+/**
+ * Returns true when a JSXElement is a `<Trans>` component
+ * (already instrumented content).
+ */
+function isTransComponent(node) {
+    const opening = node.opening;
+    if (!opening)
+        return false;
+    const name = opening.name;
+    if (name?.type === 'Identifier' && name.value === 'Trans')
+        return true;
+    if (name?.type === 'JSXMemberExpression' && name.property?.type === 'Identifier' && name.property.value === 'Trans')
+        return true;
+    return false;
+}
 // ─── Plural conditional pattern detection ────────────────────────────────────
 /**
  * Extracts the text value from a string literal or static template literal node.
@@ -1221,6 +1389,70 @@ async function isProjectUsingReact() {
         return false;
     }
 }
+/** Well-known frontend framework packages (presence → browser environment). */
+const FRONTEND_FRAMEWORKS = [
+    'react', 'react-i18next', 'vue', 'vue-i18next',
+    '@angular/core', 'angular-i18next',
+    'svelte', 'svelte-i18next',
+    'preact', 'solid-js', 'jquery', 'lit', 'ember-source', 'stimulus',
+    'next', 'nuxt', 'gatsby', '@remix-run/react', 'astro'
+];
+/** Well-known bundlers whose presence implies a browser build target. */
+const BUNDLERS = [
+    'webpack', 'vite', '@vitejs/plugin-react', 'rollup', 'parcel',
+    'esbuild', 'turbopack', 'snowpack'
+];
+/** Edge/serverless markers (no filesystem access). */
+const EDGE_MARKERS = [
+    '@cloudflare/workers-types', 'wrangler', '@cloudflare/next-on-pages',
+    '@vercel/edge', '@netlify/edge-functions', '@deno/kv'
+];
+/** Well-known Node.js server frameworks. */
+const SERVER_FRAMEWORKS = [
+    'express', 'fastify', 'koa', 'hapi', '@hapi/hapi',
+    '@nestjs/core', 'restify', 'micro', 'polka', 'h3'
+];
+/**
+ * Analyses `package.json` dependencies (and a few project-root files) to
+ * classify the project's runtime environment.
+ *
+ * Priority order:
+ *   1. Edge / serverless markers  → `'edge'`   (no filesystem)
+ *   2. Frontend framework or bundler → `'browser'`
+ *   3. Node.js server framework   → `'node-server'`
+ *   4. Fallback                   → `'unknown'`
+ */
+async function detectProjectEnvironment() {
+    try {
+        const packageJsonPath = process.cwd() + '/package.json';
+        const raw = await promises.readFile(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(raw);
+        const allDeps = {
+            ...packageJson.dependencies,
+            ...packageJson.devDependencies
+        };
+        const has = (list) => list.some(dep => !!allDeps[dep]);
+        // 1. Edge / serverless (check first — these projects may also list a
+        //    bundler or even a framework, but they have no filesystem)
+        if (has(EDGE_MARKERS))
+            return 'edge';
+        // Also check for wrangler.toml / wrangler.json
+        const cwd = process.cwd();
+        if (await fileExists(node_path.join(cwd, 'wrangler.toml')) || await fileExists(node_path.join(cwd, 'wrangler.json'))) {
+            return 'edge';
+        }
+        // 2. Browser / frontend
+        if (has(FRONTEND_FRAMEWORKS) || has(BUNDLERS))
+            return 'browser';
+        // 3. Node.js server
+        if (has(SERVER_FRAMEWORKS))
+            return 'node-server';
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 /**
  * Checks if the project uses TypeScript (looks for tsconfig.json).
  */
@@ -1271,14 +1503,12 @@ function buildDynamicImportPath(outputTemplate, initDir) {
  * 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.
+ * The generated file's backend strategy depends on the project context:
+ * - React app without i18next.t() → `i18next-resources-to-backend` (async dynamic imports)
+ * - React app with i18next.t()    → bundled resources (static imports, synchronous)
+ * - Server-side (no React)        → `i18next-fs-backend` (filesystem, initImmediate: false + preload)
  */
-async function ensureI18nInitFile(hasReact, hasTypeScript, config, logger) {
+async function ensureI18nInitFile(hasReact, hasTypeScript, config, logger, usesI18nextT) {
     const cwd = process.cwd();
     // Check for existing init files in common locations
     const searchDirs = ['src', '.'];
@@ -1312,125 +1542,17 @@ async function ensureI18nInitFile(hasReact, hasTypeScript, config, logger) {
     const initDir = srcExists ? node_path.join(cwd, 'src') : cwd;
     const initFileExt = hasTypeScript ? '.ts' : '.js';
     const initFilePath = node_path.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
-`;
-        }
-    }
+    const environment = await detectProjectEnvironment();
+    const strategy = determineBackendStrategy(environment, usesI18nextT);
+    const outputTemplate = typeof config.extract.output === 'string' ? config.extract.output : null;
+    const initContent = buildInitFileContent({
+        strategy,
+        hasReact,
+        hasTypeScript,
+        config,
+        initDir,
+        outputTemplate
+    });
     try {
         await promises.mkdir(initDir, { recursive: true });
         await promises.writeFile(initFilePath, initContent);
@@ -1442,6 +1564,171 @@ export default i18next
         return null;
     }
 }
+/**
+ * Determines which backend strategy to use for the i18n init file.
+ *
+ * Decision logic:
+ *   1. Node.js server with filesystem → `fs-backend`
+ *      (synchronous with `initImmediate: false` + `preload`)
+ *   2. Browser / edge / unknown with `i18next.t()` outside React components →
+ *      `bundled-resources` (static imports so resources are available synchronously)
+ *   3. Otherwise → `resources-to-backend` (async dynamic imports, lazy-loaded)
+ */
+function determineBackendStrategy(environment, usesI18nextT) {
+    if (environment === 'node-server')
+        return 'fs-backend';
+    if (usesI18nextT)
+        return 'bundled-resources';
+    return 'resources-to-backend';
+}
+/**
+ * Builds the full i18n init file content from composable parts,
+ * avoiding repetition across different strategies.
+ */
+function buildInitFileContent(opts) {
+    const { strategy, hasReact, hasTypeScript, config, initDir, outputTemplate } = opts;
+    const primaryLang = config.extract.primaryLanguage ?? config.locales[0] ?? 'en';
+    const defaultNS = config.extract.defaultNS !== false ? (config.extract.defaultNS || 'translation') : null;
+    const ns = defaultNS || 'translation';
+    // ── Dependencies for the install hint ──
+    const deps = ['i18next'];
+    if (hasReact)
+        deps.push('react-i18next');
+    if (strategy === 'resources-to-backend' && outputTemplate)
+        deps.push('i18next-resources-to-backend');
+    if (strategy === 'fs-backend' && outputTemplate)
+        deps.push('i18next-fs-backend');
+    const lines = [];
+    // ── Header comment ──
+    lines.push("// Generated by i18next-cli — review and adapt to your project's needs.", `// You may need to install dependencies: npm install ${deps.join(' ')}`, '//', '// 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 declarations ──
+    lines.push("import i18next from 'i18next'");
+    if (hasReact)
+        lines.push("import { initReactI18next } from 'react-i18next'");
+    if (outputTemplate) {
+        switch (strategy) {
+            case 'resources-to-backend':
+                lines.push("import resourcesToBackend from 'i18next-resources-to-backend'");
+                break;
+            case 'bundled-resources':
+                for (const locale of config.locales) {
+                    const importPath = buildResourceImportPath(outputTemplate, initDir, locale, ns);
+                    lines.push(`import ${toResourceVarName(locale, ns)} from '${importPath}'`);
+                }
+                break;
+            case 'fs-backend':
+                lines.push("import Backend from 'i18next-fs-backend'");
+                lines.push("import { resolve, dirname } from 'node:path'");
+                lines.push("import { fileURLToPath } from 'node:url'");
+                break;
+        }
+    }
+    // ── Pre-init statements ──
+    lines.push('');
+    if (strategy === 'fs-backend' && outputTemplate) {
+        lines.push('const __dirname = dirname(fileURLToPath(import.meta.url))');
+        lines.push('');
+    }
+    // ── .use() chain entries ──
+    const useEntries = [];
+    if (hasReact)
+        useEntries.push('  .use(initReactI18next)');
+    if (outputTemplate) {
+        if (strategy === 'resources-to-backend') {
+            const dynamicPath = buildDynamicImportPath(outputTemplate, initDir);
+            const importPathTemplate = dynamicPath
+                // 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 = outputTemplate.includes('{{namespace}}');
+            const cbParams = hasNamespace
+                ? (hasTypeScript ? 'language: string, namespace: string' : 'language, namespace')
+                : (hasTypeScript ? 'language: string' : 'language');
+            useEntries.push(`  .use(resourcesToBackend((${cbParams}) => import(\`${importPathTemplate}\`)))`);
+        }
+        else if (strategy === 'fs-backend') {
+            useEntries.push('  .use(Backend)');
+        }
+    }
+    // Emit the i18next chain — use compact form if no .use() calls
+    const awaitPrefix = (strategy === 'fs-backend' && outputTemplate) ? 'await ' : '';
+    if (useEntries.length > 0) {
+        lines.push(`${awaitPrefix}i18next`);
+        lines.push(...useEntries);
+        lines.push('  .init({');
+    }
+    else {
+        lines.push(`${awaitPrefix}i18next.init({`);
+    }
+    // ── .init() options ──
+    const initOpts = [];
+    if (strategy === 'fs-backend' && outputTemplate) {
+        initOpts.push('    initImmediate: false,');
+    }
+    initOpts.push('    returnEmptyString: false, // allows empty string as valid translation');
+    initOpts.push(`    // lng: '${config.locales.at(-1)}', // or add a language detector to detect the preferred language of your user`);
+    initOpts.push(`    fallbackLng: '${primaryLang}',`);
+    if (defaultNS) {
+        initOpts.push(`    defaultNS: '${ns}',`);
+    }
+    // Strategy-specific init options
+    if (outputTemplate) {
+        if (strategy === 'bundled-resources') {
+            initOpts.push('    resources: {');
+            for (const locale of config.locales) {
+                const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(locale) ? locale : `'${locale}'`;
+                initOpts.push(`      ${key}: { ${ns}: ${toResourceVarName(locale, ns)} },`);
+            }
+            initOpts.push('    },');
+        }
+        else if (strategy === 'fs-backend') {
+            const loadPath = buildFsBackendLoadPath(outputTemplate, initDir);
+            initOpts.push(`    preload: [${config.locales.map(l => `'${l}'`).join(', ')}],`);
+            initOpts.push('    backend: {');
+            initOpts.push(`      loadPath: resolve(__dirname, '${loadPath}'),`);
+            initOpts.push('    },');
+        }
+    }
+    else {
+        // No concrete output path — user needs to configure loading manually
+        initOpts.push('    // resources: { ... }  — or use a backend plugin to load translations');
+    }
+    lines.push(initOpts.join('\n'));
+    lines.push('  })');
+    lines.push('');
+    lines.push('export default i18next');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Resolves the import path for a specific locale/namespace resource file
+ * (used by the bundled-resources strategy).
+ */
+function buildResourceImportPath(outputTemplate, initDir, locale, namespace) {
+    const rel = buildDynamicImportPath(outputTemplate, initDir);
+    return rel
+        .replace(/\{\{language\}\}|\{\{lng\}\}/g, locale)
+        .replace(/\{\{namespace\}\}|\{\{ns\}\}/g, namespace);
+}
+/**
+ * Resolves the loadPath for i18next-fs-backend, using i18next's `{{lng}}`
+ * and `{{ns}}` interpolation syntax.
+ */
+function buildFsBackendLoadPath(outputTemplate, initDir) {
+    const rel = buildDynamicImportPath(outputTemplate, initDir);
+    return rel
+        .replace(/\{\{language\}\}/g, '{{lng}}')
+        .replace(/\{\{namespace\}\}/g, '{{ns}}');
+}
+/**
+ * Converts a locale + namespace pair to a valid JS variable name.
+ * E.g. ('en', 'translation') → 'enTranslation', ('zh-CN', 'common') → 'zhCNCommon'
+ */
+function toResourceVarName(locale, namespace) {
+    const sanitizedLocale = locale.replace(/[^a-zA-Z0-9]/g, '');
+    return sanitizedLocale + namespace.charAt(0).toUpperCase() + namespace.slice(1);
+}
 /**
  * Common entry-point file names, checked in priority order.
  */
@@ -1565,7 +1852,7 @@ async function writeExtractedKeys(candidates, config, namespace, logger$1 = new
                 translations[`${candidate.key}_other`] = pf.other;
             }
             else {
-                translations[candidate.key] = candidate.content;
+                translations[candidate.key] = candidate.transValue ?? candidate.content;
             }
         }
     }