fix(core): chain custom plural null to defaultPlural

Document that Nuxt plural must be a self-contained function;
file-path plural is not supported (#241).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: s00d

docs/api/module-options.md

@@ -60,7 +60,7 @@ Where translation files live and how keys are resolved.
 | `translationDir` | `string` | `'locales'` | Path to the directory containing translation JSON files, relative to the project root. |
 | `disableWatcher` | `boolean` | `false` | Disable the file watcher that auto-creates missing translation files in development mode. |
 | `routesLocaleLinks` | `{ [key: string]: string }` | `{}` | Map route names to other route names to share the same translation files. For example, `{ 'about-us': 'about' }` means the `about-us` page will use translations from the `about` page instead of its own. |
-| `plural` | `string \| PluralFunc` | `built-in pluralization (singular/plural by count)` | Custom pluralization function or a path to a file exporting one. When a string path is provided, the file is imported at build time. The function receives `(key, count, params, locale, getter)` and should return the correct plural form as a string, or `null` to fall back to the built-in logic. |
+| `plural` | `PluralFunc` | `built-in pluralization (form index by count)` | Custom pluralization function. Receives `(key, count, params, locale, getter)` and should return the selected plural form as a string, or `null`/`undefined` to fall back to the built-in `defaultPlural` logic (so you can override only some locales). For the Nuxt module the function is serialized with `.toString()` into `.nuxt/i18n.plural.mjs` — it must be self-contained (no imports / outer scope). A file path string is **not** supported. |
 | `disablePageLocales` | `boolean` | `false` | Disable per-page translation files. When `true`, only global translations (`{locale}.json`) are loaded; page-specific files (`pages/{page}/{locale}.json`) are not generated or loaded. |
 | `fallbackLocale` | `string` | `undefined (no fallback; returns the raw key)` | Global fallback locale code. When a translation key is missing in the active locale, the module looks it up in this locale before returning the key itself. |
 

docs/guide/configuration.md

@@ -50,7 +50,7 @@ The sections below explain how they work together; the
 | [`disableWatcher`](/api/module-options) | `boolean` | `false` | Disable the file watcher that auto-creates missing translation files in development mode. |
 | [`types`](/api/module-options) | `boolean` | `true` | Generate TypeScript type declarations for `useI18n`, `$t`, and related helpers based on the translation keys in your default locale files. |
 | [`routesLocaleLinks`](/api/module-options) | `{ [key: string]: string }` | `{}` | Map route names to other route names to share the same translation files. |
-| [`plural`](/api/module-options) | `string \| PluralFunc` | `built-in pluralization (singular/plural by count)` | Custom pluralization function or a path to a file exporting one. |
+| [`plural`](/api/module-options) | `PluralFunc` | `built-in pluralization (form index by count)` | Custom pluralization function. |
 | [`disablePageLocales`](/api/module-options) | `boolean` | `false` | Disable per-page translation files. |
 | [`fallbackLocale`](/api/module-options) | `string` | `undefined (no fallback; returns the raw key)` | Global fallback locale code. |
 | [`localeCookie`](/api/module-options) | `string \| null` | `null` | Cookie name for persisting the user's locale preference across sessions. |
@@ -640,12 +640,16 @@ autoDetectPath: '*' // On all routes (use with caution)
 
 <!-- generated:option:plural — do not edit; run `pnpm run docs:generate` -->
 
-**Type** `string \| PluralFunc` · **Default** `built-in pluralization (singular/plural by count)`
+**Type** `PluralFunc` · **Default** `built-in pluralization (form index by count)`
 
-Custom pluralization function or a path to a file exporting one.
-When a string path is provided, the file is imported at build time.
-The function receives `(key, count, params, locale, getter)` and should return
-the correct plural form as a string, or `null` to fall back to the built-in logic.
+Custom pluralization function.
+Receives `(key, count, params, locale, getter)` and should return the selected
+plural form as a string, or `null`/`undefined` to fall back to the built-in
+`defaultPlural` logic (so you can override only some locales).
+
+For the Nuxt module the function is serialized with `.toString()` into
+`.nuxt/i18n.plural.mjs` — it must be self-contained (no imports / outer scope).
+A file path string is **not** supported.
 
 <!-- /generated:option:plural -->
 
@@ -678,8 +682,9 @@ For languages with complex pluralization rules (e.g., Russian, Arabic, Polish),
 The function is serialized via `.toString()` and injected into a virtual module at build time. This means:
 
 - **Must use `function` keyword** — NOT shorthand method syntax, NOT arrow functions with external references
-- **No imports or external references** — the function must be fully self-contained
+- **No imports or external references** — the function must be fully self-contained (a file path like `plural: '~/i18n/plural.ts'` is **not** supported)
 - **No TypeScript-only syntax** that doesn't survive `.toString()` (type annotations are fine in `nuxt.config.ts` because Nuxt strips them)
+- Returning `null` / `undefined` falls back to the built-in `defaultPlural` (useful for per-locale overrides)
   :::
 
 **Example: Russian pluralization** (4 forms: zero, one, few, many):
@@ -755,36 +760,39 @@ plural: function (key, count, params, _locale, t) {
 
 ##### Per-locale pluralization
 
-If different locales need different plural rules, use the `locale` parameter:
+If different locales need different plural rules, branch on `locale` and return `null`
+for locales you do not customize — the built-in `defaultPlural` handles the rest:
 
 ```typescript
 plural: function (key, count, _params, locale, t) {
+  // Only override Slavic locales; en/de/… keep the built-in rules
+  if (locale !== 'ru' && locale !== 'uk') return null
+
   const translation = t(key)
-  if (!translation) return key
+  if (!translation) return null
 
   const forms = translation.toString().split('|').map(function (s) { return s.trim() })
-
-  // Russian/Ukrainian plural rules
-  if (locale === 'ru' || locale === 'uk') {
-    let idx
-    if (count === 0) {
-      idx = 0
-    } else {
-      const mod10 = count % 10
-      const mod100 = count % 100
-      if (mod10 === 1 && mod100 !== 11) idx = 1
-      else if (mod10 >= 2 && mod10 <= 4 && (mod100 < 10 || mod100 >= 20)) idx = 2
-      else idx = 3
-    }
-    if (idx >= forms.length) idx = forms.length - 1
-    return (forms[idx] || '').replace('{count}', String(count))
+  let idx
+  if (count === 0) {
+    idx = 0
+  } else {
+    const mod10 = count % 10
+    const mod100 = count % 100
+    if (mod10 === 1 && mod100 !== 11) idx = 1
+    else if (mod10 >= 2 && mod10 <= 4 && (mod100 < 10 || mod100 >= 20)) idx = 2
+    else idx = 3
   }
-
-  // Default: English-like (index-based)
-  const idx = count < forms.length ? count : forms.length - 1
+  if (idx >= forms.length) idx = forms.length - 1
   return (forms[idx] || '').replace('{count}', String(count))
 }
 ```
+
+::: warning No module-path `plural`
+`plural: '~/i18n/plural.ts'` (or any string path) is **not** supported. The Nuxt module
+serializes the function with `.toString()` into a virtual file; external imports and
+helpers from another module are stripped and will be `undefined` at runtime. Keep the
+function fully inlined in `nuxt.config.ts` (see the danger note above).
+:::
 #### `localeCookie`
 
 <!-- generated:option:localeCookie — do not edit; run `pnpm run docs:generate` -->

docs/news/index.md

@@ -6,6 +6,12 @@ outline: 'deep'
 
 # News
 
+## Unreleased — custom `plural` falls back to default (#241)
+
+**Date**: 2026-07-31
+
+A custom `plural` that returns `null`/`undefined` now chains to the built-in `defaultPlural`, so you can override only some locales (e.g. Slavic) without reimplementing English-style rules. File-path `plural: '~/…'` is **not** supported — the function must stay self-contained in `nuxt.config` (serialized via `.toString()`).
+
 ## Unreleased — hreflang from `iso`, not routing `code` (#243)
 
 **Date**: 2026-07-31

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i18n-micro/core",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "description": "Core utilities for translations, formatting, and locale routing in Nuxt I18n Micro.",
   "keywords": [
     "formatting",

packages/core/src/base.ts

@@ -43,7 +43,15 @@ export abstract class BaseI18n {
       datetimeFormats: options.datetimeFormats,
     }
     this.formatter = new FormatService(formatOptions)
-    this.pluralFunc = options.plural || defaultPlural
+    // Custom plural returning null/undefined chains to defaultPlural (#241).
+    // Skip the wrapper when the caller already passed the built-in (module default).
+    this.pluralFunc =
+      options.plural && options.plural !== defaultPlural
+        ? (key, count, params, locale, getter) => {
+            const custom = options.plural!(key, count, params, locale, getter)
+            return custom ?? defaultPlural(key, count, params, locale, getter)
+          }
+        : defaultPlural
     this.missingWarn = options.missingWarn ?? true
     this.missingHandler = options.missingHandler
     this.getCustomMissingHandler = options.getCustomMissingHandler

packages/core/tests/base.test.ts

@@ -221,6 +221,36 @@ describe('BaseI18n', () => {
       // This happens when translation exists but is empty or invalid.
       expect(i18n.tc('missing.key', 1, 'Default')).toBe('missing.key')
     })
+
+    test('#241: custom plural null should fall back to defaultPlural', () => {
+      // Override only for ru; return null elsewhere — should use built-in form selection for en
+      const customPlural: PluralFunc = (key, count, params, locale, getter) => {
+        if (locale !== 'ru') return null
+        const translation = getter(key, params)
+        if (typeof translation !== 'string') return null
+        return `ru:${translation.split('|')[0]}`
+      }
+
+      const i18n = new TestI18n('en', 'en', 'index', { plural: customPlural })
+      // key ≠ forms, so falling back to `key` cannot accidentally pass
+      // defaultPlural indexes by count: 0→form0, 1→form1, 2+→last
+      i18n['helper'].loadTranslations('en', { items: 'none|one|many' })
+
+      expect(i18n.tc('items', 0)).toBe('none')
+      expect(i18n.tc('items', 1)).toBe('one')
+      expect(i18n.tc('items', 5)).toBe('many')
+
+      i18n.setLocale('ru')
+      i18n['helper'].loadTranslations('ru', { items: 'нет|один|мало|много' })
+      expect(i18n.tc('items', 1)).toBe('ru:нет')
+    })
+
+    test('#241: custom plural can still return an explicit string (no accidental default)', () => {
+      const customPlural: PluralFunc = () => 'forced'
+      const i18n = new TestI18n('en', 'en', 'index', { plural: customPlural })
+      i18n['helper'].loadTranslations('en', { items: 'none|one|many' })
+      expect(i18n.tc('items', 1)).toBe('forced')
+    })
   })
 
   describe('tn() method', () => {

packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i18n-micro/types",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "TypeScript definitions for the Nuxt I18n Micro ecosystem.",
   "keywords": [
     "i18n",

packages/types/src/index.ts

@@ -337,13 +337,17 @@ export interface ModuleOptions {
   routesLocaleLinks?: { [key: string]: string }
 
   /**
-   * Custom pluralization function or a path to a file exporting one.
-   * When a string path is provided, the file is imported at build time.
-   * The function receives `(key, count, params, locale, getter)` and should return
-   * the correct plural form as a string, or `null` to fall back to the built-in logic.
-   * @default built-in pluralization (singular/plural by count)
+   * Custom pluralization function.
+   * Receives `(key, count, params, locale, getter)` and should return the selected
+   * plural form as a string, or `null`/`undefined` to fall back to the built-in
+   * `defaultPlural` logic (so you can override only some locales).
+   *
+   * For the Nuxt module the function is serialized with `.toString()` into
+   * `.nuxt/i18n.plural.mjs` — it must be self-contained (no imports / outer scope).
+   * A file path string is **not** supported.
+   * @default built-in pluralization (form index by count)
    */
-  plural?: string | PluralFunc
+  plural?: PluralFunc
 
   /**
    * Disable per-page translation files.

scripts/api-surface/i18n-micro__preact.api.txt

@@ -1342,7 +1342,7 @@ member ModuleOptions.missingWarn?: boolean | undefined
 member ModuleOptions.noPrefixRedirect?: boolean | undefined
 member ModuleOptions.numberFormats?: Record<string, Record<string, Intl.NumberFormatOptions>> | undefined
 member ModuleOptions.plugin?: boolean | undefined
-member ModuleOptions.plural?: string | PluralFunc | undefined
+member ModuleOptions.plural?: PluralFunc | undefined
 member ModuleOptions.redirects?: boolean | undefined
 member ModuleOptions.routeDisableMeta?: Record<string, boolean | string[]> | undefined
 member ModuleOptions.routeLocales?: Record<string, string[]> | undefined

scripts/api-surface/i18n-micro__solid.api.txt

@@ -97,7 +97,7 @@ member ModuleOptions.missingWarn?: boolean | undefined
 member ModuleOptions.noPrefixRedirect?: boolean | undefined
 member ModuleOptions.numberFormats?: Record<string, Record<string, Intl.NumberFormatOptions>> | undefined
 member ModuleOptions.plugin?: boolean | undefined
-member ModuleOptions.plural?: string | PluralFunc | undefined
+member ModuleOptions.plural?: PluralFunc | undefined
 member ModuleOptions.redirects?: boolean | undefined
 member ModuleOptions.routeDisableMeta?: Record<string, boolean | string[]> | undefined
 member ModuleOptions.routeLocales?: Record<string, string[]> | undefined