i18next-cli 1.64.0 → 1.64.2

package/dist/cjs/cli.js

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

@@ -394,8 +394,11 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
         if (shouldFilterKey(key)) {
             return false;
         }
-        if (!hasCount) {
-            // Non-plural keys are always included
+        if (!hasCount || config.extract.disablePlurals) {
+            // Non-plural keys are always included. Under `disablePlurals`, count keys
+            // are emitted as plain keys (no plural expansion) but still carry
+            // `hasCount` so `status` can recognise them — they must bypass the
+            // plural-form filtering below and always be included, exactly as before.
             return true;
         }
         // For plural keys, check if this specific plural form is needed for the target language

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

@@ -337,12 +337,17 @@ class CallExpressionHandler {
                     // Check if plurals are disabled FIRST, before any plural optimization paths
                     if (this.config.extract.disablePlurals) {
                         // When plurals are disabled, treat count as a regular option (for interpolation only)
-                        // Still handle context normally
+                        // Still handle context normally. We keep `hasCount`/`isOrdinal` on the
+                        // emitted key so `status` knows it is count-driven and can accept the
+                        // file's plural variants (or the bare key) instead of demanding the
+                        // literal base key. File generation ignores these flags under
+                        // disablePlurals (see translation-manager), so output is unchanged.
+                        const countMeta = hasCount ? { hasCount: true, isOrdinal: isOrdinalByKey } : {};
                         if (keysWithContext.length > 0) {
-                            keysWithContext.forEach(this.pluginContext.addKey);
+                            keysWithContext.forEach(k => this.pluginContext.addKey({ ...k, ...countMeta }));
                         }
                         else {
-                            this.pluginContext.addKey({ key: finalKey, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase });
+                            this.pluginContext.addKey({ key: finalKey, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase, ...countMeta });
                         }
                         continue; // This key is fully handled
                     }

package/dist/cjs/extractor/parsers/comment-parser.js

@@ -124,14 +124,18 @@ function extractKeysFromComments(code, pluginContext, config, scopeResolver) {
                 ns = config.extract.defaultNS;
             // 5. Handle context and count combinations based on disablePlurals setting
             if (config.extract.disablePlurals) {
-                // When plurals are disabled, ignore count for key generation
+                // When plurals are disabled, ignore count for key generation. We still
+                // tag the key with `hasCount` (when a count was present) so `status` can
+                // recognise it as count-driven; file generation ignores the flag under
+                // disablePlurals (see translation-manager).
+                const countMeta = count ? { hasCount: true, isOrdinal } : {};
                 if (context) {
                     // Only generate context variants (no base key when context is static)
-                    pluginContext.addKey({ key: `${key}_${context}`, ns, defaultValue: defaultValue ?? key });
+                    pluginContext.addKey({ key: `${key}_${context}`, ns, defaultValue: defaultValue ?? key, ...countMeta });
                 }
                 else {
                     // Simple key (ignore count)
-                    pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key });
+                    pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key, ...countMeta });
                 }
             }
             else {

package/dist/cjs/extractor/parsers/jsx-handler.js

@@ -369,12 +369,16 @@ class JSXHandler {
                 else if (hasCount) {
                     // Check if plurals are disabled
                     if (this.config.extract.disablePlurals) {
-                        // When plurals are disabled, just add the base keys (no plural forms)
+                        // When plurals are disabled, just add the base keys (no plural forms).
+                        // We keep `hasCount` so `status` recognises the key as count-driven and
+                        // accepts the file's plural variants (or bare key); file generation
+                        // ignores it under disablePlurals (see translation-manager).
                         extractedKeys.forEach(extractedKey => {
                             this.pluginContext.addKey({
                                 key: extractedKey.key,
                                 ns: extractedKey.ns,
                                 defaultValue: extractedKey.defaultValue,
+                                hasCount: true,
                                 locations: extractedKey.locations
                             });
                         });

package/dist/cjs/status.js

@@ -26,6 +26,53 @@ function classifyValue(value) {
         return 'empty';
     return 'translated';
 }
+/**
+ * Representative counts used to decide which CLDR plural categories a locale can
+ * actually reach in normal usage: small integers (the common case), a handful
+ * of larger integers, and common decimals (so categories that only fire for
+ * fractional display values — e.g. Polish/Russian `other` — stay required).
+ *
+ * Any category NOT produced by these counts is treated as "optional". The prime
+ * example is French `many`, which `Intl.PluralRules` only selects for values
+ * ≥ 1,000,000 — the i18next runtime can technically request it, but real apps
+ * almost never hit those values (and the runtime falls back to the base key
+ * when the variant is missing), so a missing `_many` should be a soft note
+ * rather than a hard "missing key" failure.
+ */
+const REPRESENTATIVE_COUNTS = (() => {
+    const counts = [];
+    for (let n = 0; n <= 20; n++)
+        counts.push(n);
+    counts.push(100, 101, 1000, 1001, 10000);
+    counts.push(0.5, 1.1, 1.5, 2.5, 3.5);
+    return counts;
+})();
+const optionalCategoriesCache = new Map();
+/**
+ * Returns the CLDR plural categories for a locale that are NOT reachable by any
+ * representative count (see {@link REPRESENTATIVE_COUNTS}). These are reported
+ * by `status` as optional: a missing variant is a soft note instead of a hard
+ * absence, mirroring how the i18next runtime resolves such forms.
+ */
+function getOptionalPluralCategories(locale, isOrdinal) {
+    const type = isOrdinal ? 'ordinal' : 'cardinal';
+    const cacheKey = `${locale}|${type}`;
+    const cached = optionalCategoriesCache.get(cacheKey);
+    if (cached)
+        return cached;
+    let optional;
+    try {
+        const rules = pluralRules.safePluralRules(locale, { type });
+        const all = rules.resolvedOptions().pluralCategories;
+        const reachable = new Set(REPRESENTATIVE_COUNTS.map(n => rules.select(n)));
+        optional = new Set(all.filter(c => !reachable.has(c)));
+    }
+    catch {
+        optional = new Set();
+    }
+    optionalCategoriesCache.set(cacheKey, optional);
+    return optional;
+}
 /**
  * Runs a health check on the project's i18next translations and displays a status report.
  *
@@ -53,20 +100,44 @@ async function runStatus(config, options = {}) {
         const report = await generateStatusReport(config);
         spinner.succeed('Analysis complete.');
         await displayStatusReport(report, config, options);
+        // When a specific locale is requested (`status <locale>`), the pass/fail
+        // result must reflect THAT locale only — otherwise the displayed summary
+        // (which is scoped to the requested locale) can contradict the exit code
+        // by failing on an unrelated secondary language. See issue #271.
+        const scopedLocale = options.detail && config.locales.includes(options.detail)
+            ? options.detail
+            : undefined;
         let hasMissing = false;
-        for (const [, localeData] of report.locales.entries()) {
-            if (localeData.totalTranslated < localeData.totalKeys) {
-                hasMissing = true;
-                break;
+        if (scopedLocale) {
+            if (scopedLocale === config.extract.primaryLanguage) {
+                // The primary language fails only on absent keys (used in code but
+                // missing from the file); empty placeholders are deliberate.
+                hasMissing = !!report.primary && report.primary.totalAbsent > 0;
+            }
+            else {
+                const localeData = report.locales.get(scopedLocale);
+                hasMissing = !!localeData && localeData.totalTranslated < localeData.totalKeys;
             }
         }
-        // The primary language fails the check only on absent keys (used in code but
-        // missing from the translation file); empty placeholders are tolerated.
-        if (!hasMissing && report.primary && report.primary.totalAbsent > 0) {
-            hasMissing = true;
+        else {
+            for (const [, localeData] of report.locales.entries()) {
+                if (localeData.totalTranslated < localeData.totalKeys) {
+                    hasMissing = true;
+                    break;
+                }
+            }
+            // The primary language fails the check only on absent keys (used in code but
+            // missing from the translation file); empty placeholders are tolerated.
+            if (!hasMissing && report.primary && report.primary.totalAbsent > 0) {
+                hasMissing = true;
+            }
         }
         if (hasMissing) {
-            spinner.fail('Error: Incomplete translations detected.');
+            // Name the locale when the check is scoped so the failure reason is clear
+            // (the displayed summary already explains what is missing for it).
+            spinner.fail(scopedLocale
+                ? `Error: Incomplete translations detected for "${scopedLocale}".`
+                : 'Error: Incomplete translations detected.');
             process.exit(1);
         }
     }
@@ -222,6 +293,7 @@ async function generateStatusReport(config) {
         let totalTranslatedForLocale = 0;
         let totalEmptyForLocale = 0;
         let totalAbsentForLocale = 0;
+        let totalOptionalForLocale = 0;
         let totalKeysForLocale = 0;
         const namespaces = new Map();
         const mergedTranslations = mergeNamespaces
@@ -250,6 +322,7 @@ async function generateStatusReport(config) {
             let translatedInNs = 0;
             let emptyInNs = 0;
             let absentInNs = 0;
+            let optionalInNs = 0;
             let totalInNs = 0;
             const keyDetails = [];
             // Get the plural categories for THIS specific locale
@@ -314,37 +387,85 @@ async function generateStatusReport(config) {
                         // Only count this key if it's a plural form used by this locale
                         if (localePluralCategories.includes(category) && !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 });
+                            const optionalCategories = getOptionalPluralCategories(locale, isOrdinalVariant);
+                            // An optional category (e.g. French `_many`) is a soft note whenever
+                            // it isn't translated — whether absent or an empty placeholder that
+                            // `extract` wrote. It is never a hard failure. See #270 and
+                            // getOptionalPluralCategories.
+                            if (state !== 'translated' && optionalCategories.has(category)) {
+                                optionalInNs++;
+                                keyDetails.push({ key: baseKey, state: 'optional' });
+                            }
+                            else {
+                                totalInNs++;
+                                if (state === 'translated')
+                                    translatedInNs++;
+                                else if (state === 'empty')
+                                    emptyInNs++;
+                                else
+                                    absentInNs++;
+                                keyDetails.push({ key: baseKey, state });
+                            }
                         }
                     }
                     else {
-                        // This is a base plural key without expanded variants
-                        // Expand it according to THIS locale's plural rules
+                        // This is a base plural key without expanded variants. Mirror the
+                        // i18next runtime, where t(key, { count }) resolves `key + suffix`
+                        // and falls back to the bare `key`. A family is therefore satisfied
+                        // either by its plural variants OR by a bare key (the convention
+                        // used when `disablePlurals` is enabled and no variants are written).
                         const localePluralCategories = getLocalePluralCategories(locale, isOrdinal || false);
-                        for (const category of localePluralCategories) {
-                            const pluralKey = isOrdinal
+                        const optionalCategories = getOptionalPluralCategories(locale, isOrdinal || false);
+                        const variants = localePluralCategories.map(category => ({
+                            category,
+                            pluralKey: isOrdinal
                                 ? `${baseKey}${pluralSeparator}ordinal${pluralSeparator}${category}`
-                                : `${baseKey}${pluralSeparator}${category}`;
-                            if (processedKeys.has(pluralKey))
-                                continue;
-                            processedKeys.add(pluralKey);
+                                : `${baseKey}${pluralSeparator}${category}`,
+                        }));
+                        const anyVariantPresent = variants.some(({ pluralKey }) => resolveAndClassify(pluralKey) !== 'absent');
+                        const bareState = resolveAndClassify(baseKey);
+                        if (!anyVariantPresent && bareState !== 'absent' && !processedKeys.has(baseKey)) {
+                            // Convention (a): only the bare key exists (typical under
+                            // disablePlurals, or single-"other" languages). The runtime
+                            // resolves count via the bare key, so it satisfies the family on
+                            // its own — don't demand plural variants that were never written.
+                            processedKeys.add(baseKey);
                             totalInNs++;
-                            const state = resolveAndClassify(pluralKey);
-                            if (state === 'translated')
+                            if (bareState === 'translated')
                                 translatedInNs++;
-                            else if (state === 'empty')
+                            else if (bareState === 'empty')
                                 emptyInNs++;
                             else
                                 absentInNs++;
-                            keyDetails.push({ key: pluralKey, state });
+                            keyDetails.push({ key: baseKey, state: bareState });
+                        }
+                        else {
+                            // Convention (b): plural variants exist (or the family is missing
+                            // entirely). Evaluate each CLDR category — a missing variant is a
+                            // hard absence only when the category is required for this locale;
+                            // optional categories (e.g. French `_many`) downgrade to a soft note.
+                            for (const { category, pluralKey } of variants) {
+                                if (processedKeys.has(pluralKey))
+                                    continue;
+                                processedKeys.add(pluralKey);
+                                const state = resolveAndClassify(pluralKey);
+                                // An optional category (e.g. French `_many`) is a soft note
+                                // whenever it isn't translated — never a hard failure. See #270.
+                                if (state !== 'translated' && optionalCategories.has(category)) {
+                                    optionalInNs++;
+                                    keyDetails.push({ key: pluralKey, state: 'optional' });
+                                    continue;
+                                }
+                                totalInNs++;
+                                if (state === 'translated')
+                                    translatedInNs++;
+                                else if (state === 'empty')
+                                    emptyInNs++;
+                                else
+                                    absentInNs++;
+                                keyDetails.push({ key: pluralKey, state });
+                            }
                         }
                     }
                 }
@@ -380,10 +501,11 @@ async function generateStatusReport(config) {
                     absentInNs++;
                 keyDetails.push({ key: variantKey, state });
             }
-            namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, keyDetails });
+            namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, optionalKeys: optionalInNs, keyDetails });
             totalTranslatedForLocale += translatedInNs;
             totalEmptyForLocale += emptyInNs;
             totalAbsentForLocale += absentInNs;
+            totalOptionalForLocale += optionalInNs;
             totalKeysForLocale += totalInNs;
         }
         const localeStatus = {
@@ -391,6 +513,7 @@ async function generateStatusReport(config) {
             totalTranslated: totalTranslatedForLocale,
             totalEmpty: totalEmptyForLocale,
             totalAbsent: totalAbsentForLocale,
+            totalOptional: totalOptionalForLocale,
             namespaces,
         };
         if (isPrimary) {
@@ -482,6 +605,9 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
             else if (state === 'empty') {
                 console.log(`  ${node_util.styleText('yellow', '~')} ${key}  ${node_util.styleText('yellow', '(untranslated)')}`);
             }
+            else if (state === 'optional') {
+                console.log(`  ${node_util.styleText('gray', '○')} ${key}  ${node_util.styleText('gray', '(optional plural form)')}`);
+            }
             else {
                 console.log(`  ${node_util.styleText('red', '✗')} ${key}  ${node_util.styleText('red', '(absent)')}`);
             }

package/dist/esm/cli.js

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

@@ -392,8 +392,11 @@ function buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale,
         if (shouldFilterKey(key)) {
             return false;
         }
-        if (!hasCount) {
-            // Non-plural keys are always included
+        if (!hasCount || config.extract.disablePlurals) {
+            // Non-plural keys are always included. Under `disablePlurals`, count keys
+            // are emitted as plain keys (no plural expansion) but still carry
+            // `hasCount` so `status` can recognise them — they must bypass the
+            // plural-form filtering below and always be included, exactly as before.
             return true;
         }
         // For plural keys, check if this specific plural form is needed for the target language

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

@@ -335,12 +335,17 @@ class CallExpressionHandler {
                     // Check if plurals are disabled FIRST, before any plural optimization paths
                     if (this.config.extract.disablePlurals) {
                         // When plurals are disabled, treat count as a regular option (for interpolation only)
-                        // Still handle context normally
+                        // Still handle context normally. We keep `hasCount`/`isOrdinal` on the
+                        // emitted key so `status` knows it is count-driven and can accept the
+                        // file's plural variants (or the bare key) instead of demanding the
+                        // literal base key. File generation ignores these flags under
+                        // disablePlurals (see translation-manager), so output is unchanged.
+                        const countMeta = hasCount ? { hasCount: true, isOrdinal: isOrdinalByKey } : {};
                         if (keysWithContext.length > 0) {
-                            keysWithContext.forEach(this.pluginContext.addKey);
+                            keysWithContext.forEach(k => this.pluginContext.addKey({ ...k, ...countMeta }));
                         }
                         else {
-                            this.pluginContext.addKey({ key: finalKey, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase });
+                            this.pluginContext.addKey({ key: finalKey, ns, defaultValue: dv, explicitDefault: explicitDefaultForBase, ...countMeta });
                         }
                         continue; // This key is fully handled
                     }

package/dist/esm/extractor/parsers/comment-parser.js

@@ -122,14 +122,18 @@ function extractKeysFromComments(code, pluginContext, config, scopeResolver) {
                 ns = config.extract.defaultNS;
             // 5. Handle context and count combinations based on disablePlurals setting
             if (config.extract.disablePlurals) {
-                // When plurals are disabled, ignore count for key generation
+                // When plurals are disabled, ignore count for key generation. We still
+                // tag the key with `hasCount` (when a count was present) so `status` can
+                // recognise it as count-driven; file generation ignores the flag under
+                // disablePlurals (see translation-manager).
+                const countMeta = count ? { hasCount: true, isOrdinal } : {};
                 if (context) {
                     // Only generate context variants (no base key when context is static)
-                    pluginContext.addKey({ key: `${key}_${context}`, ns, defaultValue: defaultValue ?? key });
+                    pluginContext.addKey({ key: `${key}_${context}`, ns, defaultValue: defaultValue ?? key, ...countMeta });
                 }
                 else {
                     // Simple key (ignore count)
-                    pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key });
+                    pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key, ...countMeta });
                 }
             }
             else {

package/dist/esm/extractor/parsers/jsx-handler.js

@@ -367,12 +367,16 @@ class JSXHandler {
                 else if (hasCount) {
                     // Check if plurals are disabled
                     if (this.config.extract.disablePlurals) {
-                        // When plurals are disabled, just add the base keys (no plural forms)
+                        // When plurals are disabled, just add the base keys (no plural forms).
+                        // We keep `hasCount` so `status` recognises the key as count-driven and
+                        // accepts the file's plural variants (or bare key); file generation
+                        // ignores it under disablePlurals (see translation-manager).
                         extractedKeys.forEach(extractedKey => {
                             this.pluginContext.addKey({
                                 key: extractedKey.key,
                                 ns: extractedKey.ns,
                                 defaultValue: extractedKey.defaultValue,
+                                hasCount: true,
                                 locations: extractedKey.locations
                             });
                         });

package/dist/esm/status.js

@@ -20,6 +20,53 @@ function classifyValue(value) {
         return 'empty';
     return 'translated';
 }
+/**
+ * Representative counts used to decide which CLDR plural categories a locale can
+ * actually reach in normal usage: small integers (the common case), a handful
+ * of larger integers, and common decimals (so categories that only fire for
+ * fractional display values — e.g. Polish/Russian `other` — stay required).
+ *
+ * Any category NOT produced by these counts is treated as "optional". The prime
+ * example is French `many`, which `Intl.PluralRules` only selects for values
+ * ≥ 1,000,000 — the i18next runtime can technically request it, but real apps
+ * almost never hit those values (and the runtime falls back to the base key
+ * when the variant is missing), so a missing `_many` should be a soft note
+ * rather than a hard "missing key" failure.
+ */
+const REPRESENTATIVE_COUNTS = (() => {
+    const counts = [];
+    for (let n = 0; n <= 20; n++)
+        counts.push(n);
+    counts.push(100, 101, 1000, 1001, 10000);
+    counts.push(0.5, 1.1, 1.5, 2.5, 3.5);
+    return counts;
+})();
+const optionalCategoriesCache = new Map();
+/**
+ * Returns the CLDR plural categories for a locale that are NOT reachable by any
+ * representative count (see {@link REPRESENTATIVE_COUNTS}). These are reported
+ * by `status` as optional: a missing variant is a soft note instead of a hard
+ * absence, mirroring how the i18next runtime resolves such forms.
+ */
+function getOptionalPluralCategories(locale, isOrdinal) {
+    const type = isOrdinal ? 'ordinal' : 'cardinal';
+    const cacheKey = `${locale}|${type}`;
+    const cached = optionalCategoriesCache.get(cacheKey);
+    if (cached)
+        return cached;
+    let optional;
+    try {
+        const rules = safePluralRules(locale, { type });
+        const all = rules.resolvedOptions().pluralCategories;
+        const reachable = new Set(REPRESENTATIVE_COUNTS.map(n => rules.select(n)));
+        optional = new Set(all.filter(c => !reachable.has(c)));
+    }
+    catch {
+        optional = new Set();
+    }
+    optionalCategoriesCache.set(cacheKey, optional);
+    return optional;
+}
 /**
  * Runs a health check on the project's i18next translations and displays a status report.
  *
@@ -47,20 +94,44 @@ async function runStatus(config, options = {}) {
         const report = await generateStatusReport(config);
         spinner.succeed('Analysis complete.');
         await displayStatusReport(report, config, options);
+        // When a specific locale is requested (`status <locale>`), the pass/fail
+        // result must reflect THAT locale only — otherwise the displayed summary
+        // (which is scoped to the requested locale) can contradict the exit code
+        // by failing on an unrelated secondary language. See issue #271.
+        const scopedLocale = options.detail && config.locales.includes(options.detail)
+            ? options.detail
+            : undefined;
         let hasMissing = false;
-        for (const [, localeData] of report.locales.entries()) {
-            if (localeData.totalTranslated < localeData.totalKeys) {
-                hasMissing = true;
-                break;
+        if (scopedLocale) {
+            if (scopedLocale === config.extract.primaryLanguage) {
+                // The primary language fails only on absent keys (used in code but
+                // missing from the file); empty placeholders are deliberate.
+                hasMissing = !!report.primary && report.primary.totalAbsent > 0;
+            }
+            else {
+                const localeData = report.locales.get(scopedLocale);
+                hasMissing = !!localeData && localeData.totalTranslated < localeData.totalKeys;
             }
         }
-        // The primary language fails the check only on absent keys (used in code but
-        // missing from the translation file); empty placeholders are tolerated.
-        if (!hasMissing && report.primary && report.primary.totalAbsent > 0) {
-            hasMissing = true;
+        else {
+            for (const [, localeData] of report.locales.entries()) {
+                if (localeData.totalTranslated < localeData.totalKeys) {
+                    hasMissing = true;
+                    break;
+                }
+            }
+            // The primary language fails the check only on absent keys (used in code but
+            // missing from the translation file); empty placeholders are tolerated.
+            if (!hasMissing && report.primary && report.primary.totalAbsent > 0) {
+                hasMissing = true;
+            }
         }
         if (hasMissing) {
-            spinner.fail('Error: Incomplete translations detected.');
+            // Name the locale when the check is scoped so the failure reason is clear
+            // (the displayed summary already explains what is missing for it).
+            spinner.fail(scopedLocale
+                ? `Error: Incomplete translations detected for "${scopedLocale}".`
+                : 'Error: Incomplete translations detected.');
             process.exit(1);
         }
     }
@@ -216,6 +287,7 @@ async function generateStatusReport(config) {
         let totalTranslatedForLocale = 0;
         let totalEmptyForLocale = 0;
         let totalAbsentForLocale = 0;
+        let totalOptionalForLocale = 0;
         let totalKeysForLocale = 0;
         const namespaces = new Map();
         const mergedTranslations = mergeNamespaces
@@ -244,6 +316,7 @@ async function generateStatusReport(config) {
             let translatedInNs = 0;
             let emptyInNs = 0;
             let absentInNs = 0;
+            let optionalInNs = 0;
             let totalInNs = 0;
             const keyDetails = [];
             // Get the plural categories for THIS specific locale
@@ -308,37 +381,85 @@ async function generateStatusReport(config) {
                         // Only count this key if it's a plural form used by this locale
                         if (localePluralCategories.includes(category) && !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 });
+                            const optionalCategories = getOptionalPluralCategories(locale, isOrdinalVariant);
+                            // An optional category (e.g. French `_many`) is a soft note whenever
+                            // it isn't translated — whether absent or an empty placeholder that
+                            // `extract` wrote. It is never a hard failure. See #270 and
+                            // getOptionalPluralCategories.
+                            if (state !== 'translated' && optionalCategories.has(category)) {
+                                optionalInNs++;
+                                keyDetails.push({ key: baseKey, state: 'optional' });
+                            }
+                            else {
+                                totalInNs++;
+                                if (state === 'translated')
+                                    translatedInNs++;
+                                else if (state === 'empty')
+                                    emptyInNs++;
+                                else
+                                    absentInNs++;
+                                keyDetails.push({ key: baseKey, state });
+                            }
                         }
                     }
                     else {
-                        // This is a base plural key without expanded variants
-                        // Expand it according to THIS locale's plural rules
+                        // This is a base plural key without expanded variants. Mirror the
+                        // i18next runtime, where t(key, { count }) resolves `key + suffix`
+                        // and falls back to the bare `key`. A family is therefore satisfied
+                        // either by its plural variants OR by a bare key (the convention
+                        // used when `disablePlurals` is enabled and no variants are written).
                         const localePluralCategories = getLocalePluralCategories(locale, isOrdinal || false);
-                        for (const category of localePluralCategories) {
-                            const pluralKey = isOrdinal
+                        const optionalCategories = getOptionalPluralCategories(locale, isOrdinal || false);
+                        const variants = localePluralCategories.map(category => ({
+                            category,
+                            pluralKey: isOrdinal
                                 ? `${baseKey}${pluralSeparator}ordinal${pluralSeparator}${category}`
-                                : `${baseKey}${pluralSeparator}${category}`;
-                            if (processedKeys.has(pluralKey))
-                                continue;
-                            processedKeys.add(pluralKey);
+                                : `${baseKey}${pluralSeparator}${category}`,
+                        }));
+                        const anyVariantPresent = variants.some(({ pluralKey }) => resolveAndClassify(pluralKey) !== 'absent');
+                        const bareState = resolveAndClassify(baseKey);
+                        if (!anyVariantPresent && bareState !== 'absent' && !processedKeys.has(baseKey)) {
+                            // Convention (a): only the bare key exists (typical under
+                            // disablePlurals, or single-"other" languages). The runtime
+                            // resolves count via the bare key, so it satisfies the family on
+                            // its own — don't demand plural variants that were never written.
+                            processedKeys.add(baseKey);
                             totalInNs++;
-                            const state = resolveAndClassify(pluralKey);
-                            if (state === 'translated')
+                            if (bareState === 'translated')
                                 translatedInNs++;
-                            else if (state === 'empty')
+                            else if (bareState === 'empty')
                                 emptyInNs++;
                             else
                                 absentInNs++;
-                            keyDetails.push({ key: pluralKey, state });
+                            keyDetails.push({ key: baseKey, state: bareState });
+                        }
+                        else {
+                            // Convention (b): plural variants exist (or the family is missing
+                            // entirely). Evaluate each CLDR category — a missing variant is a
+                            // hard absence only when the category is required for this locale;
+                            // optional categories (e.g. French `_many`) downgrade to a soft note.
+                            for (const { category, pluralKey } of variants) {
+                                if (processedKeys.has(pluralKey))
+                                    continue;
+                                processedKeys.add(pluralKey);
+                                const state = resolveAndClassify(pluralKey);
+                                // An optional category (e.g. French `_many`) is a soft note
+                                // whenever it isn't translated — never a hard failure. See #270.
+                                if (state !== 'translated' && optionalCategories.has(category)) {
+                                    optionalInNs++;
+                                    keyDetails.push({ key: pluralKey, state: 'optional' });
+                                    continue;
+                                }
+                                totalInNs++;
+                                if (state === 'translated')
+                                    translatedInNs++;
+                                else if (state === 'empty')
+                                    emptyInNs++;
+                                else
+                                    absentInNs++;
+                                keyDetails.push({ key: pluralKey, state });
+                            }
                         }
                     }
                 }
@@ -374,10 +495,11 @@ async function generateStatusReport(config) {
                     absentInNs++;
                 keyDetails.push({ key: variantKey, state });
             }
-            namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, keyDetails });
+            namespaces.set(ns, { totalKeys: totalInNs, translatedKeys: translatedInNs, emptyKeys: emptyInNs, absentKeys: absentInNs, optionalKeys: optionalInNs, keyDetails });
             totalTranslatedForLocale += translatedInNs;
             totalEmptyForLocale += emptyInNs;
             totalAbsentForLocale += absentInNs;
+            totalOptionalForLocale += optionalInNs;
             totalKeysForLocale += totalInNs;
         }
         const localeStatus = {
@@ -385,6 +507,7 @@ async function generateStatusReport(config) {
             totalTranslated: totalTranslatedForLocale,
             totalEmpty: totalEmptyForLocale,
             totalAbsent: totalAbsentForLocale,
+            totalOptional: totalOptionalForLocale,
             namespaces,
         };
         if (isPrimary) {
@@ -476,6 +599,9 @@ async function displayDetailedLocaleReport(report, config, locale, namespaceFilt
             else if (state === 'empty') {
                 console.log(`  ${styleText('yellow', '~')} ${key}  ${styleText('yellow', '(untranslated)')}`);
             }
+            else if (state === 'optional') {
+                console.log(`  ${styleText('gray', '○')} ${key}  ${styleText('gray', '(optional plural form)')}`);
+            }
             else {
                 console.log(`  ${styleText('red', '✗')} ${key}  ${styleText('red', '(absent)')}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next-cli",
-  "version": "1.64.0",
+  "version": "1.64.2",
   "description": "A unified, high-performance i18next CLI.",
   "type": "module",
   "bin": {

package/types/extractor/core/translation-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translation-manager.d.ts","sourceRoot":"","sources":["../../../src/extractor/core/translation-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAujC9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,oBAAoB,EAC5B,EACE,uBAA+B,EAC/B,OAAe,EACf,oBAA4B,EAC5B,MAA4B,EAC7B,GAAE;IACD,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;CACX,GACL,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiK9B"}
+{"version":3,"file":"translation-manager.d.ts","sourceRoot":"","sources":["../../../src/extractor/core/translation-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AA0jC9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,oBAAoB,EAC5B,EACE,uBAA+B,EAC/B,OAAe,EACf,oBAA4B,EAC5B,MAA4B,EAC7B,GAAE;IACD,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;CACX,GACL,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiK9B"}

package/types/extractor/parsers/call-expression-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"call-expression-handler.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/call-expression-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAA6C,MAAM,WAAW,CAAA;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,EAAgB,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1G,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAc7D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,kBAAkB,CAAoB;IACvC,UAAU,cAAoB;IACrC,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,iBAAiB,CAAsC;gBAG7D,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,EAC7C,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,MAAM,MAAM,EAC5B,cAAc,EAAE,MAAM,MAAM,EAC5B,iBAAiB,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAA2B;IAW3E;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,GAAG,IAAI;IAyZxG;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,wBAAwB;IAyEhC;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAsDpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,uBAAuB;IAgB/B;;;;;;;;OAQG;IACH,OAAO,CAAC,iCAAiC;IAwFzC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB;IAyMxB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;CA2BxB"}
+{"version":3,"file":"call-expression-handler.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/call-expression-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAA6C,MAAM,WAAW,CAAA;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,EAAgB,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1G,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAc7D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,kBAAkB,CAAoB;IACvC,UAAU,cAAoB;IACrC,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,iBAAiB,CAAsC;gBAG7D,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,EAC7C,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,MAAM,MAAM,EAC5B,cAAc,EAAE,MAAM,MAAM,EAC5B,iBAAiB,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAA2B;IAW3E;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,GAAG,IAAI;IA8ZxG;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,wBAAwB;IAyEhC;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAsDpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,uBAAuB;IAgB/B;;;;;;;;OAQG;IACH,OAAO,CAAC,iCAAiC;IAwFzC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB;IAyMxB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;CA2BxB"}

package/types/extractor/parsers/comment-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment-parser.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/comment-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAOzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,oBAAoB,EAC5B,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC1F,IAAI,CAqJN"}
+{"version":3,"file":"comment-parser.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/comment-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAOzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,oBAAoB,EAC5B,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC1F,IAAI,CAyJN"}

package/types/extractor/parsers/jsx-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsx-handler.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/jsx-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,UAAU,EAAqC,MAAM,WAAW,CAAA;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAgB,MAAM,gBAAgB,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAS7D,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,kBAAkB,CAAoB;IAC9C,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAc;gBAGlC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,EAC7C,aAAa,EAAE,aAAa,EAC5B,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,MAAM,MAAM,EAC5B,cAAc,EAAE,MAAM,MAAM;IAS9B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iCAAiC;IAgCzC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;;;;;;OAQG;IACH,gBAAgB,CAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI;IA2UjI;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,0BAA0B;IAkIlC;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;CAevB"}
+{"version":3,"file":"jsx-handler.d.ts","sourceRoot":"","sources":["../../../src/extractor/parsers/jsx-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,UAAU,EAAqC,MAAM,WAAW,CAAA;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAgB,MAAM,gBAAgB,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAS7D,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,kBAAkB,CAAoB;IAC9C,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAc;gBAGlC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,EAC7C,aAAa,EAAE,aAAa,EAC5B,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,MAAM,MAAM,EAC5B,cAAc,EAAE,MAAM,MAAM;IAS9B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iCAAiC;IAgCzC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;;;;;;OAQG;IACH,gBAAgB,CAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI;IA+UjI;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,0BAA0B;IAkIlC;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;CAevB"}

package/types/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAgB,MAAM,YAAY,CAAA;AAOpE;;GAEG;AACH,UAAU,aAAa;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAiED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,GAAE,aAAkB,iBA4BzF"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAgB,MAAM,YAAY,CAAA;AAOpE;;GAEG;AACH,UAAU,aAAa;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAyHD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,GAAE,aAAkB,iBAoDzF"}