i18next-cli 1.7.1 → 1.9.0

package/src/extractor/core/translation-manager.ts

@@ -3,6 +3,7 @@ import { resolve, basename, extname } from 'node:path'
 import { glob } from 'glob'
 import { getNestedValue, setNestedValue, getNestedKeys } from '../../utils/nested-object'
 import { getOutputPath, loadTranslationFile } from '../../utils/file-utils'
+import { resolveDefaultValue } from '../../utils/default-value'
 
 /**
  * Converts a glob pattern to a regular expression for matching keys
@@ -52,6 +53,7 @@ function buildNewTranslationsForNs (
   existingTranslations: Record<string, any>,
   config: I18nextToolkitConfig,
   locale: string,
+  namespace: string,
   preservePatterns: RegExp[],
   objectKeys: Set<string>
 ): Record<string, any> {
@@ -61,8 +63,49 @@ function buildNewTranslationsForNs (
     removeUnusedKeys = true,
     primaryLanguage,
     defaultValue: emptyDefaultValue = '',
+    pluralSeparator = '_',
   } = config.extract
 
+  // Get the plural categories for the target language
+  const targetLanguagePluralCategories = new Set<string>()
+  try {
+    const cardinalRules = new Intl.PluralRules(locale, { type: 'cardinal' })
+    const ordinalRules = new Intl.PluralRules(locale, { type: 'ordinal' })
+
+    cardinalRules.resolvedOptions().pluralCategories.forEach(cat => targetLanguagePluralCategories.add(cat))
+    ordinalRules.resolvedOptions().pluralCategories.forEach(cat => targetLanguagePluralCategories.add(`ordinal_${cat}`))
+  } catch (e) {
+    // Fallback to English if locale is invalid
+    const cardinalRules = new Intl.PluralRules(primaryLanguage || 'en', { type: 'cardinal' })
+    const ordinalRules = new Intl.PluralRules(primaryLanguage || 'en', { type: 'ordinal' })
+
+    cardinalRules.resolvedOptions().pluralCategories.forEach(cat => targetLanguagePluralCategories.add(cat))
+    ordinalRules.resolvedOptions().pluralCategories.forEach(cat => targetLanguagePluralCategories.add(`ordinal_${cat}`))
+  }
+
+  // Filter nsKeys to only include keys relevant to this language
+  const filteredKeys = nsKeys.filter(({ key, hasCount, isOrdinal }) => {
+    if (!hasCount) {
+      // Non-plural keys are always included
+      return true
+    }
+
+    // For plural keys, check if this specific plural form is needed for the target language
+    const keyParts = key.split(pluralSeparator)
+
+    if (isOrdinal && keyParts.includes('ordinal')) {
+      // For ordinal plurals: key_context_ordinal_category or key_ordinal_category
+      const lastPart = keyParts[keyParts.length - 1]
+      return targetLanguagePluralCategories.has(`ordinal_${lastPart}`)
+    } else if (hasCount) {
+      // For cardinal plurals: key_context_category or key_category
+      const lastPart = keyParts[keyParts.length - 1]
+      return targetLanguagePluralCategories.has(lastPart)
+    }
+
+    return true
+  })
+
   // If `removeUnusedKeys` is true, start with an empty object. Otherwise, start with a clone of the existing translations.
   let newTranslations: Record<string, any> = removeUnusedKeys
     ? {}
@@ -78,9 +121,9 @@ function buildNewTranslationsForNs (
   }
 
   // 1. Build the object first, without any sorting.
-  for (const { key, defaultValue } of nsKeys) {
+  for (const { key, defaultValue } of filteredKeys) {
     const existingValue = getNestedValue(existingTranslations, key, keySeparator ?? '.')
-    const isLeafInNewKeys = !nsKeys.some(otherKey => otherKey.key.startsWith(`${key}${keySeparator}`) && otherKey.key !== key)
+    const isLeafInNewKeys = !filteredKeys.some(otherKey => otherKey.key.startsWith(`${key}${keySeparator}`) && otherKey.key !== key)
 
     // Determine if we should preserve an existing object
     const shouldPreserveObject = typeof existingValue === 'object' && existingValue !== null && (
@@ -96,9 +139,17 @@ function buildNewTranslationsForNs (
       continue
     }
 
-    const valueToSet = (existingValue === undefined || isStaleObject)
-      ? (locale === primaryLanguage ? defaultValue : emptyDefaultValue)
-      : existingValue
+    let valueToSet: string
+    if (existingValue === undefined || isStaleObject) {
+      if (locale === primaryLanguage) {
+        valueToSet = defaultValue || key
+      } else {
+        // For secondary languages, use the resolved default value
+        valueToSet = resolveDefaultValue(emptyDefaultValue, key, namespace, locale)
+      }
+    } else {
+      valueToSet = existingValue
+    }
 
     setNestedValue(newTranslations, key, valueToSet, keySeparator ?? '.')
   }
@@ -117,7 +168,7 @@ function buildNewTranslationsForNs (
     // Create a map of top-level keys to a representative ExtractedKey object.
     // This is needed for the custom sort function.
     const keyMap = new Map<string, ExtractedKey>()
-    for (const ek of nsKeys) {
+    for (const ek of filteredKeys) {
       const topLevelKey = keySeparator === false ? ek.key : ek.key.split(keySeparator as string)[0]
       if (!keyMap.has(topLevelKey)) {
         keyMap.set(topLevelKey, ek)
@@ -223,7 +274,7 @@ export async function getTranslations (
       for (const ns of namespacesToProcess) {
         const nsKeys = keysByNS.get(ns) || []
         const existingTranslations = existingMergedFile[ns] || {}
-        newMergedTranslations[ns] = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, preservePatterns, objectKeys)
+        newMergedTranslations[ns] = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, ns, preservePatterns, objectKeys)
       }
 
       const oldContent = JSON.stringify(existingMergedFile, null, indentation)
@@ -247,7 +298,7 @@ export async function getTranslations (
         const outputPath = getOutputPath(config.extract.output, locale, ns)
         const fullPath = resolve(process.cwd(), outputPath)
         const existingTranslations = await loadTranslationFile(fullPath) || {}
-        const newTranslations = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, preservePatterns, objectKeys)
+        const newTranslations = buildNewTranslationsForNs(nsKeys, existingTranslations, config, locale, ns, preservePatterns, objectKeys)
 
         const oldContent = JSON.stringify(existingTranslations, null, indentation)
         const newContent = JSON.stringify(newTranslations, null, indentation)

package/src/extractor/parsers/ast-visitors.ts

@@ -1,4 +1,4 @@
-import type { Module, Node, CallExpression, VariableDeclarator, JSXElement, ArrowFunctionExpression, ObjectExpression, Expression, TemplateLiteral } from '@swc/core'
+import type { Module, Node, CallExpression, VariableDeclarator, JSXElement, ArrowFunctionExpression, ObjectExpression, Expression, TemplateLiteral, TsType, TsTemplateLiteralType } from '@swc/core'
 import type { PluginContext, I18nextToolkitConfig, Logger, ExtractedKey, ScopeInfo } from '../../types'
 import { extractFromTransComponent } from './jsx-parser'
 import { getObjectProperty, getObjectPropValue } from './ast-utils'
@@ -597,12 +597,12 @@ export class ASTVisitors {
           // If we have keys with context pluralize them
           if (keysWithContext.length > 0) {
             for (const { key, ns } of keysWithContext) {
-              // Pass the combined ordinal flag to the handler
-              this.handlePluralKeys(key, ns, options, isOrdinalByOption || isOrdinalByKey)
+              // Pass the combined ordinal flag and the default value to the handler
+              this.handlePluralKeys(key, ns, options, isOrdinalByOption || isOrdinalByKey, finalDefaultValue)
             }
           } else {
             // Otherwise pluralize the base key
-            this.handlePluralKeys(finalKey, ns, options, isOrdinalByOption || isOrdinalByKey)
+            this.handlePluralKeys(finalKey, ns, options, isOrdinalByOption || isOrdinalByKey, finalDefaultValue)
           }
 
           continue // This key is fully handled
@@ -683,11 +683,27 @@ export class ASTVisitors {
    *
    * @private
    */
-  private handlePluralKeys (key: string, ns: string | undefined, options: ObjectExpression, isOrdinal: boolean): void {
+  private handlePluralKeys (key: string, ns: string | undefined, options: ObjectExpression, isOrdinal: boolean, defaultValueFromCall?: string): void {
     try {
       const type = isOrdinal ? 'ordinal' : 'cardinal'
 
-      const pluralCategories = new Intl.PluralRules(this.config.extract?.primaryLanguage, { type }).resolvedOptions().pluralCategories
+      // Generate plural forms for ALL target languages to ensure we have all necessary keys
+      const allPluralCategories = new Set<string>()
+
+      for (const locale of this.config.locales) {
+        try {
+          const pluralRules = new Intl.PluralRules(locale, { type })
+          const categories = pluralRules.resolvedOptions().pluralCategories
+          categories.forEach(cat => allPluralCategories.add(cat))
+        } catch (e) {
+          // If a locale is invalid, fall back to English rules
+          const englishRules = new Intl.PluralRules('en', { type })
+          const categories = englishRules.resolvedOptions().pluralCategories
+          categories.forEach(cat => allPluralCategories.add(cat))
+        }
+      }
+
+      const pluralCategories = Array.from(allPluralCategories).sort()
       const pluralSeparator = this.config.extract.pluralSeparator ?? '_'
 
       // Get all possible default values once at the start
@@ -695,50 +711,91 @@ export class ASTVisitors {
       const otherDefault = getObjectPropValue(options, `defaultValue${pluralSeparator}other`)
       const ordinalOtherDefault = getObjectPropValue(options, `defaultValue${pluralSeparator}ordinal${pluralSeparator}other`)
 
-      for (const category of pluralCategories) {
-        // 1. Look for the most specific default value (e.g., defaultValue_ordinal_one)
-        const specificDefaultKey = isOrdinal ? `defaultValue${pluralSeparator}ordinal${pluralSeparator}${category}` : `defaultValue${pluralSeparator}${category}`
-        const specificDefault = getObjectPropValue(options, specificDefaultKey)
+      // Get the count value and determine target category if available
+      const countValue = getObjectPropValue(options, 'count')
+      let targetCategory: string | undefined
+
+      if (typeof countValue === 'number') {
+        try {
+          const primaryLanguage = this.config.extract?.primaryLanguage || this.config.locales[0] || 'en'
+          const pluralRules = new Intl.PluralRules(primaryLanguage, { type })
+          targetCategory = pluralRules.select(countValue)
+        } catch (e) {
+          // If we can't determine the category, continue with normal logic
+        }
+      }
 
-        // 2. Determine the final default value using a clear fallback chain
-        let finalDefaultValue: string | undefined
-        if (typeof specificDefault === 'string') {
-          // 1. Use the most specific default if it exists (e.g., defaultValue_one)
-          finalDefaultValue = specificDefault
-        } else if (category === 'one' && typeof defaultValue === 'string') {
-          // 2. SPECIAL CASE: The 'one' category falls back to the main 'defaultValue' prop
-          finalDefaultValue = defaultValue
-        } else if (isOrdinal && typeof ordinalOtherDefault === 'string') {
-          // 3a. Other ordinal categories fall back to 'defaultValue_ordinal_other'
-          finalDefaultValue = ordinalOtherDefault
-        } else if (!isOrdinal && typeof otherDefault === 'string') {
-          // 3b. Other cardinal categories fall back to 'defaultValue_other'
-          finalDefaultValue = otherDefault
-        } else if (typeof defaultValue === 'string') {
-          // 4. If no '_other' is found, all categories can fall back to the main 'defaultValue'
-          finalDefaultValue = defaultValue
-        } else {
-          // 5. Final fallback to the base key itself
-          finalDefaultValue = key
+      // Check if context is present
+      const contextValue = getObjectPropValue(options, 'context')
+      const hasContext = typeof contextValue === 'string' && contextValue.length > 0
+
+      // Determine which key variants to generate
+      const keysToGenerate: Array<{ key: string, context?: string }> = []
+
+      if (hasContext) {
+        // Generate keys for the specific context
+        keysToGenerate.push({ key, context: contextValue })
+
+        // Only generate base plural forms if generateBasePluralForms is not disabled
+        const shouldGenerateBaseForms = this.config.extract?.generateBasePluralForms !== false
+        if (shouldGenerateBaseForms) {
+          keysToGenerate.push({ key })
         }
+      } else {
+        // No context, always generate base plural forms
+        keysToGenerate.push({ key })
+      }
 
-        // 3. Construct the final plural key
-        const finalKey = isOrdinal
-          ? `${key}${pluralSeparator}ordinal${pluralSeparator}${category}`
-          : `${key}${pluralSeparator}${category}`
+      // Generate plural forms for each key variant
+      for (const { key: baseKey, context } of keysToGenerate) {
+        for (const category of pluralCategories) {
+          // 1. Look for the most specific default value
+          const specificDefaultKey = isOrdinal ? `defaultValue${pluralSeparator}ordinal${pluralSeparator}${category}` : `defaultValue${pluralSeparator}${category}`
+          const specificDefault = getObjectPropValue(options, specificDefaultKey)
+
+          // 2. Determine the final default value using a clear fallback chain
+          let finalDefaultValue: string | undefined
+          if (typeof specificDefault === 'string') {
+            finalDefaultValue = specificDefault
+          } else if (category === 'one' && typeof defaultValue === 'string') {
+            finalDefaultValue = defaultValue
+          } else if (isOrdinal && typeof ordinalOtherDefault === 'string') {
+            finalDefaultValue = ordinalOtherDefault
+          } else if (!isOrdinal && typeof otherDefault === 'string') {
+            finalDefaultValue = otherDefault
+          } else if (typeof defaultValue === 'string') {
+            finalDefaultValue = defaultValue
+          } else if (defaultValueFromCall && targetCategory === category) {
+            finalDefaultValue = defaultValueFromCall
+          } else {
+            finalDefaultValue = baseKey
+          }
 
-        this.pluginContext.addKey({
-          key: finalKey,
-          ns,
-          defaultValue: finalDefaultValue,
-          hasCount: true,
-          isOrdinal
-        })
+          // 3. Construct the final plural key
+          let finalKey: string
+          if (context) {
+            finalKey = isOrdinal
+              ? `${baseKey}${pluralSeparator}${context}${pluralSeparator}ordinal${pluralSeparator}${category}`
+              : `${baseKey}${pluralSeparator}${context}${pluralSeparator}${category}`
+          } else {
+            finalKey = isOrdinal
+              ? `${baseKey}${pluralSeparator}ordinal${pluralSeparator}${category}`
+              : `${baseKey}${pluralSeparator}${category}`
+          }
+
+          this.pluginContext.addKey({
+            key: finalKey,
+            ns,
+            defaultValue: finalDefaultValue,
+            hasCount: true,
+            isOrdinal
+          })
+        }
       }
     } catch (e) {
       this.logger.warn(`Could not determine plural rules for language "${this.config.extract?.primaryLanguage}". Falling back to simple key extraction.`)
       // Fallback to a simple key if Intl API fails
-      const defaultValue = getObjectPropValue(options, 'defaultValue')
+      const defaultValue = defaultValueFromCall || getObjectPropValue(options, 'defaultValue')
       this.pluginContext.addKey({ key, ns, defaultValue: typeof defaultValue === 'string' ? defaultValue : key })
     }
   }
@@ -789,7 +846,13 @@ export class ASTVisitors {
               key = parts.join(nsSeparator)
             }
 
-            return { key, ns, defaultValue: defaultValue || serializedChildren, hasCount, isOrdinal }
+            return {
+              key,
+              ns,
+              defaultValue: defaultValue || serializedChildren,
+              hasCount,
+              isOrdinal,
+            }
           })
 
           const tProp = node.opening.attributes?.find(
@@ -818,7 +881,13 @@ export class ASTVisitors {
         } else {
           const { ns } = extractedAttributes
           extractedKeys = keysToProcess.map(key => {
-            return { key, ns, defaultValue: defaultValue || serializedChildren, hasCount, isOrdinal, }
+            return {
+              key,
+              ns,
+              defaultValue: defaultValue || serializedChildren,
+              hasCount,
+              isOrdinal,
+            }
           })
         }
 
@@ -1128,17 +1197,49 @@ export class ASTVisitors {
       return [`${expression.value}`] // Handle literals like 5 or true
     }
 
+    // Support building translation keys for
+    // `variable satisfies 'coaching' | 'therapy'`
+    if (expression.type === 'TsSatisfiesExpression' || expression.type === 'TsAsExpression') {
+      const annotation = expression.typeAnnotation
+
+      return this.resolvePossibleStringValuesFromType(annotation, returnEmptyStrings)
+    }
+
+    // We can't statically determine the value of other expressions (e.g., variables, function calls)
+    return []
+  }
+
+  private resolvePossibleStringValuesFromType (type: TsType, returnEmptyStrings = false): string[] {
+    if (type.type === 'TsUnionType') {
+      return type.types.flatMap((t) => this.resolvePossibleStringValuesFromType(t, returnEmptyStrings))
+    }
+
+    if (type.type === 'TsLiteralType') {
+      if (type.literal.type === 'StringLiteral') {
+        // Filter out empty strings as they should be treated as "no context" like i18next does
+        return type.literal.value || returnEmptyStrings ? [type.literal.value] : []
+      }
+
+      if (type.literal.type === 'TemplateLiteral') {
+        return this.resolvePossibleStringValuesFromTemplateLiteralType(type.literal)
+      }
+
+      if (type.literal.type === 'NumericLiteral' || type.literal.type === 'BooleanLiteral') {
+        return [`${type.literal.value}`] // Handle literals like 5 or true
+      }
+    }
+
     // We can't statically determine the value of other expressions (e.g., variables, function calls)
     return []
   }
 
   /**
-   * Resolves a template literal to one or more possible string values that can be
+   * Resolves a template literal string to one or more possible strings that can be
    * determined statically from the AST.
    *
    * @private
-   * @param templateString - The SWC AST template literal node to resolve
-   * @returns An array of possible string values that the template literal may produce.
+   * @param templateString - The SWC AST template literal string to resolve
+   * @returns An array of possible string values that the template may produce.
    */
   private resolvePossibleStringValuesFromTemplateString (templateString: TemplateLiteral): string[] {
     // If there are no expressions, we can just return the cooked value
@@ -1147,7 +1248,7 @@ export class ASTVisitors {
       return [templateString.quasis[0].cooked || '']
     }
 
-    // Ex. `translation.key.with.expression.${x ? 'title' : 'description}`
+    // Ex. `translation.key.with.expression.${x ? 'title' : 'description'}`
     const [firstQuasis, ...tails] = templateString.quasis
 
     const stringValues = templateString.expressions.reduce(
@@ -1165,6 +1266,39 @@ export class ASTVisitors {
     return stringValues
   }
 
+  /**
+   * Resolves a template literal type to one or more possible strings that can be
+   * determined statically from the AST.
+   *
+   * @private
+   * @param templateLiteralType - The SWC AST template literal type to resolve
+   * @returns An array of possible string values that the template may produce.
+   */
+  private resolvePossibleStringValuesFromTemplateLiteralType (templateLiteralType: TsTemplateLiteralType): string[] {
+    // If there are no types, we can just return the cooked value
+    if (templateLiteralType.quasis.length === 1 && templateLiteralType.types.length === 0) {
+      // Ex. `translation.key.no.substitution`
+      return [templateLiteralType.quasis[0].cooked || '']
+    }
+
+    // Ex. `translation.key.with.expression.${'title' | 'description'}`
+    const [firstQuasis, ...tails] = templateLiteralType.quasis
+
+    const stringValues = templateLiteralType.types.reduce(
+      (heads, type, i) => {
+        return heads.flatMap((head) => {
+          const tail = tails[i]?.cooked ?? ''
+          return this.resolvePossibleStringValuesFromType(type, true).map(
+            (expressionValue) => `${head}${expressionValue}${tail}`
+          )
+        })
+      },
+      [firstQuasis.cooked ?? '']
+    )
+
+    return stringValues
+  }
+
   /**
    * Finds the configuration for a given useTranslation function name.
    * Applies default argument positions if none are specified.

package/src/extractor/parsers/comment-parser.ts

@@ -83,9 +83,14 @@ export function extractKeysFromComments (
 
       // 5. Handle context and count combinations
       if (context && count) {
-        // Generate all combinations: base plural + context+plural
-        generatePluralKeys(key, defaultValue ?? key, ns, pluginContext, config, isOrdinal)
+        // Generate context+plural combinations
         generateContextPluralKeys(key, defaultValue ?? key, ns, context, pluginContext, config, isOrdinal)
+
+        // Only generate base plural forms if generateBasePluralForms is not disabled
+        const shouldGenerateBaseForms = config.extract?.generateBasePluralForms !== false
+        if (shouldGenerateBaseForms) {
+          generatePluralKeys(key, defaultValue ?? key, ns, pluginContext, config, isOrdinal)
+        }
       } else if (context) {
         // Just context variants
         pluginContext.addKey({ key, ns, defaultValue: defaultValue ?? key })
@@ -114,8 +119,24 @@ function generatePluralKeys (
 ): void {
   try {
     const type = isOrdinal ? 'ordinal' : 'cardinal'
-    const primaryLanguage = config.extract.primaryLanguage || config.locales[0] || 'en'
-    const pluralCategories = new Intl.PluralRules(primaryLanguage, { type }).resolvedOptions().pluralCategories
+
+    // Generate plural forms for ALL target languages to ensure we have all necessary keys
+    const allPluralCategories = new Set<string>()
+
+    for (const locale of config.locales) {
+      try {
+        const pluralRules = new Intl.PluralRules(locale, { type })
+        const categories = pluralRules.resolvedOptions().pluralCategories
+        categories.forEach(cat => allPluralCategories.add(cat))
+      } catch (e) {
+        // If a locale is invalid, fall back to English rules
+        const englishRules = new Intl.PluralRules('en', { type })
+        const categories = englishRules.resolvedOptions().pluralCategories
+        categories.forEach(cat => allPluralCategories.add(cat))
+      }
+    }
+
+    const pluralCategories = Array.from(allPluralCategories).sort()
     const pluralSeparator = config.extract.pluralSeparator ?? '_'
 
     // Generate keys for each plural category
@@ -152,8 +173,24 @@ function generateContextPluralKeys (
 ): void {
   try {
     const type = isOrdinal ? 'ordinal' : 'cardinal'
-    const primaryLanguage = config.extract.primaryLanguage || config.locales[0] || 'en'
-    const pluralCategories = new Intl.PluralRules(primaryLanguage, { type }).resolvedOptions().pluralCategories
+
+    // Generate plural forms for ALL target languages to ensure we have all necessary keys
+    const allPluralCategories = new Set<string>()
+
+    for (const locale of config.locales) {
+      try {
+        const pluralRules = new Intl.PluralRules(locale, { type })
+        const categories = pluralRules.resolvedOptions().pluralCategories
+        categories.forEach(cat => allPluralCategories.add(cat))
+      } catch (e) {
+        // If a locale is invalid, fall back to English rules
+        const englishRules = new Intl.PluralRules(config.extract.primaryLanguage || 'en', { type })
+        const categories = englishRules.resolvedOptions().pluralCategories
+        categories.forEach(cat => allPluralCategories.add(cat))
+      }
+    }
+
+    const pluralCategories = Array.from(allPluralCategories).sort()
     const pluralSeparator = config.extract.pluralSeparator ?? '_'
 
     // Generate keys for each context + plural combination

package/src/extractor/parsers/jsx-parser.ts

@@ -152,9 +152,22 @@ export function extractFromTransComponent (node: JSXElement, config: I18nextTool
 
   const serialized = serializeJSXChildren(node.children, config)
 
-  let defaultValue = config.extract.defaultValue || ''
+  // Handle default value properly
+  let defaultValue: string
+
   if (defaultsAttr?.type === 'JSXAttribute' && defaultsAttr.value?.type === 'StringLiteral') {
+    // Explicit defaults attribute takes precedence
     defaultValue = defaultsAttr.value.value
+  } else {
+    // Use the configured default value or fall back to empty string
+    const configuredDefault = config.extract.defaultValue
+    if (typeof configuredDefault === 'string') {
+      defaultValue = configuredDefault
+    } else {
+      // For function-based defaults or undefined, use empty string as placeholder
+      // The translation manager will handle function resolution with proper context
+      defaultValue = ''
+    }
   }
 
   let keyExpression: Expression | undefined

package/src/extractor/plugin-manager.ts

@@ -49,9 +49,30 @@ export function createPluginContext (allKeys: Map<string, ExtractedKey>, plugins
     addKey: (keyInfo: ExtractedKey) => {
       // Use namespace in the unique map key to avoid collisions across namespaces
       const uniqueKey = `${keyInfo.ns ?? 'translation'}:${keyInfo.key}`
+      const defaultValue = keyInfo.defaultValue ?? keyInfo.key
 
-      if (!allKeys.has(uniqueKey)) {
-        const defaultValue = keyInfo.defaultValue ?? keyInfo.key
+      // Check if key already exists
+      const existingKey = allKeys.get(uniqueKey)
+
+      if (existingKey) {
+        // Check if existing value is a generic fallback
+        // For plural keys, the fallback is often the base key (e.g., "item.count" for "item.count_other")
+        // For regular keys, the fallback is the key itself
+        const isExistingGenericFallback =
+          existingKey.defaultValue === existingKey.key || // Regular key fallback
+          (existingKey.hasCount && existingKey.defaultValue &&
+            existingKey.key.includes('_') &&
+            existingKey.key.startsWith(existingKey.defaultValue)) // Plural key with base key fallback
+
+        const isNewGenericFallback = defaultValue === keyInfo.key
+
+        // If existing value is a generic fallback and new value is specific, replace it
+        if (isExistingGenericFallback && !isNewGenericFallback) {
+          allKeys.set(uniqueKey, { ...keyInfo, defaultValue })
+        }
+        // Otherwise keep the existing one
+      } else {
+        // New key, just add it
         allKeys.set(uniqueKey, { ...keyInfo, defaultValue })
       }
     },

package/src/syncer.ts

@@ -1,5 +1,5 @@
 import { writeFile, mkdir } from 'node:fs/promises'
-import { resolve, dirname, basename } from 'path'
+import { resolve, dirname, basename } from 'node:path'
 import chalk from 'chalk'
 import ora from 'ora'
 import { glob } from 'glob'
@@ -7,6 +7,7 @@ import type { I18nextToolkitConfig } from './types'
 import { getNestedKeys, getNestedValue, setNestedValue } from './utils/nested-object'
 import { getOutputPath, loadTranslationFile, serializeTranslationFile } from './utils/file-utils'
 import { shouldShowFunnel, recordFunnelShown } from './utils/funnel-msg-tracker'
+import { resolveDefaultValue } from './utils/default-value'
 
 /**
  * Synchronizes translation files across different locales by ensuring all secondary
@@ -84,7 +85,9 @@ export async function runSyncer (config: I18nextToolkitConfig) {
 
         for (const key of primaryKeys) {
           const existingValue = getNestedValue(existingSecondaryTranslations, key, keySeparator ?? '.')
-          const valueToSet = existingValue ?? defaultValue
+
+          // Use the resolved default value if no existing value
+          const valueToSet = existingValue ?? resolveDefaultValue(defaultValue, key, ns, lang)
           setNestedValue(newSecondaryTranslations, key, valueToSet, keySeparator ?? '.')
         }
 

package/src/types.ts

@@ -88,7 +88,7 @@ export interface I18nextToolkitConfig {
     indentation?: number | string;
 
     /** Default value to use for missing translations in secondary languages */
-    defaultValue?: string;
+    defaultValue?: string | ((key: string, namespace: string, language: string) => string);
 
     /** Primary language that provides default values (default: first locale) */
     primaryLanguage?: string;
@@ -116,6 +116,9 @@ export interface I18nextToolkitConfig {
 
     /** If true, keys that are not found in the source code will be removed from translation files. (default: true) */
     removeUnusedKeys?: boolean;
+
+    // New option to control whether base plural forms are generated when context is present
+    generateBasePluralForms?: boolean
   };
 
   /** Configuration options for TypeScript type generation */

package/src/utils/default-value.ts

@@ -0,0 +1,44 @@
+/**
+ * Resolves the default value for a missing key in secondary languages.
+ * Supports both string and function-based default values.
+ *
+ * @param defaultValue - The configured default value (string or function)
+ * @param key - The translation key
+ * @param namespace - The namespace for the key
+ * @param language - The target language
+ * @returns The resolved default value
+ *
+ * @example
+ * ```typescript
+ * // String-based default value
+ * const result1 = resolveDefaultValue('[MISSING]', 'user.name', 'common', 'de')
+ * // Returns: '[MISSING]'
+ *
+ * // Function-based default value
+ * const defaultValueFn = (key, ns, lang) => `${lang.toUpperCase()}_${ns}_${key}`
+ * const result2 = resolveDefaultValue(defaultValueFn, 'user.name', 'common', 'de')
+ * // Returns: 'DE_common_user.name'
+ *
+ * // Error handling - function throws
+ * const errorFn = () => { throw new Error('Oops') }
+ * const result3 = resolveDefaultValue(errorFn, 'user.name', 'common', 'de')
+ * // Returns: '' (fallback to empty string)
+ * ```
+ */
+export function resolveDefaultValue (
+  defaultValue: string | ((key: string, namespace: string, language: string) => string) | undefined,
+  key: string,
+  namespace: string,
+  language: string
+): string {
+  if (typeof defaultValue === 'function') {
+    try {
+      return defaultValue(key, namespace, language)
+    } catch (error) {
+      // If the function throws an error, fall back to empty string
+      return ''
+    }
+  }
+
+  return defaultValue || ''
+}

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,aAAa,CAAA;AAqJnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,GAC3B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA8E9B"}
+{"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,aAAa,CAAA;AAwMnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,GAC3B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA8E9B"}