i18next-cli 1.55.0 → 1.56.1

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

@@ -32,7 +32,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.55.0'); // This string is replaced with the actual version at build time by rollup
+    .version('1.56.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

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) {

package/dist/cjs/status.js

@@ -10,6 +10,8 @@ require('glob');
 var nestedObject = require('./utils/nested-object.js');
 var fileUtils = require('./utils/file-utils.js');
 var pluralRules = require('./utils/plural-rules.js');
+var nesting = require('./utils/nesting.js');
+var contextVariants = require('./utils/context-variants.js');
 var funnelMsgTracker = require('./utils/funnel-msg-tracker.js');
 require('./extractor/parsers/jsx-parser.js');
 
@@ -82,7 +84,8 @@ async function generateStatusReport(config) {
     config.extract.primaryLanguage ||= config.locales[0] || 'en';
     config.extract.secondaryLanguages ||= config.locales.filter((l) => l !== config?.extract?.primaryLanguage);
     const { allKeys: allExtractedKeys } = await keyFinder.findKeys(config);
-    const { secondaryLanguages, keySeparator = '.', defaultNS = 'translation', mergeNamespaces = false, pluralSeparator = '_', fallbackNS } = config.extract;
+    const { secondaryLanguages, keySeparator = '.', defaultNS = 'translation', mergeNamespaces = false, pluralSeparator = '_', contextSeparator = '_', fallbackNS } = config.extract;
+    const primaryLanguage = config.extract.primaryLanguage || config.locales[0] || 'en';
     const keysByNs = new Map();
     for (const key of allExtractedKeys.values()) {
         const ns = key.ns || defaultNS || 'translation';
@@ -105,6 +108,101 @@ async function generateStatusReport(config) {
         keysByNs,
         locales: new Map(),
     };
+    // Build per-namespace "virtual" key lists for translation entries that the
+    // AST-based extractor cannot see on its own. Both inputs come from the
+    // primary translation file:
+    //
+    //  1. Context variants of an accepting-context key (see issue #243).
+    //     `t('exportType', { context: dynamic })` only registers the base key;
+    //     the concrete `exportType_gas` / `exportType_water` variants live in
+    //     the primary file.
+    //
+    //  2. Keys reachable only via `$t(...)` nested references from inside an
+    //     existing translation value (see follow-up to issue #241).
+    //     `"girlsAndBoys": "... $t(boys, {\"count\": x}) ..."` doesn't appear
+    //     in source code, yet the referenced keys (`boys`, plus per-locale
+    //     plural forms) must be checked in every secondary locale.
+    //
+    // Both scans need the primary translation file per namespace, so the load
+    // is shared.
+    const keysAcceptingContext = new Set();
+    for (const keys of keysByNs.values()) {
+        for (const k of keys) {
+            if (k.keyAcceptingContext)
+                keysAcceptingContext.add(k.keyAcceptingContext);
+        }
+    }
+    const contextVariantsByNs = new Map();
+    const nestedReferenceKeysByNs = new Map();
+    const primaryMergedForScan = mergeNamespaces
+        ? ((await fileUtils.loadTranslationFile(node_path.resolve(process.cwd(), fileUtils.getOutputPath(config.extract.output, primaryLanguage, (defaultNS === false ? 'translation' : (defaultNS || 'translation')))))) || {})
+        : null;
+    const collectNestedRefsFromValue = (value, refNs, bucket, seen) => {
+        if (typeof value === 'string') {
+            if (seen.has(value))
+                return;
+            seen.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) {
+                // References with an explicit namespace that differs from the current
+                // bucket are ignored — they belong to another namespace's scan.
+                const normalizedRefNs = ref.ns === undefined || ref.ns === null
+                    ? (config.extract.defaultNS ?? 'translation')
+                    : ref.ns;
+                if (normalizedRefNs !== refNs)
+                    continue;
+                if (ref.context !== undefined) {
+                    const ctxKey = `${ref.key}${contextSeparator}${ref.context}`;
+                    if (ref.hasCount) {
+                        // Treat `key_ctx` as a base plural key; the per-locale loop
+                        // expands it into the correct CLDR forms for each target locale.
+                        bucket.push({ key: ctxKey, hasCount: true });
+                    }
+                    else {
+                        bucket.push({ key: ref.key });
+                        bucket.push({ key: ctxKey });
+                    }
+                }
+                else if (ref.hasCount) {
+                    bucket.push({ key: ref.key, hasCount: true });
+                }
+                else {
+                    bucket.push({ key: ref.key });
+                }
+            }
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const v of Object.values(value)) {
+                collectNestedRefsFromValue(v, refNs, bucket, seen);
+            }
+        }
+    };
+    for (const ns of keysByNs.keys()) {
+        const primaryNsTranslations = mergeNamespaces
+            ? (primaryMergedForScan?.[ns] ?? primaryMergedForScan ?? {})
+            : ((await fileUtils.loadTranslationFile(node_path.resolve(process.cwd(), fileUtils.getOutputPath(config.extract.output, primaryLanguage, ns)))) || {});
+        if (keysAcceptingContext.size > 0) {
+            const primaryKeys = nestedObject.getNestedKeys(primaryNsTranslations, keySeparator ?? '.');
+            const variants = [];
+            for (const primaryKey of primaryKeys) {
+                if (contextVariants.isContextVariantOfAcceptingKey(primaryKey, keysAcceptingContext, pluralSeparator, contextSeparator)) {
+                    variants.push(primaryKey);
+                }
+            }
+            if (variants.length > 0)
+                contextVariantsByNs.set(ns, variants);
+        }
+        const nestedRefKeys = [];
+        collectNestedRefsFromValue(primaryNsTranslations, ns, nestedRefKeys, new Set());
+        if (nestedRefKeys.length > 0)
+            nestedReferenceKeysByNs.set(ns, nestedRefKeys);
+    }
     for (const locale of secondaryLanguages) {
         let totalTranslatedForLocale = 0;
         let totalEmptyForLocale = 0;
@@ -172,7 +270,15 @@ async function generateStatusReport(config) {
                 }
                 return primaryState;
             };
-            for (const { key: baseKey, hasCount, isOrdinal, isExpandedPlural } of keysInNs) {
+            const processedKeys = new Set();
+            // Combine AST-extracted keys with nested-reference keys discovered in
+            // the primary translation file (see follow-up on issue #241). Both go
+            // through the same plural-expansion logic; processedKeys dedupes.
+            const nestedRefKeys = nestedReferenceKeysByNs.get(ns) || [];
+            const combinedKeysInNs = nestedRefKeys.length > 0
+                ? [...keysInNs, ...nestedRefKeys]
+                : keysInNs;
+            for (const { key: baseKey, hasCount, isOrdinal, isExpandedPlural } of combinedKeysInNs) {
                 if (hasCount) {
                     if (isExpandedPlural) {
                         // This is an already-expanded plural variant key (e.g., key_one, key_other)
@@ -185,7 +291,8 @@ async function generateStatusReport(config) {
                         // Get the plural categories for this locale
                         const localePluralCategories = getLocalePluralCategories(locale, isOrdinalVariant);
                         // Only count this key if it's a plural form used by this locale
-                        if (localePluralCategories.includes(category)) {
+                        if (localePluralCategories.includes(category) && !processedKeys.has(baseKey)) {
+                            processedKeys.add(baseKey);
                             totalInNs++;
                             const state = resolveAndClassify(baseKey);
                             if (state === 'translated')
@@ -202,10 +309,13 @@ async function generateStatusReport(config) {
                         // Expand it according to THIS locale's plural rules
                         const localePluralCategories = getLocalePluralCategories(locale, isOrdinal || false);
                         for (const category of localePluralCategories) {
-                            totalInNs++;
                             const pluralKey = isOrdinal
                                 ? `${baseKey}${pluralSeparator}ordinal${pluralSeparator}${category}`
                                 : `${baseKey}${pluralSeparator}${category}`;
+                            if (processedKeys.has(pluralKey))
+                                continue;
+                            processedKeys.add(pluralKey);
+                            totalInNs++;
                             const state = resolveAndClassify(pluralKey);
                             if (state === 'translated')
                                 translatedInNs++;
@@ -218,17 +328,37 @@ async function generateStatusReport(config) {
                     }
                 }
                 else {
-                    totalInNs++;
-                    const state = resolveAndClassify(baseKey);
-                    if (state === 'translated')
-                        translatedInNs++;
-                    else if (state === 'empty')
-                        emptyInNs++;
-                    else
-                        absentInNs++;
-                    keyDetails.push({ key: baseKey, state });
+                    if (!processedKeys.has(baseKey)) {
+                        processedKeys.add(baseKey);
+                        totalInNs++;
+                        const state = resolveAndClassify(baseKey);
+                        if (state === 'translated')
+                            translatedInNs++;
+                        else if (state === 'empty')
+                            emptyInNs++;
+                        else
+                            absentInNs++;
+                        keyDetails.push({ key: baseKey, state });
+                    }
                 }
             }
+            // Additionally check context variants discovered in the primary file
+            // (see issue #243). Skip variants already counted via extracted keys.
+            const contextVariants = contextVariantsByNs.get(ns) || [];
+            for (const variantKey of contextVariants) {
+                if (processedKeys.has(variantKey))
+                    continue;
+                processedKeys.add(variantKey);
+                totalInNs++;
+                const state = resolveAndClassify(variantKey);
+                if (state === 'translated')
+                    translatedInNs++;
+                else if (state === 'empty')
+                    emptyInNs++;
+                else
+                    absentInNs++;
+                keyDetails.push({ key: variantKey, state });
+            }
             namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, keyDetails });
             totalTranslatedForLocale += translatedInNs;
             totalEmptyForLocale += emptyInNs;

package/dist/cjs/utils/context-variants.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Helpers for reasoning about context variants of translation keys.
+ *
+ * A "key accepting context" is a base key that was called with a `context`
+ * option in source code (e.g. `t('friend', { context: gender })`). Its
+ * variants in the translation file look like `<base><contextSeparator><ctx>`
+ * (optionally suffixed with a CLDR plural form).
+ */
+const pluralForms = ['zero', 'one', 'two', 'few', 'many', 'other'];
+/**
+ * Checks if an existing key is a context variant of a base key that accepts context.
+ * Handles:
+ * - Keys suffixed with a CLDR plural form (e.g. `friend_male_one`).
+ * - Context values that 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;
+    }
+    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;
+        }
+    }
+    // The context value itself may contain the separator — try every possible
+    // split to find a base that matches an accepting-context key.
+    const parts = potentialBaseKey.split(contextSeparator);
+    if (parts.length > 1) {
+        for (let i = 1; i < parts.length; i++) {
+            const baseWithoutContext = parts.slice(0, -i).join(contextSeparator);
+            if (keysAcceptingContext.has(baseWithoutContext)) {
+                return true;
+            }
+        }
+    }
+    // Also accept the plural-stripped key itself as a direct match
+    // (e.g. `friend_other` → base `friend`).
+    if (keysAcceptingContext.has(potentialBaseKey)) {
+        return true;
+    }
+    return false;
+}
+
+exports.isContextVariantOfAcceptingKey = isContextVariantOfAcceptingKey;