status: introduce fallbackNS option, to prevent missing key warnings #158

Author: adrai

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.36.0](https://github.com/i18next/i18next-cli/compare/v1.35.0...v1.36.0) - 2026-01-14
+
+- status: introduce fallbackNS option, to prevent missing key warnings [#158](https://github.com/i18next/i18next-cli/issues/158)
+
 ## [1.35.0](https://github.com/i18next/i18next-cli/compare/v1.34.1...v1.35.0) - 2026-01-12
 
 - extractor: Allow extraction from new expressions [#157](https://github.com/i18next/i18next-cli/pull/157)

README.md

@@ -379,6 +379,7 @@ export default defineConfig({
     
     // Namespace and key configuration
     defaultNS: 'translation', // If set to false it will not generate any namespace, useful if i.e. the output is a single language json with 1 namespace (and no nesting).
+    fallbackNS: 'fallback', // Namespace to use as fallback when a key is missing in the current namespace for a locale. (default undefined)
     nsSeparator: ':',
     keySeparator: '.', // Or `false` to disable nesting and use flat keys
     contextSeparator: '_',

src/status.ts

@@ -101,7 +101,7 @@ async function generateStatusReport (config: I18nextToolkitConfig): Promise<Stat
   config.extract.secondaryLanguages ||= config.locales.filter((l: string) => l !== config?.extract?.primaryLanguage)
 
   const { allKeys: allExtractedKeys } = await findKeys(config)
-  const { secondaryLanguages, keySeparator = '.', defaultNS = 'translation', mergeNamespaces = false, pluralSeparator = '_' } = config.extract
+  const { secondaryLanguages, keySeparator = '.', defaultNS = 'translation', mergeNamespaces = false, pluralSeparator = '_', fallbackNS } = config.extract
 
   const keysByNs = new Map<string, ExtractedKey[]>()
   for (const key of allExtractedKeys.values()) {
@@ -144,6 +144,14 @@ async function generateStatusReport (config: I18nextToolkitConfig): Promise<Stat
         ? (mergedTranslations?.[ns] ?? mergedTranslations ?? {})
         : await loadTranslationFile(resolve(process.cwd(), getOutputPath(config.extract.output, locale, ns))) || {}
 
+      // Load fallbackNS translations if configured
+      let fallbackTranslations: any
+      if (fallbackNS && ns !== fallbackNS) {
+        fallbackTranslations = await loadTranslationFile(
+          resolve(process.cwd(), getOutputPath(config.extract.output, locale, fallbackNS))
+        ) || {}
+      }
+
       let translatedInNs = 0
       let totalInNs = 0
       const keyDetails: Array<{ key: string; isTranslated: boolean }> = []
@@ -179,7 +187,11 @@ async function generateStatusReport (config: I18nextToolkitConfig): Promise<Stat
             // Only count this key if it's a plural form used by this locale
             if (localePluralCategories.includes(category)) {
               totalInNs++
-              const value = getNestedValue(translationsForNs, baseKey, keySeparator ?? '.')
+              let value = getNestedValue(translationsForNs, baseKey, keySeparator ?? '.')
+              // Fallback lookup
+              if (!value && fallbackTranslations) {
+                value = getNestedValue(fallbackTranslations, baseKey, keySeparator ?? '.')
+              }
               const isTranslated = !!value
               if (isTranslated) translatedInNs++
               keyDetails.push({ key: baseKey, isTranslated })
@@ -194,7 +206,11 @@ async function generateStatusReport (config: I18nextToolkitConfig): Promise<Stat
               const pluralKey = isOrdinal
                 ? `${baseKey}${pluralSeparator}ordinal${pluralSeparator}${category}`
                 : `${baseKey}${pluralSeparator}${category}`
-              const value = getNestedValue(translationsForNs, pluralKey, keySeparator ?? '.')
+              let value = getNestedValue(translationsForNs, pluralKey, keySeparator ?? '.')
+              // Fallback lookup
+              if (!value && fallbackTranslations) {
+                value = getNestedValue(fallbackTranslations, pluralKey, keySeparator ?? '.')
+              }
               const isTranslated = !!value
               if (isTranslated) translatedInNs++
               keyDetails.push({ key: pluralKey, isTranslated })
@@ -203,7 +219,11 @@ async function generateStatusReport (config: I18nextToolkitConfig): Promise<Stat
         } else {
           // It's a simple key
           totalInNs++
-          const value = getNestedValue(translationsForNs, baseKey, keySeparator ?? '.')
+          let value = getNestedValue(translationsForNs, baseKey, keySeparator ?? '.')
+          // Fallback lookup
+          if (!value && fallbackTranslations) {
+            value = getNestedValue(fallbackTranslations, baseKey, keySeparator ?? '.')
+          }
           const isTranslated = !!value
           if (isTranslated) translatedInNs++
           keyDetails.push({ key: baseKey, isTranslated })

src/types.ts

@@ -42,6 +42,9 @@ export interface I18nextToolkitConfig {
      */
     defaultNS?: string | false;
 
+    /** Namespace to use as fallback when a key is missing in the current namespace for a locale. */
+    fallbackNS?: string;
+
     /** Separator for nested keys, or false for flat keys (default: '.') */
     keySeparator?: string | false | null;
 

test/status.test.ts

@@ -672,3 +672,89 @@ describe('status (plurals)', () => {
     expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('100% (3/3 keys)'))
   })
 })
+
+describe('status (fallbackNS)', () => {
+  let consoleLogSpy: any
+  // let consoleErrorSpy: any
+  let processExitSpy: any
+
+  beforeEach(async () => {
+    vol.reset()
+    vi.clearAllMocks()
+    const { glob } = await import('glob')
+    vi.mocked(glob).mockImplementation(async (pattern: any, options?: any) => {
+      return Object.keys(vol.toJSON()).filter(p => p.includes('/src/'))
+    })
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    // consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    processExitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called')
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should not flag keys as missing if present in fallbackNS', async () => {
+    // Simulate the scenario from the bug report
+    vol.fromJSON({
+      [resolve(process.cwd(), 'src/app.tsx')]: `
+        import { useTranslation } from 'react-i18next'
+        export default function App() {
+          const { t } = useTranslation('feature')
+          return (
+            <div>
+              <p>{t('feature-specific')}</p>
+              <p>{t('ok')}</p>
+              <p>{t('cancel')}</p>
+            </div>
+          )
+        }
+      `,
+      [resolve(process.cwd(), 'locales/en/shared.json')]: JSON.stringify({
+        ok: 'This is a common string that can be used anywhere',
+        cancel: 'This is a common string',
+      }),
+      [resolve(process.cwd(), 'locales/en/feature.json')]: JSON.stringify({
+        'feature-specific': 'This is a feature-specific string',
+        cancel: 'This is an override of a common string',
+      }),
+      [resolve(process.cwd(), 'locales/de/shared.json')]: JSON.stringify({
+        ok: 'Das ist ein common text der überall verwendet werden kann',
+        cancel: 'Das ist ein common text',
+      }),
+      [resolve(process.cwd(), 'locales/de/feature.json')]: JSON.stringify({
+        'feature-specific': 'Das ist ein feature-speziefischer text',
+        cancel: 'Das sit ein überschriebener text gegenüber common',
+      }),
+    })
+
+    const config: I18nextToolkitConfig = {
+      locales: ['en', 'de'],
+      extract: {
+        input: ['src/'],
+        output: 'locales/{{language}}/{{namespace}}.json',
+        fallbackNS: 'shared',
+      },
+    }
+
+    await runStatus(config)
+
+    // const errorLogCalls = consoleErrorSpy.mock.calls.map((call: any[]) => call[0])
+
+    // Should not flag 'ok' as missing for feature namespace, since it's present in fallbackNS
+    const logCalls = consoleLogSpy.mock.calls.map((call: any[]) => call[0])
+    // Should include the expected summary lines
+    expect(logCalls).toContain('\ni18next Project Status')
+    expect(logCalls).toContain('------------------------')
+    expect(logCalls).toContain('🔑 Keys Found:         3')
+    expect(logCalls).toContain('📚 Namespaces Found:   1')
+    expect(logCalls).toContain('🌍 Locales:            en, de')
+    expect(logCalls).toContain('✅ Primary Language:   en')
+    expect(logCalls).toContain('\nTranslation Progress:')
+    // Should include the correct progress line for de (all keys present via fallbackNS)
+    expect(logCalls).toContain('- de: [■■■■■■■■■■■■■■■■■■■■] 100% (3/3 keys)')
+    expect(processExitSpy).not.toHaveBeenCalled()
+  })
+})