i18next-cli 1.54.2 → 1.56.0

package/README.md

@@ -607,9 +607,12 @@ export default defineConfig({
     ],
     
     /**
-     * When true, preserves all context variants of keys that use context parameters.
-     * For example, if 'friend' is used with context, all variants like 'friend_male',
-     * 'friend_female', etc. are preserved even if not explicitly found in source code.
+     * When true, preserves all context variants of keys that use context parameters,
+     * across every configured locale. For example, if 'friend' is used with a context
+     * option in source code, variants like 'friend_male' and 'friend_female' are kept
+     * in the primary language even when they're not referenced explicitly, and are
+     * propagated to secondary locales with empty placeholders so every language ends
+     * up with the same key skeleton.
      * (default: false)
      */
     preserveContextVariants: false,
@@ -661,6 +664,10 @@ export default defineConfig({
 
     // Prefix for nested translations.
     // Controls how nested $t(...) calls inside strings are detected.
+    // Nested references are scanned in BOTH source code (keys and defaultValues
+    // passed to t()) and in the values of existing translation files, so keys
+    // reachable only via `$t(...)` inside a translation value are preserved by
+    // `extract` and expanded into the correct per-locale plural skeleton.
     // Example: '$t('
     nestingPrefix: '$t(', // Default: '$t('
     

package/dist/cjs/cli.js

@@ -11,6 +11,7 @@ var heuristicConfig = require('./heuristic-config.js');
 var extractor = require('./extractor/core/extractor.js');
 require('./extractor/parsers/jsx-parser.js');
 require('node:path');
+var nestedObject = require('./utils/nested-object.js');
 require('node:fs/promises');
 require('jiti');
 require('@croct/json5-parser');
@@ -31,7 +32,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.54.2'); // This string is replaced with the actual version at build time by rollup
+    .version('1.56.0'); // 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
@@ -51,7 +52,7 @@ program
         const runExtract = async () => {
             // --sync-all implies sync-primary behavior
             const syncPrimary = !!options.syncPrimary || !!options.syncAll;
-            const { anyFileUpdated, hasErrors } = await extractor.runExtractor(config$1, {
+            const { anyFileUpdated, hasErrors, results } = await extractor.runExtractor(config$1, {
                 isWatchMode: !!options.watch,
                 isDryRun: !!options.dryRun,
                 syncPrimaryWithDefaults: syncPrimary,
@@ -65,6 +66,7 @@ program
             }
             else if (options.ci && anyFileUpdated) {
                 console.error('❌ Some files were updated. This should not happen in CI mode.');
+                printCiDiff(results, config$1);
                 process.exit(1);
             }
             if (hasErrors && !options.watch) {
@@ -328,5 +330,67 @@ const expandGlobs = async (patterns = []) => {
     const sets = await Promise.all(arr.map(p => glob.glob(p || '', { nodir: true })));
     return Array.from(new Set(sets.flat()));
 };
+function printCiDiff(results, config) {
+    const rawSep = config.extract.keySeparator;
+    const keySeparator = rawSep === false ? false : (rawSep ?? '.');
+    for (const result of results) {
+        if (!result.updated)
+            continue;
+        const existing = result.existingTranslations || {};
+        const next = result.newTranslations || {};
+        const oldKeys = new Set(nestedObject.getNestedKeys(existing, keySeparator));
+        const newKeys = new Set(nestedObject.getNestedKeys(next, keySeparator));
+        const added = [];
+        const removed = [];
+        const changed = [];
+        for (const k of newKeys) {
+            if (!oldKeys.has(k)) {
+                added.push(k);
+            }
+            else {
+                const oldVal = nestedObject.getNestedValue(existing, k, keySeparator);
+                const newVal = nestedObject.getNestedValue(next, k, keySeparator);
+                if (oldVal !== newVal)
+                    changed.push(k);
+            }
+        }
+        for (const k of oldKeys) {
+            if (!newKeys.has(k))
+                removed.push(k);
+        }
+        const nsLabel = result.namespace
+            ? ` [${result.locale}/${result.namespace}]`
+            : ` [${result.locale}]`;
+        console.error(`\n  ${result.path}${nsLabel}`);
+        if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+            console.error('    (no key differences — only formatting or ordering changes)');
+            continue;
+        }
+        added.sort();
+        removed.sort();
+        changed.sort();
+        for (const k of added) {
+            const v = nestedObject.getNestedValue(next, k, keySeparator);
+            console.error(node_util.styleText('green', `    + ${k}: ${formatCiDiffValue(v)}`));
+        }
+        for (const k of removed) {
+            const v = nestedObject.getNestedValue(existing, k, keySeparator);
+            console.error(node_util.styleText('red', `    - ${k}: ${formatCiDiffValue(v)}`));
+        }
+        for (const k of changed) {
+            const oldV = nestedObject.getNestedValue(existing, k, keySeparator);
+            const newV = nestedObject.getNestedValue(next, k, keySeparator);
+            console.error(node_util.styleText('yellow', `    ~ ${k}: ${formatCiDiffValue(oldV)} → ${formatCiDiffValue(newV)}`));
+        }
+    }
+}
+function formatCiDiffValue(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 
 exports.program = program;

package/dist/cjs/extractor/core/ast-visitors.js

@@ -96,6 +96,16 @@ class ASTVisitors {
                 this.scopeManager.handleVariableDeclarator(node);
                 this.expressionResolver.captureVariableDeclarator(node);
                 break;
+            case 'TSEnumDeclaration':
+            case 'TsEnumDeclaration':
+            case 'TsEnumDecl':
+                // Enums → ExpressionResolver.sharedEnumTable. Needed in pre-scan so
+                // that function bodies referencing enum members (e.g. `return
+                // OrganizationType.ROUTING`) can be resolved by the body-inference
+                // branch of captureFunctionDeclaration when we hit the function later
+                // in the same file.
+                this.expressionResolver.captureEnumDeclaration(node);
+                break;
             case 'TsTypeAliasDeclaration':
             case 'TSTypeAliasDeclaration':
             case 'TsTypeAliasDecl':
@@ -104,7 +114,7 @@ class ASTVisitors {
                 break;
             case 'FunctionDeclaration':
             case 'FnDecl':
-                // Return-type annotations for t(fn()) patterns
+                // Return-type annotations or inferred return values for t(fn()) patterns
                 this.expressionResolver.captureFunctionDeclaration(node);
                 break;
         }

package/dist/cjs/extractor/core/extractor.js

@@ -99,7 +99,7 @@ async function runExtractor(config, options = {}) {
         // always show the funnel regardless of cooldown.
         if (anyFileUpdated && !options.isDryRun && !options.quiet)
             await printLocizeFunnel(options.logger, anyNewFile);
-        return { anyFileUpdated, hasErrors: fileErrors.length > 0 };
+        return { anyFileUpdated, hasErrors: fileErrors.length > 0, results };
     }
     catch (error) {
         spinner.fail(node_util.styleText('red', 'Extraction failed.'));

package/dist/cjs/extractor/core/translation-manager.js

@@ -7,6 +7,8 @@ var fileUtils = require('../../utils/file-utils.js');
 var defaultValue = require('../../utils/default-value.js');
 var logger = require('../../utils/logger.js');
 var pluralRules = require('../../utils/plural-rules.js');
+var nesting = require('../../utils/nesting.js');
+var contextVariants = require('../../utils/context-variants.js');
 
 // used for natural language check
 const chars = [' ', ',', '?', '!', ';'];
@@ -21,58 +23,6 @@ function globToRegex(glob) {
     const regexString = `^${escaped.replace(/\*/g, '.*')}$`;
     return new RegExp(regexString);
 }
-/**
- * Checks if an existing key is a context variant of a base key that accepts context.
- * This function handles complex cases where:
- * - The key might have plural suffixes (_one, _other, etc.)
- * - The context value itself might contain the separator (e.g., mc_laren)
- *
- * @param existingKey - The key from the translation file to check
- * @param keysAcceptingContext - Set of base keys that were used with context in source code
- * @param pluralSeparator - The separator used for plural forms (default: '_')
- * @param contextSeparator - The separator used for context variants (default: '_')
- * @returns true if the existing key is a context variant of a key accepting context
- */
-function isContextVariantOfAcceptingKey(existingKey, keysAcceptingContext, pluralSeparator, contextSeparator) {
-    if (keysAcceptingContext.size === 0) {
-        return false;
-    }
-    // Try to extract the base key from this existing key by removing context and/or plural suffixes
-    let potentialBaseKey = existingKey;
-    // First, try removing plural suffixes if present
-    for (const form of pluralForms) {
-        if (potentialBaseKey.endsWith(`${pluralSeparator}${form}`)) {
-            potentialBaseKey = potentialBaseKey.slice(0, -(pluralSeparator.length + form.length));
-            break;
-        }
-        if (potentialBaseKey.endsWith(`${pluralSeparator}ordinal${pluralSeparator}${form}`)) {
-            potentialBaseKey = potentialBaseKey.slice(0, -(pluralSeparator.length + 'ordinal'.length + pluralSeparator.length + form.length));
-            break;
-        }
-    }
-    // Then, try removing the context suffix to get the base key
-    // We need to check all possible base keys since the context value itself might contain separators
-    // For example: 'formula_one_mc_laren' could be:
-    //   - base: 'formula_one_mc', context: 'laren'
-    //   - base: 'formula_one', context: 'mc_laren'  ← correct
-    //   - base: 'formula', context: 'one_mc_laren'
-    const parts = potentialBaseKey.split(contextSeparator);
-    if (parts.length > 1) {
-        // Try removing 1, 2, 3... parts from the end to find a matching base key
-        for (let i = 1; i < parts.length; i++) {
-            const baseWithoutContext = parts.slice(0, -i).join(contextSeparator);
-            if (keysAcceptingContext.has(baseWithoutContext)) {
-                return true;
-            }
-        }
-    }
-    // Also check if the key itself (after removing plural suffix) accepts context
-    // This handles cases like 'friend_other' where 'friend' accepts context
-    if (keysAcceptingContext.has(potentialBaseKey)) {
-        return true;
-    }
-    return false;
-}
 /**
  * Checks if a key looks like an object path or natural language.
  * (like in i18next)
@@ -285,6 +235,100 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
             return [...union];
         })()
         : null;
+    // Discover keys that are only referenced through `$t(...)` nested references
+    // inside existing translation values (see issue #241). These keys are
+    // invisible to the AST-based extractor, so without this step they would be
+    // deleted when `removeUnusedKeys` is true and never expanded into the plural
+    // forms a secondary locale needs.
+    //
+    // We inject synthetic ExtractedKey entries for each discovered reference so
+    // the normal filter / plural-expansion pipeline picks them up — for the
+    // primary language this preserves the existing variants, and for secondary
+    // languages this generates the correct per-locale plural skeleton.
+    const syntheticNestedKeys = [];
+    const namespaceMatches = (refNs) => {
+        if (namespace === undefined)
+            return true;
+        // Nested references arrive from parseNestedReferences with `ns` either set
+        // from an explicit `ns:key` prefix or defaulted to config.extract.defaultNS.
+        // Normalise to the same bucket keys used in `keysByNS`.
+        const normalizedRef = refNs === undefined || refNs === null
+            ? config.extract.defaultNS ?? 'translation'
+            : refNs;
+        return normalizedRef === namespace;
+    };
+    // All cardinal plural categories we should expand to for a context+count
+    // nested reference, covering every configured locale so the per-locale
+    // filter can then keep only the relevant ones.
+    const nestedContextCountCategories = (() => {
+        const union = new Set();
+        for (const loc of config.locales) {
+            pluralRules.safePluralRules(loc, { type: 'cardinal' }).resolvedOptions().pluralCategories.forEach(c => union.add(c));
+        }
+        return [...union];
+    })();
+    const seenNestedValues = new Set();
+    const collectFromValue = (value) => {
+        if (typeof value === 'string') {
+            if (seenNestedValues.has(value))
+                return;
+            seenNestedValues.add(value);
+            const refs = nesting.parseNestedReferences(value, {
+                nestingPrefix: config.extract.nestingPrefix,
+                nestingSuffix: config.extract.nestingSuffix,
+                nestingOptionsSeparator: config.extract.nestingOptionsSeparator,
+                nsSeparator: config.extract.nsSeparator,
+                defaultNS: config.extract.defaultNS
+            });
+            for (const ref of refs) {
+                if (!namespaceMatches(ref.ns))
+                    continue;
+                const effectiveHasCount = ref.hasCount && !config.extract.disablePlurals;
+                if (ref.context !== undefined) {
+                    const ctxKey = `${ref.key}${contextSeparator}${ref.context}`;
+                    if (effectiveHasCount) {
+                        // `ctxKey` contains `contextSeparator` (which equals pluralSeparator
+                        // by default) so we cannot hand it to the base plural expansion
+                        // pass. Instead, push fully-expanded variants and rely on the
+                        // per-locale filter to keep the relevant ones.
+                        for (const category of nestedContextCountCategories) {
+                            syntheticNestedKeys.push({
+                                key: `${ctxKey}${pluralSeparator}${category}`,
+                                hasCount: true,
+                                isExpandedPlural: true
+                            });
+                        }
+                    }
+                    else {
+                        syntheticNestedKeys.push({ key: ref.key });
+                        syntheticNestedKeys.push({ key: ctxKey });
+                    }
+                }
+                else if (effectiveHasCount) {
+                    // Plain plural reference — push the base plural key and let the
+                    // normal expansion in the main loop emit per-locale variants.
+                    syntheticNestedKeys.push({ key: ref.key, hasCount: true });
+                }
+                else {
+                    syntheticNestedKeys.push({ key: ref.key });
+                }
+            }
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const v of Object.values(value)) {
+                collectFromValue(v);
+            }
+        }
+    };
+    // Scan both the locale being built and the primary locale so that newly
+    // introduced references are propagated to every locale on the first run.
+    collectFromValue(existingTranslations);
+    if (primaryExistingTranslations && primaryExistingTranslations !== existingTranslations) {
+        collectFromValue(primaryExistingTranslations);
+    }
+    const nsKeysWithNested = syntheticNestedKeys.length > 0
+        ? [...nsKeys, ...syntheticNestedKeys]
+        : nsKeys;
     // Prepare namespace pattern checking helpers
     const rawPreserve = config.extract.preservePatterns || [];
     // Helper to check if a key should be filtered out during extraction
@@ -340,7 +384,7 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
         return false;
     };
     // Filter nsKeys to only include keys relevant to this language
-    const filteredKeys = nsKeys.filter(({ key, hasCount, isOrdinal, explicitDefault }) => {
+    const filteredKeys = nsKeysWithNested.filter(({ key, hasCount, isOrdinal, explicitDefault }) => {
         // FIRST: Check if key matches preservePatterns and should be excluded
         if (shouldFilterKey(key)) {
             return false;
@@ -415,12 +459,41 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
     const existingKeys = nestedObject.getNestedKeys(existingTranslations, keySeparator ?? '.');
     for (const existingKey of existingKeys) {
         const shouldPreserve = shouldPreserveExistingKey(existingKey);
-        const isContextVariant = !shouldPreserve && isContextVariantOfAcceptingKey(existingKey, keysAcceptingContext, pluralSeparator, contextSeparator);
+        const isContextVariant = !shouldPreserve && contextVariants.isContextVariantOfAcceptingKey(existingKey, keysAcceptingContext, pluralSeparator, contextSeparator);
         if (shouldPreserve || (preserveContextVariants && isContextVariant)) {
             const value = nestedObject.getNestedValue(existingTranslations, existingKey, keySeparator ?? '.');
             nestedObject.setNestedValue(newTranslations, existingKey, value, keySeparator ?? '.');
         }
     }
+    // PROPAGATE CONTEXT VARIANTS FROM PRIMARY TO SECONDARY (issue #242):
+    // When `preserveContextVariants` is enabled and the source code uses a
+    // dynamic context value (e.g. `t('exportType', { context: type })`), the
+    // extractor tags the base key as "accepting context" but the actual context
+    // values (e.g. `gas`, `water`) are only known from the primary translation
+    // file. Propagate those variants from primary to secondary locales so every
+    // locale ends up with the same key skeleton — translators and downstream
+    // `sync` can then fill in real values.
+    if (preserveContextVariants && locale !== primaryLanguage && primaryExistingTranslations) {
+        const primaryKeys = nestedObject.getNestedKeys(primaryExistingTranslations, keySeparator ?? '.');
+        for (const primaryKey of primaryKeys) {
+            if (shouldFilterKey(primaryKey))
+                continue;
+            const isContextVariant = contextVariants.isContextVariantOfAcceptingKey(primaryKey, keysAcceptingContext, pluralSeparator, contextSeparator);
+            if (!isContextVariant)
+                continue;
+            const separator = primaryKey.startsWith('<') ? false : (keySeparator ?? '.');
+            const alreadySet = nestedObject.getNestedValue(newTranslations, primaryKey, separator);
+            if (alreadySet !== undefined)
+                continue;
+            // Prefer an existing secondary value if present, otherwise fall back to
+            // the configured defaultValue (empty string for secondaries by default).
+            const existingSecondaryValue = nestedObject.getNestedValue(existingTranslations, primaryKey, separator);
+            const valueToSet = existingSecondaryValue !== undefined
+                ? existingSecondaryValue
+                : defaultValue.resolveDefaultValue(emptyDefaultValue, primaryKey, namespace || config?.extract?.defaultNS || 'translation', locale);
+            nestedObject.setNestedValue(newTranslations, primaryKey, valueToSet, separator);
+        }
+    }
     // PRESERVE LOCALE-SPECIFIC PLURAL FORMS: When dealing with plural keys in non-primary locales,
     // preserve any existing plural forms that are NOT being explicitly generated.
     // This ensures that locale-specific forms (like _few, _many) added by translators are preserved.

package/dist/cjs/extractor/parsers/call-expression-handler.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var pluralRules = require('../../utils/plural-rules.js');
+var nesting = require('../../utils/nesting.js');
 var astUtils = require('./ast-utils.js');
 
 // Helper to escape regex characters
@@ -454,103 +455,26 @@ class CallExpressionHandler {
         }
     }
     /**
-     * Scans a string for nested translations like $t(key, options) and extracts them.
+     * Scans a string for nested translations like $t(key, options) and registers
+     * the referenced keys (plus their plural / context variants) on the current
+     * plugin context.
      */
-    extractNestedKeys(text, ns) {
-        if (!text || typeof text !== 'string')
-            return;
-        const prefix = this.config.extract.nestingPrefix ?? '$t(';
-        const suffix = this.config.extract.nestingSuffix ?? ')';
-        const escapedPrefix = escapeRegex(prefix);
-        const escapedSuffix = escapeRegex(suffix);
-        // Regex adapted from i18next Interpolator.js
-        // Matches nested calls like $t(key) or $t(key, { options })
-        // It handles balanced parentheses to some extent and quoted strings
-        const nestingRegexp = new RegExp(`${escapedPrefix}((?:[^()"']+|"[^"]*"|'[^']*'|\\((?:[^()]|"[^"]*"|'[^']*')*\\))*?)${escapedSuffix}`, 'g');
-        let match;
-        while ((match = nestingRegexp.exec(text)) !== null) {
-            if (match[1]) {
-                // Do NOT trust the outer `ns` blindly — compute namespace from the nested key itself
-                // inside processNestedContent. Pass `undefined` so processNestedContent resolves ns
-                // deterministically (either from key "ns:key" or from defaultNS).
-                this.processNestedContent(match[1], undefined);
-            }
-        }
-    }
-    processNestedContent(content, ns) {
-        let key = content;
-        let optionsString = '';
-        const separator = this.config.extract.nestingOptionsSeparator ?? ',';
-        // Logic adapted from i18next Interpolator.js handleHasOptions
-        if (content.indexOf(separator) < 0) {
-            key = content.trim();
-        }
-        else {
-            // Split by separator, but be careful about objects
-            // i18next does: const c = key.split(new RegExp(`${sep}[ ]*{`));
-            // This assumes options start with {
-            const sepRegex = new RegExp(`${escapeRegex(separator)}[ ]*{`);
-            const parts = content.split(sepRegex);
-            if (parts.length > 1) {
-                key = parts[0].trim();
-                // Reconstruct the options part: add back the '{' that was consumed by split
-                optionsString = `{${parts.slice(1).join(separator + ' {')}`;
+    extractNestedKeys(text, _ns) {
+        const references = nesting.parseNestedReferences(text, {
+            nestingPrefix: this.config.extract.nestingPrefix,
+            nestingSuffix: this.config.extract.nestingSuffix,
+            nestingOptionsSeparator: this.config.extract.nestingOptionsSeparator,
+            nsSeparator: this.config.extract.nsSeparator,
+            defaultNS: this.config.extract.defaultNS
+        });
+        for (const { key, ns: nestedNs, hasCount, context } of references) {
+            const effectiveHasCount = hasCount && !this.config.extract.disablePlurals;
+            if (effectiveHasCount || context !== undefined) {
+                this.generateNestedPluralKeys(key, nestedNs, effectiveHasCount, context);
             }
             else {
-                // Fallback for simple split if no object pattern found
-                const sepIdx = content.indexOf(separator);
-                key = content.substring(0, sepIdx).trim();
-                optionsString = content.substring(sepIdx + 1).trim();
-            }
-        }
-        // Remove quotes from key if present
-        if ((key.startsWith("'") && key.endsWith("'")) || (key.startsWith('"') && key.endsWith('"'))) {
-            key = key.slice(1, -1);
-        }
-        if (!key)
-            return;
-        // Resolve namespace for the nested key:
-        // If nested key contains nsSeparator (e.g. "ns:key"), extract namespace,
-        // otherwise use configured defaultNS.
-        let nestedNs;
-        const nsSeparator = this.config.extract.nsSeparator ?? ':';
-        if (nsSeparator && key.includes(nsSeparator)) {
-            const parts = key.split(nsSeparator);
-            const candidateNs = parts[0];
-            if (!looksLikeNaturalLanguage(candidateNs)) {
-                nestedNs = parts.shift();
-                key = parts.join(nsSeparator);
-                if (!key || key.trim() === '')
-                    return;
+                this.pluginContext.addKey({ key, ns: nestedNs });
             }
-            else {
-                nestedNs = this.config.extract.defaultNS;
-            }
-        }
-        else {
-            nestedNs = this.config.extract.defaultNS;
-        }
-        let hasCount = false;
-        let context;
-        if (optionsString) {
-            // Simple regex check for count and context in the options string
-            // This is an approximation since we don't have a full JSON parser here that handles JS objects perfectly
-            // but it should cover most static cases.
-            // Check for count: ...
-            if (/['"]?count['"]?\s*:/.test(optionsString)) {
-                hasCount = true;
-            }
-            // Check for context: ...
-            const contextMatch = /['"]?context['"]?\s*:\s*(['"])(.*?)\1/.exec(optionsString);
-            if (contextMatch) {
-                context = contextMatch[2];
-            }
-        }
-        if ((hasCount && !this.config.extract.disablePlurals) || context !== undefined) {
-            this.generateNestedPluralKeys(key, nestedNs, hasCount && !this.config.extract.disablePlurals, context);
-        }
-        else {
-            this.pluginContext.addKey({ key, ns: nestedNs });
         }
     }
     generateNestedPluralKeys(key, ns, hasCount, context) {