i18next 26.1.0 → 26.3.0

package/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr *)",
+      "Read(//Users/adrai/Projects/i18next/react-i18next/**)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Read(//Users/adrai/Projects/i18next/**)",
+      "Bash(gh issue *)",
+      "Read(//tmp/**)",
+      "WebFetch(domain:github.com)",
+      "Bash(grep -n '$PreservedValue\\\\b' /Users/adrai/Projects/i18next/i18next/typescript/helpers.d.ts)",
+      "Bash(npm run *)",
+      "Bash(cat > *)",
+      "Bash(python3 -c \"import json,sys; print\\(json.load\\(sys.stdin\\)['version']\\)\")",
+      "Bash(npm test *)",
+      "Bash(git pull *)",
+      "Bash(git push *)",
+      "Bash(gh api *)",
+      "Bash(curl -s \"https://raw.githubusercontent.com/GabenGar/todos/d6d77cef716fcdc5a3991f84605176f85a69cdc8/apps/frontend/src/lib/internationalization/augs.d.ts\")"
+    ],
+    "additionalDirectories": [
+      "/Users/adrai/Projects/i18next/react-i18next",
+      "/tmp",
+      "/Users/adrai/Projects/i18next/i18next-gitbook/overview",
+      "/Users/adrai/Projects/i18next/i18next-icu"
+    ]
+  }
+}

package/README.md

@@ -23,7 +23,7 @@ i18next provides:
 - Extensibility: eg. [sprintf](https://www.i18next.com/overview/plugins-and-utils#post-processors)
 - ...
 
-> **Pro Tip:** Looking for a way to manage your translations? Locize is the official service by i18next's creators and now offers a **[Free plan](https://www.locize.com/pricing?utm_source=i18next_readme&utm_medium=github&utm_campaign=readme)** for small projects.
+> **Pro Tip:** Looking for a way to manage your translations? [Locize](https://www.locize.com?utm_source=i18next_readme&utm_medium=github&utm_campaign=readme) is the official service by i18next's creators — drop in [`i18next-locize-backend`](https://github.com/locize/i18next-locize-backend) for CDN delivery, AI translation, and no redeploys for copy changes. **[Free plan](https://www.locize.com/pricing?utm_source=i18next_readme&utm_medium=github&utm_campaign=readme)** available for small projects.
 
 For more information visit the website:
 

package/dist/esm/package.json

@@ -1 +1 @@
-{"type":"module","version":"26.1.0"}
+{"type":"module","version":"26.3.0"}

package/index.d.ts

@@ -584,6 +584,7 @@ export type {
   InitOptions,
   TypeOptions,
   CustomTypeOptions,
+  ResourceNamespaceMap,
   CustomPluginOptions,
   PluginOptions,
   FormatFunction,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next",
-  "version": "26.1.0",
+  "version": "26.3.0",
   "description": "i18next internationalization framework",
   "main": "./dist/cjs/i18next.js",
   "module": "./dist/esm/i18next.js",

package/typescript/options.d.ts

@@ -27,140 +27,246 @@ import type { $MergeBy, $PreservedValue, $Dictionary } from './helpers.js';
  */
 export interface CustomTypeOptions {}
 
+/**
+ * Per-package namespace types for monorepos. Augment this in each package's
+ * `i18next.d.ts` instead of `CustomTypeOptions.resources` when several packages
+ * need their own namespaces — otherwise TypeScript reports TS2717 on merge.
+ *
+ * Works alongside the legacy `CustomTypeOptions.resources` field; both end up
+ * in `TypeOptions['resources']`.
+ *
+ * Scalar type options like `defaultNS`, `returnNull`, `enableSelector`, etc.,
+ * still belong on `CustomTypeOptions` — this interface is for namespace
+ * resource types only.
+ *
+ * @see https://github.com/i18next/i18next/issues/2409
+ *
+ * @example
+ * ```ts
+ * // packages/ui/i18next.d.ts
+ * declare module 'i18next' {
+ *   interface ResourceNamespaceMap {
+ *     '@repo/ui': typeof uiTranslations;
+ *   }
+ * }
+ * ```
+ */
+export interface ResourceNamespaceMap {}
+
 /**
  * This interface can be augmented by users to add types to `i18next` default PluginOptions.
  */
 export interface CustomPluginOptions {}
 
-export type TypeOptions = $MergeBy<
-  {
-    /** @see {InitOptions.returnNull} */
-    returnNull: false;
-
-    /** @see {InitOptions.returnEmptyString} */
-    returnEmptyString: true;
-
-    /** @see {InitOptions.returnObjects} */
-    returnObjects: false;
-
-    /** @see {InitOptions.keySeparator} */
-    keySeparator: '.';
-
-    /** @see {InitOptions.nsSeparator} */
-    nsSeparator: ':';
-
-    /** @see {InitOptions.pluralSeparator} */
-    pluralSeparator: '_';
+type _LegacyResources = CustomTypeOptions extends { resources: infer R } ? R : object;
+
+// Per-property merge of two object types. Unlike `L & R`, which TypeScript
+// collapses to `never` whenever ANY property has incompatible literals (so a
+// single same-key/different-literal conflict wipes out the whole namespace),
+// this iterates keys and intersects them individually — the conflicting key
+// becomes `never`, the rest survive.
+type _PerPropMerge<L, R> = {
+  [K in keyof L | keyof R]: K extends keyof L
+    ? K extends keyof R
+      ? L[K] & R[K]
+      : L[K]
+    : K extends keyof R
+      ? R[K]
+      : never;
+};
+
+// Drop properties whose value resolved to `never`. Without this, the
+// conflict key would leak into `keyof Resources[ns]`, then poison
+// `KeysBuilder` recursion (it tries to walk a `never` value) and break
+// `t()` overload resolution for the entire namespace.
+// NOTE: must use the `Pick<T, NonNeverKeys>` form. A `[K in keyof T as ...]`
+// remap does NOT eagerly evaluate `T[K]` for intersection types, so conflict
+// keys would survive the filter.
+type _NonNeverKeys<T> = {
+  [K in keyof T]: [T[K]] extends [never] ? never : K;
+}[keyof T];
+type _DropConflictKeys<T> = Pick<T, _NonNeverKeys<T>>;
+
+// When the same namespace exists on both sides, deep-merge per property and
+// strip same-key/different-literal conflicts. Otherwise pick from whichever
+// side has it.
+type _MergeNamespaces<L, R> = {
+  [K in keyof L | keyof R]: K extends keyof L
+    ? K extends keyof R
+      ? _DropConflictKeys<_PerPropMerge<L[K], R[K]>>
+      : L[K]
+    : K extends keyof R
+      ? R[K]
+      : never;
+};
+
+// NOTE: empty legacy + empty registry must stay `object` so unconfigured projects
+// still get `$IsResourcesDefined === false`.
+type _MergedResources = [keyof _LegacyResources] extends [never]
+  ? [keyof ResourceNamespaceMap] extends [never]
+    ? object
+    : ResourceNamespaceMap
+  : [keyof ResourceNamespaceMap] extends [never]
+    ? _LegacyResources
+    : _MergeNamespaces<_LegacyResources, ResourceNamespaceMap>;
 
-    /** @see {InitOptions.contextSeparator} */
-    contextSeparator: '_';
-
-    /** @see {InitOptions.defaultNS} */
-    defaultNS: 'translation';
-
-    /** @see {InitOptions.fallbackNS} */
-    fallbackNS: false;
-
-    /** @see {InitOptions.compatibilityJSON} */
-    compatibilityJSON: 'v4';
-
-    /** @see {InitOptions.resources} */
-    resources: object;
-
-    /**
-     * Flag that allows HTML elements to receive objects. This is only useful for React applications
-     * where you pass objects to HTML elements so they can be replaced to their respective interpolation
-     * values (mostly with Trans component)
-     */
-    allowObjectInHTMLChildren: false;
-
-    /**
-     * Flag that enables strict key checking even if a `defaultValue` has been provided.
-     * This ensures all calls of `t` function don't accidentally use implicitly missing keys.
-     */
-    strictKeyChecks: false;
-
-    /**
-     * Prefix for interpolation
-     */
-    interpolationPrefix: '{{';
-
-    /**
-     * Suffix for interpolation
-     */
-    interpolationSuffix: '}}';
-
-    /** @see {InterpolationOptions.unescapePrefix} */
-    unescapePrefix: '-';
-
-    /** @see {InterpolationOptions.unescapeSuffix} */
-    unescapeSuffix: '';
-
-    /**
-     * Use a proxy-based selector to select a translation.
-     *
-     * Enables features like go-to definition, and better DX/faster autocompletion
-     * for TypeScript developers.
-     *
-     * If you're working with an especially large set of translations and aren't
-     * using context, you set `enableSelector` to `"optimize"` and i18next won't do
-     * any type-level processing of your translations at all.
-     *
-     * With `enableSelector` set to `"optimize"`, i18next is capable of supporting
-     * arbitrarily large/deep translation sets without causing any IDE slowdown
-     * whatsoever.
-     *
-     * Set `enableSelector` to `"strict"` to require an explicit namespace as the
-     * first selector path segment in every call. The selector proxy stops
-     * exposing the primary namespace's keys flat on `$` — even
-     * `useTranslation('only')` must use `$.only.foo`, never `$.foo`. At runtime,
-     * a leading segment matching the scope's namespace list (primary included)
-     * is always rewritten as a namespace prefix, fully decoupling selector
-     * shape from resolution scope. Use this when you want a single mental model
-     * for selector paths regardless of how many namespaces a hook was created
-     * with, and to remove the silent miss that flat-primary paths can otherwise
-     * cause in multi-ns hooks (see [#2429](https://github.com/i18next/i18next/issues/2429)).
-     *
-     * `"strict"` mode is incompatible with the `"optimize"` shortcut. If you
-     * have keys whose names match sibling namespaces (the
-     * [#2405](https://github.com/i18next/i18next/issues/2405) pattern), do not
-     * enable strict mode — the leading-segment rewrite would route those keys
-     * into the wrong namespace.
-     *
-     * @default false
-     */
-    enableSelector: false;
-
-    /**
-     * Maps interpolation format specifiers to their expected value types.
-     *
-     * By default, i18next infers types from built-in formatter names:
-     * - `number`, `currency` → `number`
-     * - `datetime` → `Date`
-     * - `relativetime` → `number`
-     * - `list` → `readonly string[]`
-     * - No format specifier → `string | number` (since i18next stringifies values at runtime)
-     *
-     * Use this option to add mappings for custom formatters or to override
-     * the built-in defaults.
-     *
-     * @default {} (empty — built-in defaults apply)
-     *
-     * @example
-     * ```ts
-     * interface CustomTypeOptions {
-     *   interpolationFormatTypeMap: {
-     *     // custom formatter
-     *     uppercase: string;
-     *     // override built-in
-     *     currency: string;
-     *   };
-     * }
-     * ```
-     */
-    interpolationFormatTypeMap: {};
-  },
-  CustomTypeOptions
+export type TypeOptions = $MergeBy<
+  $MergeBy<
+    {
+      /** @see {InitOptions.returnNull} */
+      returnNull: false;
+
+      /** @see {InitOptions.returnEmptyString} */
+      returnEmptyString: true;
+
+      /** @see {InitOptions.returnObjects} */
+      returnObjects: false;
+
+      /** @see {InitOptions.keySeparator} */
+      keySeparator: '.';
+
+      /** @see {InitOptions.nsSeparator} */
+      nsSeparator: ':';
+
+      /** @see {InitOptions.pluralSeparator} */
+      pluralSeparator: '_';
+
+      /** @see {InitOptions.contextSeparator} */
+      contextSeparator: '_';
+
+      /** @see {InitOptions.defaultNS} */
+      defaultNS: 'translation';
+
+      /** @see {InitOptions.fallbackNS} */
+      fallbackNS: false;
+
+      /** @see {InitOptions.compatibilityJSON} */
+      compatibilityJSON: 'v4';
+
+      /** @see {InitOptions.resources} */
+      resources: object;
+
+      /**
+       * Flag that allows HTML elements to receive objects. This is only useful for React applications
+       * where you pass objects to HTML elements so they can be replaced to their respective interpolation
+       * values (mostly with Trans component)
+       */
+      allowObjectInHTMLChildren: false;
+
+      /**
+       * Flag that enables strict key checking even if a `defaultValue` has been provided.
+       * This ensures all calls of `t` function don't accidentally use implicitly missing keys.
+       */
+      strictKeyChecks: false;
+
+      /**
+       * Prefix for interpolation
+       */
+      interpolationPrefix: '{{';
+
+      /**
+       * Suffix for interpolation
+       */
+      interpolationSuffix: '}}';
+
+      /** @see {InterpolationOptions.unescapePrefix} */
+      unescapePrefix: '-';
+
+      /** @see {InterpolationOptions.unescapeSuffix} */
+      unescapeSuffix: '';
+
+      /**
+       * Whether to extract interpolation variables from translation strings at
+       * the type level. When `true` (default), the type system parses each
+       * resource value for `{{variable}}` patterns and types the `t()` options
+       * accordingly.
+       *
+       * Set to `false` when your translation strings use a different
+       * interpolation syntax that the i18next type extractor cannot understand
+       * — e.g. ICU MessageFormat plurals like `{count, plural, one {{count} row}
+       * other {{count} rows}}` would otherwise produce phantom variable names
+       * because the default extractor naively matches the outermost `{{` …
+       * `}}`. This flag is type-only; runtime interpolation is governed by
+       * `InterpolationOptions` and is unaffected.
+       *
+       * Required by `i18next-icu` users — see that package's docs for the
+       * recommended `CustomTypeOptions` augmentation.
+       *
+       * @default true
+       */
+      parseInterpolation: true;
+
+      /**
+       * Use a proxy-based selector to select a translation.
+       *
+       * Enables features like go-to definition, and better DX/faster autocompletion
+       * for TypeScript developers.
+       *
+       * If you're working with an especially large set of translations and aren't
+       * using context, you set `enableSelector` to `"optimize"` and i18next won't do
+       * any type-level processing of your translations at all.
+       *
+       * With `enableSelector` set to `"optimize"`, i18next is capable of supporting
+       * arbitrarily large/deep translation sets without causing any IDE slowdown
+       * whatsoever.
+       *
+       * Set `enableSelector` to `"strict"` to require an explicit namespace as the
+       * first selector path segment in every call. The selector proxy stops
+       * exposing the primary namespace's keys flat on `$` — even
+       * `useTranslation('only')` must use `$.only.foo`, never `$.foo`. At runtime,
+       * a leading segment matching the scope's namespace list (primary included)
+       * is always rewritten as a namespace prefix, fully decoupling selector
+       * shape from resolution scope. Use this when you want a single mental model
+       * for selector paths regardless of how many namespaces a hook was created
+       * with, and to remove the silent miss that flat-primary paths can otherwise
+       * cause in multi-ns hooks (see [#2429](https://github.com/i18next/i18next/issues/2429)).
+       *
+       * `"strict"` mode is incompatible with the `"optimize"` shortcut. If you
+       * have keys whose names match sibling namespaces (the
+       * [#2405](https://github.com/i18next/i18next/issues/2405) pattern), do not
+       * enable strict mode — the leading-segment rewrite would route those keys
+       * into the wrong namespace.
+       *
+       * @default false
+       */
+      enableSelector: false;
+
+      /**
+       * Maps interpolation format specifiers to their expected value types.
+       *
+       * By default, i18next infers types from built-in formatter names:
+       * - `number`, `currency` → `number`
+       * - `datetime` → `Date`
+       * - `relativetime` → `number`
+       * - `list` → `readonly string[]`
+       * - No format specifier → `string | number` (since i18next stringifies values at runtime)
+       *
+       * Use this option to add mappings for custom formatters or to override
+       * the built-in defaults.
+       *
+       * @default {} (empty — built-in defaults apply)
+       *
+       * @example
+       * ```ts
+       * interface CustomTypeOptions {
+       *   interpolationFormatTypeMap: {
+       *     // custom formatter
+       *     uppercase: string;
+       *     // override built-in
+       *     currency: string;
+       *   };
+       * }
+       * ```
+       */
+      interpolationFormatTypeMap: {};
+    },
+    CustomTypeOptions
+  >,
+  // HACK: apply merged resources *after* CustomTypeOptions so registry contributions
+  // survive when CustomTypeOptions.resources is also defined. Without this
+  // second step, the inner $MergeBy would replace the default `resources: object`
+  // with CustomTypeOptions['resources'] alone, dropping the registry namespaces.
+  { resources: _MergedResources }
 >;
 
 export type PluginOptions<T> = $MergeBy<
@@ -641,6 +747,19 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
    */
   nsSeparator?: false | string;
 
+  /**
+   * Selector-API mode. Mirrors `CustomTypeOptions['enableSelector']`.
+   *
+   * - `false` (default): selector API disabled.
+   * - `true` / `'optimize'`: selector resolution enabled.
+   * - `'strict'`: require an explicit namespace as the first selector
+   *   path segment in every call. The resolver always rewrites a leading
+   *   namespace-matching segment as a namespace prefix.
+   *
+   * @default false
+   */
+  enableSelector?: false | true | 'optimize' | 'strict';
+
   /**
    * Char to split plural from key
    * @default '_'

package/typescript/t.d.ts

@@ -36,6 +36,7 @@ type _UnescapePrefix = TypeOptions['unescapePrefix'];
 type _UnescapeSuffix = TypeOptions['unescapeSuffix'];
 type _StrictKeyChecks = TypeOptions['strictKeyChecks'];
 type _EnableSelector = TypeOptions['enableSelector'];
+type _ParseInterpolation = TypeOptions['parseInterpolation'];
 type _InterpolationFormatTypeMap = TypeOptions['interpolationFormatTypeMap'];
 
 type $IsResourcesDefined = [keyof _Resources] extends [never] ? false : true;
@@ -76,19 +77,23 @@ interface Branded<Ns extends Namespace> {
 /** ****************************************************
  * Build all keys and key prefixes based on Resources *
  ***************************************************** */
-type KeysBuilderWithReturnObjects<Res, Key = keyof Res> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary | readonly unknown[]
-    ?
-        | JoinKeys<Key, WithOrWithoutPlural<keyof $OmitArrayKeys<Res[Key]>>>
-        | JoinKeys<Key, KeysBuilderWithReturnObjects<Res[Key]>>
-    : never
-  : never;
+type KeysBuilderWithReturnObjects<Res, Key = keyof Res> = [Res] extends [never]
+  ? never
+  : Key extends keyof Res
+    ? Res[Key] extends $Dictionary | readonly unknown[]
+      ?
+          | JoinKeys<Key, WithOrWithoutPlural<keyof $OmitArrayKeys<Res[Key]>>>
+          | JoinKeys<Key, KeysBuilderWithReturnObjects<Res[Key]>>
+      : never
+    : never;
 
-type KeysBuilderWithoutReturnObjects<Res, Key = keyof $OmitArrayKeys<Res>> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary | readonly unknown[]
-    ? JoinKeys<Key, KeysBuilderWithoutReturnObjects<Res[Key]>>
-    : Key
-  : never;
+type KeysBuilderWithoutReturnObjects<Res, Key = keyof $OmitArrayKeys<Res>> = [Res] extends [never]
+  ? never
+  : Key extends keyof Res
+    ? Res[Key] extends $Dictionary | readonly unknown[]
+      ? JoinKeys<Key, KeysBuilderWithoutReturnObjects<Res[Key]>>
+      : Key
+    : never;
 
 type KeysBuilder<Res, WithReturnObjects> = $IsResourcesDefined extends true
   ? WithReturnObjects extends true
@@ -168,8 +173,9 @@ type ParseActualValue<Ret> = Ret extends `${_UnescapePrefix}${infer ActualValue}
   : Ret;
 
 /** Parses interpolation entries as `[variableName, formatSpecifier | never]` tuples. */
-type ParseInterpolationEntries<Ret> =
-  Ret extends `${string}${_InterpolationPrefix}${infer Value}${_InterpolationSuffix}${infer Rest}`
+type ParseInterpolationEntries<Ret> = [_ParseInterpolation] extends [false]
+  ? never
+  : Ret extends `${string}${_InterpolationPrefix}${infer Value}${_InterpolationSuffix}${infer Rest}`
     ?
         | (Value extends `${infer ActualValue},${infer Format}`
             ? [ParseActualValue<ActualValue>, TrimSpaces<Format>]