i18next-cli 1.55.0 → 1.56.0

package/dist/cjs/utils/nesting.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Shared parser for i18next-style nested translation references of the form
+ * `$t(key, { options })`.
+ *
+ * Used in two places:
+ * 1. The extractor's AST pass scans source-code keys and default values for
+ *    nested references and registers the referenced keys (so they show up in
+ *    output translation files).
+ * 2. The translation-manager uses it during `removeUnusedKeys` cleanup so
+ *    keys that are only referenced from inside a translation value (and thus
+ *    invisible to the AST pass) are preserved instead of being deleted.
+ */
+const naturalLanguageChars = /[ ,?!;]/;
+const looksLikeNaturalLanguage = (s) => naturalLanguageChars.test(s);
+const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Scans a string for `$t(...)` references and returns metadata about each one.
+ * The implementation mirrors the behaviour of i18next's Interpolator so that
+ * the extractor and translation manager agree on what counts as a reference.
+ */
+function parseNestedReferences(text, config) {
+    if (!text || typeof text !== 'string')
+        return [];
+    const prefix = config.nestingPrefix ?? '$t(';
+    const suffix = config.nestingSuffix ?? ')';
+    const separator = config.nestingOptionsSeparator ?? ',';
+    const nsSeparator = config.nsSeparator ?? ':';
+    const escapedPrefix = escapeRegex(prefix);
+    const escapedSuffix = escapeRegex(suffix);
+    // Regex adapted from i18next Interpolator.js — matches `$t(key)` or
+    // `$t(key, { options })` with (limited) support for balanced parens and
+    // quoted strings.
+    const nestingRegexp = new RegExp(`${escapedPrefix}((?:[^()"']+|"[^"]*"|'[^']*'|\\((?:[^()]|"[^"]*"|'[^']*')*\\))*?)${escapedSuffix}`, 'g');
+    const results = [];
+    let match;
+    while ((match = nestingRegexp.exec(text)) !== null) {
+        const content = match[1];
+        if (!content)
+            continue;
+        let key = content;
+        let optionsString = '';
+        if (content.indexOf(separator) < 0) {
+            key = content.trim();
+        }
+        else {
+            // 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();
+                optionsString = `{${parts.slice(1).join(separator + ' {')}`;
+            }
+            else {
+                const sepIdx = content.indexOf(separator);
+                key = content.substring(0, sepIdx).trim();
+                optionsString = content.substring(sepIdx + 1).trim();
+            }
+        }
+        if ((key.startsWith("'") && key.endsWith("'")) || (key.startsWith('"') && key.endsWith('"'))) {
+            key = key.slice(1, -1);
+        }
+        if (!key)
+            continue;
+        let ns;
+        if (nsSeparator && typeof nsSeparator === 'string' && key.includes(nsSeparator)) {
+            const parts = key.split(nsSeparator);
+            const candidateNs = parts[0];
+            if (!looksLikeNaturalLanguage(candidateNs)) {
+                ns = parts.shift();
+                key = parts.join(nsSeparator);
+                if (!key || key.trim() === '')
+                    continue;
+            }
+            else {
+                ns = config.defaultNS;
+            }
+        }
+        else {
+            ns = config.defaultNS;
+        }
+        let hasCount = false;
+        let context;
+        if (optionsString) {
+            if (/['"]?count['"]?\s*:/.test(optionsString)) {
+                hasCount = true;
+            }
+            const contextMatch = /['"]?context['"]?\s*:\s*(['"])(.*?)\1/.exec(optionsString);
+            if (contextMatch) {
+                context = contextMatch[2];
+            }
+        }
+        results.push({ key, ns, hasCount, context });
+    }
+    return results;
+}
+
+exports.parseNestedReferences = parseNestedReferences;

package/dist/esm/cli.js

@@ -30,7 +30,7 @@ const program = new 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.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

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

@@ -5,6 +5,8 @@ import { getOutputPath, loadTranslationFile } from '../../utils/file-utils.js';
 import { resolveDefaultValue } from '../../utils/default-value.js';
 import { ConsoleLogger } from '../../utils/logger.js';
 import { safePluralRules } from '../../utils/plural-rules.js';
+import { parseNestedReferences } from '../../utils/nesting.js';
+import { isContextVariantOfAcceptingKey } from '../../utils/context-variants.js';
 
 // used for natural language check
 const chars = [' ', ',', '?', '!', ';'];
@@ -19,58 +21,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)
@@ -283,6 +233,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) {
+            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 = 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
@@ -338,7 +382,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;
@@ -419,6 +463,35 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
             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 = getNestedKeys(primaryExistingTranslations, keySeparator ?? '.');
+        for (const primaryKey of primaryKeys) {
+            if (shouldFilterKey(primaryKey))
+                continue;
+            const isContextVariant = isContextVariantOfAcceptingKey(primaryKey, keysAcceptingContext, pluralSeparator, contextSeparator);
+            if (!isContextVariant)
+                continue;
+            const separator = primaryKey.startsWith('<') ? false : (keySeparator ?? '.');
+            const alreadySet = 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 = getNestedValue(existingTranslations, primaryKey, separator);
+            const valueToSet = existingSecondaryValue !== undefined
+                ? existingSecondaryValue
+                : resolveDefaultValue(emptyDefaultValue, primaryKey, namespace || config?.extract?.defaultNS || 'translation', locale);
+            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/esm/extractor/parsers/call-expression-handler.js

@@ -1,4 +1,5 @@
 import { safePluralRules } from '../../utils/plural-rules.js';
+import { parseNestedReferences } from '../../utils/nesting.js';
 import { lineColumnFromOffset, isSimpleTemplateLiteral, getObjectPropValue, getObjectPropValueExpression } from './ast-utils.js';
 
 // Helper to escape regex characters
@@ -452,103 +453,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 = 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/esm/status.js

@@ -5,9 +5,10 @@ import '@swc/core';
 import 'node:fs/promises';
 import { findKeys } from './extractor/core/key-finder.js';
 import 'glob';
-import { getNestedValue } from './utils/nested-object.js';
+import { getNestedKeys, getNestedValue } from './utils/nested-object.js';
 import { loadTranslationFile, getOutputPath } from './utils/file-utils.js';
 import { safePluralRules } from './utils/plural-rules.js';
+import { isContextVariantOfAcceptingKey } from './utils/context-variants.js';
 import { shouldShowFunnel, recordFunnelShown } from './utils/funnel-msg-tracker.js';
 import './extractor/parsers/jsx-parser.js';
 
@@ -80,7 +81,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 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';
@@ -103,6 +105,40 @@ async function generateStatusReport(config) {
         keysByNs,
         locales: new Map(),
     };
+    // Discover context variants that live in the primary translation file but
+    // are not directly extracted as keys (see issue #243). When source code uses
+    // a dynamic context value like `t('exportType', { context: type })`, the
+    // extractor can only tag the base key as "accepting context"; the actual
+    // context values (`_gas`, `_water`, ...) are only visible in the primary
+    // translation file. Without this scan, status never checks those variants
+    // for translation gaps in secondary locales.
+    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();
+    if (keysAcceptingContext.size > 0) {
+        const primaryMerged = mergeNamespaces
+            ? ((await loadTranslationFile(resolve(process.cwd(), getOutputPath(config.extract.output, primaryLanguage, (defaultNS === false ? 'translation' : (defaultNS || 'translation')))))) || {})
+            : null;
+        for (const ns of keysByNs.keys()) {
+            const primaryNsTranslations = mergeNamespaces
+                ? (primaryMerged?.[ns] ?? primaryMerged ?? {})
+                : ((await loadTranslationFile(resolve(process.cwd(), getOutputPath(config.extract.output, primaryLanguage, ns)))) || {});
+            const primaryKeys = getNestedKeys(primaryNsTranslations, keySeparator ?? '.');
+            const variants = [];
+            for (const primaryKey of primaryKeys) {
+                if (isContextVariantOfAcceptingKey(primaryKey, keysAcceptingContext, pluralSeparator, contextSeparator)) {
+                    variants.push(primaryKey);
+                }
+            }
+            if (variants.length > 0)
+                contextVariantsByNs.set(ns, variants);
+        }
+    }
     for (const locale of secondaryLanguages) {
         let totalTranslatedForLocale = 0;
         let totalEmptyForLocale = 0;
@@ -170,6 +206,7 @@ async function generateStatusReport(config) {
                 }
                 return primaryState;
             };
+            const processedKeys = new Set();
             for (const { key: baseKey, hasCount, isOrdinal, isExpandedPlural } of keysInNs) {
                 if (hasCount) {
                     if (isExpandedPlural) {
@@ -183,7 +220,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')
@@ -200,10 +238,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++;
@@ -216,17 +257,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/esm/utils/context-variants.js

@@ -0,0 +1,57 @@
+/**
+ * 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;
+}
+
+export { isContextVariantOfAcceptingKey };