i18next-cli 1.46.4 → 1.47.1

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

@@ -0,0 +1,339 @@
+'use strict';
+
+var MagicString = require('magic-string');
+var keyGenerator = require('./key-generator.js');
+
+/**
+ * Transforms a source file, replacing candidate strings with instrumented code.
+ * Also injects useTranslation() hooks into React function components that
+ * contain transformed strings.
+ *
+ * @param content - Original source code
+ * @param file - File path
+ * @param candidates - Candidate strings to transform
+ * @param options - Transformation options
+ * @returns TransformResult with modified content and diff
+ */
+function transformFile(content, file, candidates, options) {
+    const s = new MagicString(content);
+    const errors = [];
+    const warnings = [];
+    let transformCount = 0;
+    const injections = {
+        importAdded: false,
+        hookInjected: false
+    };
+    // Filter high-confidence candidates
+    const highConfidenceCandidates = candidates.filter(c => c.confidence >= 0.7);
+    // Track which components have transformed candidates
+    const transformedComponents = new Set();
+    let hasComponentCandidates = false;
+    let hasNonComponentCandidates = false;
+    // ── Language-change site injections ────────────────────────────────────
+    const languageChangeSites = options.languageChangeSites || [];
+    // Track components that need `i18n` from useTranslation()
+    const componentsNeedingI18n = new Set();
+    let languageChangeCount = 0;
+    // Apply language-change injections in reverse order (to preserve offsets)
+    const sortedSites = [...languageChangeSites].sort((a, b) => b.callStart - a.callStart);
+    for (const site of sortedSites) {
+        try {
+            const changeCall = site.insideComponent
+                ? `i18n.changeLanguage(${site.languageExpression})`
+                : `i18next.changeLanguage(${site.languageExpression})`;
+            // Check if the call is the expression body of an arrow function (no braces):
+            //   () => updateSettings({ language: code })
+            // We need to wrap it:
+            //   () => { i18n.changeLanguage(code); updateSettings({ language: code }); }
+            const beforeCall = content.slice(0, site.callStart);
+            const arrowMatch = beforeCall.match(/=>\s*$/);
+            if (arrowMatch) {
+                // Arrow function expression body → wrap in block
+                const originalCall = content.slice(site.callStart, site.callEnd);
+                s.overwrite(site.callStart, site.callEnd, `{ ${changeCall}; ${originalCall}; }`);
+            }
+            else {
+                // Already in a block → prepend as a statement
+                s.appendLeft(site.callStart, `${changeCall}; `);
+            }
+            languageChangeCount++;
+            if (site.insideComponent) {
+                componentsNeedingI18n.add(site.insideComponent);
+                transformedComponents.add(site.insideComponent);
+                hasComponentCandidates = true;
+            }
+            else {
+                hasNonComponentCandidates = true;
+            }
+        }
+        catch (err) {
+            errors.push(`Failed to inject changeLanguage at offset ${site.callStart}: ${err}`);
+        }
+    }
+    // Apply transformations in reverse order (to maintain correct offsets)
+    for (let i = highConfidenceCandidates.length - 1; i >= 0; i--) {
+        const candidate = highConfidenceCandidates[i];
+        try {
+            const key = candidate.key || keyGenerator.generateKeyFromContent(candidate.content);
+            const useHookStyle = !!candidate.insideComponent;
+            const defaultNS = options.config.extract?.defaultNS ?? 'translation';
+            const nsForReplacement = (options.namespace && options.namespace !== defaultNS) ? options.namespace : undefined;
+            const replacement = buildReplacement(candidate, key, useHookStyle, nsForReplacement);
+            if (replacement) {
+                s.overwrite(candidate.offset, candidate.endOffset, replacement);
+                transformCount++;
+                if (candidate.insideComponent) {
+                    transformedComponents.add(candidate.insideComponent);
+                    hasComponentCandidates = true;
+                }
+                else {
+                    hasNonComponentCandidates = true;
+                }
+            }
+        }
+        catch (err) {
+            errors.push(`Failed to transform candidate at offset ${candidate.offset}: ${err}`);
+        }
+    }
+    // Add necessary imports and hooks if any transformations were made
+    if (transformCount > 0 || languageChangeCount > 0) {
+        const components = options.components || [];
+        // Inject useTranslation() hooks into affected React components
+        if (options.hasReact && transformedComponents.size > 0) {
+            // Process components in reverse order of bodyStart to avoid offset shifts
+            const affectedComponents = components
+                .filter(c => transformedComponents.has(c.name) && !c.hasUseTranslation)
+                .sort((a, b) => b.bodyStart - a.bodyStart);
+            for (const comp of affectedComponents) {
+                const indent = detectIndent(content, comp.bodyStart);
+                const defaultNS = options.config.extract?.defaultNS ?? 'translation';
+                const nsArg = (options.namespace && options.namespace !== defaultNS) ? `'${options.namespace}'` : '';
+                // Build destructuring: include `t` if the component has string candidates,
+                // include `i18n` if the component has language-change sites.
+                const needsT = highConfidenceCandidates.some(c => c.insideComponent === comp.name);
+                const needsI18n = componentsNeedingI18n.has(comp.name);
+                const parts = [];
+                if (needsT)
+                    parts.push('t');
+                if (needsI18n)
+                    parts.push('i18n');
+                if (parts.length === 0)
+                    parts.push('t'); // fallback
+                const destructured = `{ ${parts.join(', ')} }`;
+                s.appendRight(comp.bodyStart + 1, `\n${indent}const ${destructured} = useTranslation(${nsArg})`);
+                injections.hookInjected = true;
+            }
+            // For components that already have useTranslation but need i18n added,
+            // try to upgrade `const { t } = useTranslation(...)` → `const { t, i18n } = useTranslation(...)`
+            if (componentsNeedingI18n.size > 0) {
+                const compsWithExistingHook = components.filter(c => componentsNeedingI18n.has(c.name) && c.hasUseTranslation);
+                for (const comp of compsWithExistingHook) {
+                    // Search for the destructuring pattern within the component body
+                    const bodyText = content.slice(comp.bodyStart, comp.bodyEnd);
+                    // Skip if i18n is already destructured
+                    if (/const\s*\{[^}]*\bi18n\b[^}]*\}\s*=\s*useTranslation/.test(bodyText))
+                        continue;
+                    // Match `{ t }` or `{ t, ... }` in `const { t } = useTranslation`
+                    const hookRe = /const\s*\{\s*t\s*\}\s*=\s*useTranslation/;
+                    const hookMatch = hookRe.exec(bodyText);
+                    if (hookMatch) {
+                        const absStart = comp.bodyStart + hookMatch.index;
+                        const absEnd = absStart + hookMatch[0].length;
+                        const upgraded = hookMatch[0].replace(/\{\s*t\s*\}/, '{ t, i18n }');
+                        s.overwrite(absStart, absEnd, upgraded);
+                    }
+                }
+            }
+        }
+        // Add import statements
+        addImportStatements(s, content, {
+            needsUseTranslation: hasComponentCandidates && options.hasReact,
+            needsI18next: hasNonComponentCandidates || !options.hasReact
+        });
+        injections.importAdded = true;
+    }
+    // Warn when i18next.t() is used in React projects (translations may not be loaded yet)
+    if (options.hasReact && hasNonComponentCandidates && transformCount > 0) {
+        warnings.push(`${file}: i18next.t() was added outside of a React component. ` +
+            'If translation resources are loaded asynchronously, i18next.t() may return the key instead of the translation. ' +
+            'Consider moving this text into a component and using the useTranslation() hook, or ensure i18next is fully initialized before this code runs. ' +
+            'See: https://www.locize.com/blog/how-to-use-i18next-t-outside-react-components/');
+    }
+    const newContent = s.toString();
+    const diff = generateDiff(content, newContent, file);
+    const totalChanges = transformCount + languageChangeCount;
+    return {
+        modified: totalChanges > 0,
+        newContent: !options.isDryRun ? newContent : undefined,
+        diff,
+        errors,
+        warnings,
+        transformCount,
+        languageChangeCount,
+        injections
+    };
+}
+/**
+ * Builds the replacement code for a candidate string.
+ *
+ * @param candidate - The candidate to replace
+ * @param key - The i18n key to use
+ * @param useHookStyle - If true, uses t() (from useTranslation hook); otherwise uses i18next.t()
+ * @param namespace - Optional namespace (only set when different from defaultNS)
+ */
+function buildReplacement(candidate, key, useHookStyle, namespace) {
+    const tFunc = useHookStyle ? 't' : 'i18next.t';
+    const escapedContent = escapeString(candidate.content);
+    // ── Plural form: t('key', { defaultValue_zero: '…', …, count: expr }) ──
+    if (candidate.pluralForms) {
+        const pf = candidate.pluralForms;
+        const optionEntries = [];
+        if (pf.zero !== undefined) {
+            optionEntries.push(`defaultValue_zero: '${escapeString(pf.zero)}'`);
+        }
+        if (pf.one !== undefined) {
+            optionEntries.push(`defaultValue_one: '${escapeString(pf.one)}'`);
+        }
+        optionEntries.push(`defaultValue_other: '${escapeString(pf.other)}'`);
+        optionEntries.push(`count: ${pf.countExpression}`);
+        if (!useHookStyle && namespace) {
+            optionEntries.push(`ns: '${namespace}'`);
+        }
+        const tCall = `${tFunc}('${key}', { ${optionEntries.join(', ')} })`;
+        switch (candidate.type) {
+            case 'jsx-text':
+            case 'jsx-attribute':
+                return `{${tCall}}`;
+            default:
+                return tCall;
+        }
+    }
+    // Build the optional third argument: { interpolationVars..., ns? }
+    const optionEntries = [];
+    if (candidate.interpolations?.length) {
+        for (const interp of candidate.interpolations) {
+            optionEntries.push(interp.name === interp.expression ? interp.name : `${interp.name}: ${interp.expression}`);
+        }
+    }
+    if (!useHookStyle && namespace) {
+        optionEntries.push(`ns: '${namespace}'`);
+    }
+    const optionsArg = optionEntries.length > 0 ? `, { ${optionEntries.join(', ')} }` : '';
+    const tCall = `${tFunc}('${key}', '${escapedContent}'${optionsArg})`;
+    switch (candidate.type) {
+        case 'jsx-text':
+        case 'jsx-attribute':
+            return `{${tCall}}`;
+        case 'jsx-mixed':
+            if (useHookStyle) {
+                return `<Trans i18nKey="${key}">${candidate.content}</Trans>`;
+            }
+            return candidate.content;
+        case 'template-literal':
+        case 'string-literal':
+        default:
+            return tCall;
+    }
+}
+/**
+ * Escapes a string for use in generated code.
+ */
+function escapeString(str) {
+    return str
+        .replace(/\\/g, '\\\\') // Escape backslashes first
+        .replace(/'/g, "\\'") // Escape single quotes
+        .replace(/\n/g, '\\n') // Escape newlines
+        .replace(/\r/g, '\\r') // Escape carriage returns
+        .replace(/\t/g, '\\t'); // Escape tabs
+}
+/**
+ * Checks if an import statement for a module already exists.
+ */
+function hasImport(content, moduleName) {
+    const importRegex = new RegExp(`import\\s+.*from\\s+['"]${moduleName}['"]`, 'g');
+    const requireRegex = new RegExp(`require\\(['"]${moduleName}['"]\\)`, 'g');
+    return importRegex.test(content) || requireRegex.test(content);
+}
+/**
+ * Detects the indentation level used after an opening brace.
+ * Skips blank lines and reads the whitespace of the first line that has actual content.
+ */
+function detectIndent(content, braceOffset) {
+    let searchFrom = braceOffset;
+    while (searchFrom < content.length) {
+        const newlinePos = content.indexOf('\n', searchFrom);
+        if (newlinePos === -1)
+            return '  ';
+        let indent = '';
+        let i = newlinePos + 1;
+        while (i < content.length && (content[i] === ' ' || content[i] === '\t')) {
+            indent += content[i];
+            i++;
+        }
+        // If this line has actual content (not just empty / blank), use its indentation
+        if (i < content.length && content[i] !== '\n' && content[i] !== '\r') {
+            return indent || '  ';
+        }
+        // Empty line — continue looking at the next line
+        searchFrom = i;
+    }
+    return '  ';
+}
+/**
+ * Adds necessary import statements (useTranslation and/or i18next).
+ */
+function addImportStatements(s, content, needs) {
+    let importStatement = '';
+    if (needs.needsUseTranslation && !hasImport(content, 'react-i18next')) {
+        importStatement += "import { useTranslation } from 'react-i18next'\n";
+    }
+    if (needs.needsI18next && !hasImport(content, 'i18next')) {
+        importStatement += "import i18next from 'i18next'\n";
+    }
+    if (!importStatement)
+        return;
+    // Insert after the last existing import statement, or at the top of the file
+    let insertPos = 0;
+    // Skip shebang if present
+    if (content.startsWith('#!')) {
+        insertPos = content.indexOf('\n') + 1;
+    }
+    // Find the end of the last import statement
+    const importRegex = /^import\s.+$/gm;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+        const endOfImport = match.index + match[0].length;
+        if (endOfImport > insertPos) {
+            const nextNewline = content.indexOf('\n', endOfImport);
+            insertPos = nextNewline !== -1 ? nextNewline + 1 : endOfImport;
+        }
+    }
+    s.appendRight(insertPos, importStatement);
+}
+/**
+ * Generates a unified diff showing what changed.
+ */
+function generateDiff(original, modified, filePath) {
+    if (original === modified) {
+        return '';
+    }
+    const originalLines = original.split('\n');
+    const modifiedLines = modified.split('\n');
+    let diff = `--- a/${filePath}\n`;
+    diff += `+++ b/${filePath}\n`;
+    // Simple line-by-line diff
+    for (let i = 0; i < Math.max(originalLines.length, modifiedLines.length); i++) {
+        if (originalLines[i] !== modifiedLines[i]) {
+            if (originalLines[i] !== undefined) {
+                diff += `-${originalLines[i]}\n`;
+            }
+            if (modifiedLines[i] !== undefined) {
+                diff += `+${modifiedLines[i]}\n`;
+            }
+        }
+    }
+    return diff;
+}
+
+exports.generateDiff = generateDiff;
+exports.transformFile = transformFile;

package/dist/cjs/linter.js

@@ -8,6 +8,7 @@ var node_events = require('node:events');
 var node_util = require('node:util');
 var logger = require('./utils/logger.js');
 var wrapOra = require('./utils/wrap-ora.js');
+var jsxAttributes = require('./utils/jsx-attributes.js');
 
 /**
  * Loads all translation values from the primary locale's JSON files and returns
@@ -74,8 +75,8 @@ async function loadPrimaryTranslationValues(config) {
 function extractInterpolationKeys(str, config) {
     const prefix = config.extract.interpolationPrefix ?? '{{';
     const suffix = config.extract.interpolationSuffix ?? '}}';
-    // Regex to match {{key}}
-    const regex = new RegExp(`${prefix.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}\\s*([\\w.-]+)\\s*${suffix.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}`, 'g');
+    // Regex to match {{key}} or {{key, format}} (i18next formatting syntax)
+    const regex = new RegExp(`${prefix.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}\\s*([\\w.-]+)\\s*(?:,[^}]*)?${suffix.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}`, 'g');
     const keys = [];
     let match;
     while ((match = regex.exec(str))) {
@@ -246,12 +247,10 @@ function lintInterpolationParams(ast, code, config, translationValues) {
     }
     return issues;
 }
-const recommendedAcceptedTags = [
-    'a', 'abbr', 'address', 'article', 'aside', 'bdi', 'bdo', 'blockquote', 'button', 'caption', 'cite', 'code', 'data', 'dd', 'del', 'details', 'dfn', 'dialog', 'div', 'dt', 'em', 'figcaption', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'img', 'ins', 'kbd', 'label', 'legend', 'li', 'main', 'mark', 'nav', 'option', 'output', 'p', 'pre', 'q', 's', 'samp', 'section', 'small', 'span', 'strong', 'sub', 'summary', 'sup', 'td', 'textarea', 'th', 'time', 'title', 'var'
-].map(s => s.toLowerCase());
-const recommendedAcceptedAttributes = ['abbr', 'accesskey', 'alt', 'aria-description', 'aria-label', 'aria-placeholder', 'aria-roledescription', 'aria-valuetext', 'content', 'label', 'placeholder', 'summary', 'title'].map(s => s.toLowerCase());
-const defaultIgnoredAttributes = ['className', 'key', 'id', 'style', 'href', 'i18nKey', 'defaults', 'type', 'target'].map(s => s.toLowerCase());
-const defaultIgnoredTags = ['script', 'style', 'code'];
+const recommendedAcceptedTags = jsxAttributes.acceptedTags.map(s => s.toLowerCase());
+const recommendedAcceptedAttributes = jsxAttributes.translatableAttributes.map(s => s.toLowerCase());
+const defaultIgnoredAttributes = jsxAttributes.ignoredAttributeLowerSet;
+const defaultIgnoredTags = jsxAttributes.ignoredTags;
 class Linter extends node_events.EventEmitter {
     config;
     logger;
@@ -566,7 +565,7 @@ function findHardcodedStrings(ast, code, config) {
     };
     const transComponents = (config.extract.transComponents || ['Trans']).map((s) => s.toLowerCase());
     const customIgnoredTags = (config?.lint?.ignoredTags || config.extract.ignoredTags || []).map((s) => s.toLowerCase());
-    const allIgnoredTags = new Set([...transComponents, ...defaultIgnoredTags.map(s => s.toLowerCase()), ...customIgnoredTags]);
+    const allIgnoredTags = new Set([...transComponents, ...defaultIgnoredTags.map((s) => s.toLowerCase()), ...customIgnoredTags]);
     const customIgnoredAttributes = (config?.lint?.ignoredAttributes || config.extract.ignoredAttributes || []).map((s) => s.toLowerCase());
     const ignoredAttributes = new Set([...defaultIgnoredAttributes, ...customIgnoredAttributes]);
     const lintAcceptedTags = config?.lint?.acceptedTags ? config.lint.acceptedTags : null;

package/dist/cjs/utils/jsx-attributes.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * Shared constants for JSX / HTML attribute classification.
+ *
+ * Used by both the **linter** and the **instrumenter** to consistently decide
+ * which JSX attribute values are user-facing (translatable) and which are
+ * technical / non-translatable.
+ *
+ * Having a single source of truth avoids drift between the linter's
+ * `defaultIgnoredAttributes` / `recommendedAcceptedAttributes` and the
+ * instrumenter's `SKIP_JSX_ATTRIBUTES` / `TRANSLATABLE_ATTRIBUTES`.
+ */
+// ────────────────────────────────────────────────────────────────────────
+// Translatable attributes
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * JSX/HTML attribute names whose values are typically user-visible and
+ * should be translated.
+ *
+ * This is the recommended accepted-list for the linter **and** the set used
+ * by the instrumenter's string-detector to allow attribute values through.
+ *
+ * Exported from the public API as `recommendedAcceptedAttributes`.
+ */
+const translatableAttributes = [
+    'abbr', 'accesskey', 'alt',
+    'aria-description', 'aria-label', 'aria-placeholder',
+    'aria-roledescription', 'aria-valuetext',
+    'content', 'description',
+    'label', 'placeholder',
+    'summary', 'caption', 'title'
+];
+/**
+ * Pre-built Set (lower-cased) for fast membership checks in hot loops.
+ */
+const translatableAttributeSet = new Set(translatableAttributes.map(s => s.toLowerCase()));
+// ────────────────────────────────────────────────────────────────────────
+// Non-translatable (ignored) attributes
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * JSX attribute names whose values are **never** user-facing.
+ *
+ * The linter uses these as `defaultIgnoredAttributes`, and the instrumenter
+ * skips recursing into them entirely so that e.g. `className={...}` is
+ * never wrapped in `t()`.
+ *
+ * Event-handler attributes (on*) are handled separately via a prefix check
+ * rather than being enumerated here, but a representative set is included
+ * for the instrumenter's early-exit guard which does a Set lookup.
+ */
+const ignoredAttributes = [
+    // CSS / styling
+    'className', 'class', 'style',
+    // Identity / keys
+    'key', 'id', 'htmlFor', 'for', 'name',
+    // Links & resources
+    'href', 'src', 'srcSet', 'action',
+    // HTML form / behaviour
+    'type', 'target', 'rel', 'role', 'method', 'encType',
+    'autoComplete', 'autoFocus', 'tabIndex',
+    // Testing
+    'data-testid', 'data-cy',
+    // i18next-specific (already instrumented / extractor config)
+    'i18nKey', 'defaults', 'ns', 'defaultValue',
+    // Event handlers (representative set — the instrumenter also does a
+    // prefix check for `on[A-Z]`)
+    'onChange', 'onClick', 'onSubmit', 'onFocus', 'onBlur',
+    'onKeyDown', 'onKeyUp', 'onMouseEnter', 'onMouseLeave',
+    // React internals
+    'ref', 'dangerouslySetInnerHTML', 'suppressHydrationWarning'
+];
+/**
+ * Pre-built Set for fast membership checks.
+ * Values are stored in their original casing — the instrumenter checks the
+ * raw SWC attribute name.  The linter lower-cases before lookup.
+ */
+const ignoredAttributeSet = new Set(ignoredAttributes);
+/**
+ * Same set, lower-cased — used by the linter which normalises attr names.
+ */
+const ignoredAttributeLowerSet = new Set(ignoredAttributes.map(s => s.toLowerCase()));
+// ────────────────────────────────────────────────────────────────────────
+// Translatable object properties (instrumenter-specific)
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * Object / JSON property names whose values are typically user-visible and
+ * should be translated.  Used by the instrumenter's string-detector to give
+ * a confidence boost.
+ */
+const translatableProperties = [
+    'label', 'title', 'description', 'text', 'message', 'placeholder',
+    'caption', 'summary', 'heading', 'subheading', 'subtitle', 'tooltip',
+    'hint', 'helpText', 'errorMessage', 'successMessage', 'name'
+];
+const translatablePropertySet = new Set(translatableProperties);
+// ────────────────────────────────────────────────────────────────────────
+// Ignored tags (linter + potential future instrumenter use)
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * HTML/JSX tags whose content should be ignored when linting for hardcoded
+ * strings (e.g. `<script>`, `<style>`, `<code>`).
+ */
+const ignoredTags = ['script', 'style', 'code'];
+/**
+ * Recommended accepted tags — the set of tags the linter considers as
+ * potentially containing translatable content.
+ *
+ * Exported from the public API as `recommendedAcceptedTags`.
+ */
+const acceptedTags = [
+    'a', 'abbr', 'address', 'article', 'aside', 'bdi', 'bdo', 'blockquote',
+    'button', 'caption', 'cite', 'code', 'data', 'dd', 'del', 'details',
+    'dfn', 'dialog', 'div', 'dt', 'em', 'figcaption', 'footer',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header',
+    'img', 'ins', 'kbd', 'label', 'legend', 'li', 'main', 'mark', 'nav',
+    'option', 'output', 'p', 'pre', 'q', 's', 'samp', 'section', 'small',
+    'span', 'strong', 'sub', 'summary', 'sup', 'td', 'textarea', 'th',
+    'time', 'title', 'var'
+];
+new Set(acceptedTags.map(s => s.toLowerCase()));
+
+exports.acceptedTags = acceptedTags;
+exports.ignoredAttributeLowerSet = ignoredAttributeLowerSet;
+exports.ignoredAttributeSet = ignoredAttributeSet;
+exports.ignoredAttributes = ignoredAttributes;
+exports.ignoredTags = ignoredTags;
+exports.translatableAttributeSet = translatableAttributeSet;
+exports.translatableAttributes = translatableAttributes;
+exports.translatableProperties = translatableProperties;
+exports.translatablePropertySet = translatablePropertySet;

package/dist/esm/cli.js

@@ -21,12 +21,15 @@ import { runLinterCli } from './linter.js';
 import { runStatus } from './status.js';
 import { runLocizeSync, runLocizeDownload, runLocizeMigrate } from './locize.js';
 import { runRenameKey } from './rename-key.js';
+import { runInstrumenter } from './instrumenter/core/instrumenter.js';
+import './utils/jsx-attributes.js';
+import 'magic-string';
 
 const program = new Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.46.4'); // This string is replaced with the actual version at build time by rollup
+    .version('1.47.1'); // 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
@@ -202,6 +205,52 @@ program
         }
     }
 });
+program
+    .command('instrument')
+    .description('Scan for hardcoded strings and instrument your code with i18next calls.')
+    .option('--dry-run', 'Preview changes without writing files to disk.')
+    .option('--interactive', 'Prompt for approval of each candidate string.')
+    .option('--namespace <ns>', 'Target a specific namespace for extracted keys.')
+    .option('-q, --quiet', 'Suppress spinner and output')
+    .action(async (options) => {
+    try {
+        const cfgPath = program.opts().config;
+        const config = await ensureConfig(cfgPath);
+        const results = await runInstrumenter(config, {
+            isDryRun: !!options.dryRun,
+            isInteractive: !!options.interactive,
+            namespace: options.namespace,
+            quiet: !!options.quiet
+        });
+        // Display results
+        if (!options.quiet) {
+            console.log(styleText('bold', '\nInstrumentation Summary:'));
+            console.log(`  Total candidates: ${results.totalCandidates}`);
+            console.log(`  Approved: ${results.totalTransformed}`);
+            console.log(`  Skipped: ${results.totalSkipped}`);
+            if (results.totalLanguageChanges > 0) {
+                console.log(`  Language-change sites: ${results.totalLanguageChanges}`);
+            }
+            if (options.dryRun) {
+                console.log(styleText('blue', '\n📋 Dry-run mode enabled. No files were modified.'));
+                console.log('Run again without --dry-run to apply changes.');
+            }
+            if (results.files.length > 0) {
+                console.log(styleText('green', `\n✅ ${results.files.length} file(s) ready for instrumentation`));
+            }
+            else {
+                console.log(styleText('yellow', '\n⚠️  No files required instrumentation'));
+            }
+            if (results.totalTransformed > 0 && !options.dryRun) {
+                console.log(styleText('cyan', '\n💡 Next step: run `i18next-cli extract` to extract the translation keys into your locale files.'));
+            }
+        }
+    }
+    catch (error) {
+        console.error(styleText('red', 'Error running instrument command:'), error);
+        process.exit(1);
+    }
+});
 program
     .command('locize-sync')
     .description('Synchronize local translations with your Locize project.')

package/dist/esm/extractor/core/extractor.js

@@ -59,9 +59,13 @@ async function runExtractor(config, options = {}) {
             logger: options.logger
         });
         let anyFileUpdated = false;
+        let anyNewFile = false;
         for (const result of results) {
             if (result.updated) {
                 anyFileUpdated = true;
+                if (Object.keys(result.existingTranslations || {}).length === 0) {
+                    anyNewFile = true;
+                }
                 if (!options.isDryRun) {
                     // prefer explicit outputFormat; otherwise infer from file extension per-file
                     const effectiveFormat = config.extract.outputFormat ?? inferFormatFromPath(result.path);
@@ -87,8 +91,10 @@ async function runExtractor(config, options = {}) {
             : styleText('bold', 'Extraction complete!');
         spinner.succeed(completionMessage);
         // Show the funnel message only if files were actually changed.
-        if (anyFileUpdated)
-            await printLocizeFunnel(options.logger);
+        // When new translation files are created (new namespace or first extraction),
+        // always show the funnel regardless of cooldown.
+        if (anyFileUpdated && !options.isDryRun)
+            await printLocizeFunnel(options.logger, anyNewFile);
         return { anyFileUpdated, hasErrors: fileErrors.length > 0 };
     }
     catch (error) {
@@ -249,24 +255,27 @@ async function extract(config, { syncPrimaryWithDefaults = false } = {}) {
  * Prints a promotional message for the locize saveMissing workflow.
  * This message is shown after a successful extraction that resulted in changes.
  */
-async function printLocizeFunnel(logger) {
-    if (!(await shouldShowFunnel('extract')))
+async function printLocizeFunnel(logger, force) {
+    if (!force && !(await shouldShowFunnel('extract')))
         return;
     const internalLogger = logger ?? new ConsoleLogger();
-    if (typeof internalLogger.info === 'function') {
-        internalLogger.info(styleText(['yellow', 'bold'], '\n💡 Tip: Tired of running the extractor manually?'));
-        internalLogger.info('   Discover a real-time "push" workflow with `saveMissing` and Locize AI,');
-        internalLogger.info('   where keys are created and translated automatically as you code.');
-        internalLogger.info(`   Learn more: ${styleText('cyan', 'https://www.locize.com/blog/i18next-savemissing-ai-automation')}`);
-        internalLogger.info(`   Watch the video: ${styleText('cyan', 'https://youtu.be/joPsZghT3wM')}`);
-    }
-    else {
-        console.log(styleText(['yellow', 'bold'], '\n💡 Tip: Tired of running the extractor manually?'));
-        console.log('   Discover a real-time "push" workflow with `saveMissing` and Locize AI,');
-        console.log('   where keys are created and translated automatically as you code.');
-        console.log(`   Learn more: ${styleText('cyan', 'https://www.locize.com/blog/i18next-savemissing-ai-automation')}`);
-        console.log(`   Watch the video: ${styleText('cyan', 'https://youtu.be/joPsZghT3wM')}`);
-    }
+    const lines = [
+        styleText(['yellow', 'bold'], '\n💡 Tip: Tired of running the extractor manually?'),
+        '   Discover a real-time "push" workflow with `saveMissing` and Locize AI/MT,',
+        '   where keys are created and translated automatically as you code.',
+        `   Learn more: ${styleText('cyan', 'https://www.locize.com/blog/i18next-savemissing-ai-automation')}`,
+        `   Watch the video: ${styleText('cyan', 'https://youtu.be/joPsZghT3wM')}`,
+        '',
+        '   You can also sync your extracted translations to Locize:',
+        `     ${styleText('cyan', 'npx i18next-cli locize-sync')}      – upload/sync translations to Locize`,
+        `     ${styleText('cyan', 'npx i18next-cli locize-migrate')}   – migrate local translations to Locize`,
+        '   Or import them manually via the Locize UI, API, or locize-cli.',
+    ];
+    const log = typeof internalLogger.info === 'function'
+        ? (msg) => internalLogger.info(msg)
+        : (msg) => console.log(msg);
+    for (const line of lines)
+        log(line);
     return recordFunnelShown('extract');
 }