i18next 26.5.12 → 26.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/typescript/t.d.ts CHANGED
@@ -23,7 +23,8 @@ type _ReturnObjects = TypeOptions['returnObjects'];
23
23
  type _ReturnEmptyString = TypeOptions['returnEmptyString'];
24
24
  type _ReturnNull = TypeOptions['returnNull'];
25
25
  type _KeySeparator = TypeOptions['keySeparator'];
26
- type _NsSeparator = TypeOptions['nsSeparator'];
26
+ // `nsSeparator: false`: no `ns:key` keys (a `false` here made `nsfalsekey` keys and split keys containing "false")
27
+ type _NsSeparator = Exclude<TypeOptions['nsSeparator'], false>;
27
28
  type _PluralSeparator = TypeOptions['pluralSeparator'];
28
29
  type _ContextSeparator = TypeOptions['contextSeparator'];
29
30
  type _FallbackNamespace = TypeOptions['fallbackNS'];
@@ -31,9 +32,12 @@ type _Resources = TypeOptions['resources'];
31
32
  type _CompatibilityJSON = TypeOptions['compatibilityJSON'];
32
33
  type _InterpolationPrefix = TypeOptions['interpolationPrefix'];
33
34
  type _InterpolationSuffix = TypeOptions['interpolationSuffix'];
35
+ type _InterpolationFormatSeparator = TypeOptions['interpolationFormatSeparator'];
36
+ type _DefaultVariables = TypeOptions['defaultVariables'];
34
37
  type _UnescapePrefix = TypeOptions['unescapePrefix'];
35
38
  type _UnescapeSuffix = TypeOptions['unescapeSuffix'];
36
39
  type _StrictKeyChecks = TypeOptions['strictKeyChecks'];
40
+ type _StrictInterpolationChecks = TypeOptions['strictInterpolationChecks'];
37
41
  type _EnableSelector = TypeOptions['enableSelector'];
38
42
  type _ParseInterpolation = TypeOptions['parseInterpolation'];
39
43
  type _InterpolationFormatTypeMap = TypeOptions['interpolationFormatTypeMap'];
@@ -196,7 +200,7 @@ type ParseActualValue<Ret> = Ret extends `${_UnescapePrefix}${infer ActualValue}
196
200
  type ParseInterpolationEntries<Ret> = [_ParseInterpolation] extends [false | 'icu' | 'mf2']
197
201
  ? never
198
202
  : Ret extends `${string}${_InterpolationPrefix}${infer Value}${_InterpolationSuffix}${infer Rest}`
199
- ? | (Value extends `${infer ActualValue},${infer Format}`
203
+ ? | (Value extends `${infer ActualValue}${_InterpolationFormatSeparator}${infer Format}`
200
204
  ? [ParseActualValue<ActualValue>, TrimSpaces<Format>]
201
205
  : [ParseActualValue<Value>, never])
202
206
  | ParseInterpolationEntries<Rest>
@@ -432,14 +436,21 @@ type _Mf2ArgsMap<Ret> = Ret extends string
432
436
  : never
433
437
  : never;
434
438
 
435
- export type InterpolationMap<Ret> = [_ParseInterpolation] extends ['icu']
436
- ? $PreservedValue<_IcuArgsMap<Ret>, Record<string, unknown>>
437
- : [_ParseInterpolation] extends ['mf2']
438
- ? $PreservedValue<_Mf2ArgsMap<Ret>, Record<string, unknown>>
439
- : $PreservedValue<
440
- _InterpolationMapFromEntries<ParseInterpolationEntries<Ret>>,
441
- Record<string, unknown>
442
- >;
439
+ /** The variables declared in `defaultVariables` are optional: they are filled in at runtime. */
440
+ type _WithDefaultVariables<Map> = [keyof _DefaultVariables] extends [never]
441
+ ? Map
442
+ : Omit<Map, keyof _DefaultVariables> & Partial<Pick<Map, keyof _DefaultVariables & keyof Map>>;
443
+
444
+ export type InterpolationMap<Ret> = _WithDefaultVariables<
445
+ [_ParseInterpolation] extends ['icu']
446
+ ? $PreservedValue<_IcuArgsMap<Ret>, Record<string, unknown>>
447
+ : [_ParseInterpolation] extends ['mf2']
448
+ ? $PreservedValue<_Mf2ArgsMap<Ret>, Record<string, unknown>>
449
+ : $PreservedValue<
450
+ _InterpolationMapFromEntries<ParseInterpolationEntries<Ret>>,
451
+ Record<string, unknown>
452
+ >
453
+ >;
443
454
 
444
455
  type ParseTReturnPlural<
445
456
  Res,
@@ -606,18 +617,37 @@ type EffectiveKPrefix<KPrefix, TOpt> = TOpt extends { keyPrefix: infer OptKP ext
606
617
 
607
618
  /** `parseInterpolation: 'icu'` or `'mf2'`: messages are typed by their arguments. */
608
619
  type _ParsesMessageFormat = [_ParseInterpolation] extends ['icu'] | ['mf2'] ? true : false;
620
+ /**
621
+ * Whether `t()` options are required for a message with variables: always under
622
+ * ICU / MF2 (on a missing one, i18next-icu renders the raw message and
623
+ * i18next-mf2 a `{$name}` fallback), and with `strictInterpolationChecks: true`
624
+ * for `{{variables}}` (i18next renders the raw placeholder).
625
+ */
626
+ type _RequiresMessageOptions = _ParsesMessageFormat extends true
627
+ ? true
628
+ : [_ParseInterpolation] extends [true]
629
+ ? _StrictInterpolationChecks extends true
630
+ ? true
631
+ : false
632
+ : false;
609
633
 
610
634
  /**
611
- * `t()` options are optional, except for a message with arguments under
612
- * `parseInterpolation: 'icu'` or `'mf2'` (on a missing one, i18next-icu renders
613
- * the raw message and i18next-mf2 a `{$name}` fallback). The conditional
614
- * resolves eagerly; a generic one here would break inference.
635
+ * `t()` options are optional, except for a message with variables when
636
+ * `_RequiresMessageOptions` is true. The conditional resolves eagerly; a generic
637
+ * one here would break inference.
615
638
  */
616
- type _KeyAndOptions<Key, Ret, Opts> = _ParsesMessageFormat extends true
639
+ type _KeyAndOptions<Key, Ret, Opts> = _RequiresMessageOptions extends true
617
640
  ? [key: Key | Key[], options: Opts] | [key: (Key | Key[]) & _IfOptionalOptions<Ret>]
618
641
  : [key: Key | Key[], options?: Opts];
642
+ /**
643
+ * `t(key, defaultValue)` under `strictKeyChecks`: the variables are required only
644
+ * with `strictInterpolationChecks`, else `unknown` (the call stays as before).
645
+ */
646
+ type _IfOptionalDefaultOptions<Ret> = _StrictInterpolationChecks extends true
647
+ ? _IfOptionalOptions<Ret>
648
+ : unknown;
619
649
  /** `unknown` when options may be left out, else a type naming the missing arguments. */
620
- type _IfOptionalOptions<Ret> = _ParsesMessageFormat extends true
650
+ type _IfOptionalOptions<Ret> = _RequiresMessageOptions extends true
621
651
  ? {} extends InterpolationMap<Ret>
622
652
  ? unknown
623
653
  : { 'pass these arguments as t() options': InterpolationMap<Ret> }
@@ -625,6 +655,25 @@ type _IfOptionalOptions<Ret> = _ParsesMessageFormat extends true
625
655
  /** Options parameter of a selector overload: required for a message with arguments. */
626
656
  type _SelectorOptionsArg<Ret, Opts> =
627
657
  unknown extends _IfOptionalOptions<Ret> ? [options?: Opts] : [options: Opts];
658
+ /** Union of the values an array of selectors resolves to (plural brands kept). */
659
+ type _SelectorsReturn<Fns extends readonly unknown[]> = Fns[number] extends (
660
+ ...args: any[]
661
+ ) => infer R
662
+ ? R
663
+ : never;
664
+ /** Whether any member of the union is a plural group (`false` for `any`). */
665
+ type _HasPlural<R> = 0 extends 1 & R
666
+ ? false
667
+ : [Extract<R, PluralValue<string>>] extends [never]
668
+ ? false
669
+ : true;
670
+ /** `{ count: number }` when any member of the union is a plural group. */
671
+ type _CountIfPlural<R> = _HasPlural<R> extends true ? { count: number } : {};
672
+ /** Options of a selector-array overload: required for variables or a plural member. */
673
+ type _SelectorArrayOptionsArg<R, Opts> =
674
+ _HasPlural<R> extends true
675
+ ? [options: Opts & { count: number } & InterpolationMap<DeepUnwrapPlural<R>>]
676
+ : _SelectorOptionsArg<DeepUnwrapPlural<R>, Opts & InterpolationMap<DeepUnwrapPlural<R>>>;
628
677
 
629
678
  /** ************************
630
679
  * T function declaration *
@@ -663,7 +712,7 @@ interface TFunctionStrict<
663
712
  >(
664
713
  key: Key | Key[],
665
714
  defaultValue: string,
666
- options?: TOpt &
715
+ options: TOpt &
667
716
  InterpolationMap<Ret> & {
668
717
  context?: Key extends string
669
718
  ? unknown extends TOpt['context']
@@ -672,6 +721,14 @@ interface TFunctionStrict<
672
721
  : never;
673
722
  },
674
723
  ): TFunctionReturnOptionalDetails<TFunctionProcessReturnValue<$NoInfer<Ret>, never>, TOpt>;
724
+ <
725
+ const Key extends ParseKeys<Ns, TOpt, EffectiveKPrefix<KPrefix, TOpt>> | TemplateStringsArray,
726
+ const TOpt extends TOptions,
727
+ Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, EffectiveKPrefix<KPrefix, TOpt>>, TOpt>,
728
+ >(
729
+ key: (Key | Key[]) & _IfOptionalDefaultOptions<$NoInfer<Ret>>,
730
+ defaultValue: string,
731
+ ): TFunctionReturnOptionalDetails<TFunctionProcessReturnValue<$NoInfer<Ret>, never>, TOpt>;
675
732
  }
676
733
 
677
734
  interface TFunctionNonStrict<
@@ -728,6 +785,32 @@ export interface TFunction<
728
785
 
729
786
  export type KeyPrefix<Ns extends Namespace> = ResourceKeys<true>[$FirstNamespace<Ns>] | undefined;
730
787
 
788
+ /**
789
+ * The keys of `ParseKeys<Ns, {}, KPrefix>` that `t()` takes without options: their string has no
790
+ * variables, and a plural key is left out when its forms take `count`. For a wrapper that passes a
791
+ * key on to `t()`, which then compiles with `strictInterpolationChecks` (since v26.7.0):
792
+ *
793
+ * @example
794
+ * ```ts
795
+ * import type { ParseKeysWithoutVariables } from 'i18next';
796
+ *
797
+ * const label = (key: ParseKeysWithoutVariables<'common'>) => t(key);
798
+ * ```
799
+ */
800
+ export type ParseKeysWithoutVariables<
801
+ Ns extends Namespace = DefaultNamespace,
802
+ KPrefix = undefined,
803
+ > = _KeysWithoutVariables<ParseKeys<Ns, {}, KPrefix>, Ns, KPrefix>;
804
+
805
+ // resolved with `count`, so a plural key is checked against its plural forms
806
+ type _KeysWithoutVariables<Key, Ns extends Namespace, KPrefix> = Key extends string
807
+ ? {} extends InterpolationMap<
808
+ TFunctionReturn<Ns, AppendKeyPrefix<Key, KPrefix>, { count: number }>
809
+ >
810
+ ? Key
811
+ : never
812
+ : never;
813
+
731
814
  /**
732
815
  * Strict variant: every namespace (primary included) is exposed under its own
733
816
  * key on `$`. The flattened-primary form (`Resources[Ns[0]] &`) is dropped, so
@@ -826,7 +909,7 @@ interface TFunctionSelector<Ns extends Namespace, KPrefix, Source> extends Brand
826
909
  NewSrc extends GetSource<NewNs, KPrefix>,
827
910
  >(
828
911
  selectors: readonly SelectorFn<NewSrc, ApplyTarget<Target, Opts>, Opts>[],
829
- options: Opts & InterpolationMap<Target> & { ns: NewNs },
912
+ options: Opts & InterpolationMap<Target> & { ns: NewNs } & _CountIfPlural<Target>,
830
913
  ): SelectorReturn<Target, Opts>;
831
914
 
832
915
  // ── Single selector with explicit `ns` ──────────────────────────────────────
@@ -843,6 +926,21 @@ interface TFunctionSelector<Ns extends Namespace, KPrefix, Source> extends Brand
843
926
  } & (Target extends PluralValue<string> ? { count: number } : {}),
844
927
  ): SelectorReturn<Target, Opts>;
845
928
 
929
+ // ── Array of selectors with defaultValue — preserves literal type of DV ─────
930
+ // Same TypeScript limitation as the single-selector defaultValue overload below:
931
+ // `const Opts` loses the `defaultValue` literal when inferred through the
932
+ // conditional rest tuple of the general array overload. A plural member
933
+ // requires `count`, as in the single-selector overload.
934
+ <
935
+ const Fns extends readonly ((src: Select<Source, Opts['context']>) => string | object)[],
936
+ const DV extends string,
937
+ const Opts extends SelectorOptions<Ns[number]> = SelectorOptions<Ns[number]>,
938
+ >(
939
+ selectors: Fns,
940
+ options: Opts & { defaultValue: DV } & _CountIfPlural<_SelectorsReturn<Fns>> &
941
+ InterpolationMap<DeepUnwrapPlural<_SelectorsReturn<Fns>>>,
942
+ ): SelectorReturn<_SelectorsReturn<Fns>, Opts, DV>;
943
+
846
944
  // ── Array of selectors with default `ns` ─────────────────────────────────────
847
945
  // Captures the selector tuple as `const Fns` so TypeScript preserves each
848
946
  // element's exact return type. The union of return types is then extracted
@@ -854,14 +952,8 @@ interface TFunctionSelector<Ns extends Namespace, KPrefix, Source> extends Brand
854
952
  const Opts extends SelectorOptions<Ns[number]> = SelectorOptions<Ns[number]>,
855
953
  >(
856
954
  selectors: Fns,
857
- ...args: _SelectorOptionsArg<
858
- DeepUnwrapPlural<Fns[number] extends (...args: any[]) => infer R ? R : never>,
859
- Opts &
860
- InterpolationMap<
861
- DeepUnwrapPlural<Fns[number] extends (...args: any[]) => infer R ? R : never>
862
- >
863
- >
864
- ): SelectorReturn<Fns[number] extends (...args: any[]) => infer R ? R : never, Opts>;
955
+ ...args: _SelectorArrayOptionsArg<_SelectorsReturn<Fns>, Opts>
956
+ ): SelectorReturn<_SelectorsReturn<Fns>, Opts>;
865
957
 
866
958
  // ── Single selector with context + returnObjects ────────────────────────────
867
959
  // More specific than the general context overload below. Captures `Context` as
@@ -945,7 +1037,8 @@ type SelectorReturn<
945
1037
  ? TFunctionReturnOptionalDetails<ProcessReturnValue<DeepUnwrapPlural<Target>, DV>, Opts>
946
1038
  : DefaultTReturn<Opts>;
947
1039
 
948
- interface SelectorFn<Source, Target, Opts extends SelectorOptions<unknown>> {
1040
+ /** Public for react-i18next's `Trans` types (since v26.7.0). */
1041
+ export interface SelectorFn<Source, Target, Opts extends SelectorOptions<unknown>> {
949
1042
  (translations: Select<Source, Opts['context']>): Target;
950
1043
  }
951
1044
 
@@ -956,12 +1049,14 @@ type ApplyKeyPrefix<
956
1049
  ? ApplyKeyPrefix<[T[0][Head]], Tail>
957
1050
  : T[0][KPrefix & string];
958
1051
 
959
- type ApplyTarget<
1052
+ /** Public for react-i18next's `Trans` types (since v26.7.0). */
1053
+ export type ApplyTarget<
960
1054
  Target,
961
1055
  Opts extends { returnObjects?: unknown },
962
1056
  > = Opts['returnObjects'] extends true ? unknown : Target;
963
1057
 
964
- type ConstrainTarget<Opts extends SelectorOptions<any>> = _ReturnObjects extends true
1058
+ /** Public for react-i18next's `Trans` types (since v26.7.0). */
1059
+ export type ConstrainTarget<Opts extends SelectorOptions<any>> = _ReturnObjects extends true
965
1060
  ? unknown
966
1061
  : Opts['returnObjects'] extends true
967
1062
  ? unknown
@@ -988,7 +1083,8 @@ type SelectorReturnSource<KPrefix, Fallback> = KPrefix extends (...args: any[])
988
1083
  : Fallback
989
1084
  : Fallback;
990
1085
 
991
- type GetSource<Ns extends Namespace, KPrefix, Res = NsResource<Ns>> = KPrefix extends (
1086
+ /** Public for react-i18next's `Trans` types (since v26.7.0). */
1087
+ export type GetSource<Ns extends Namespace, KPrefix, Res = NsResource<Ns>> = KPrefix extends (
992
1088
  ...args: any[]
993
1089
  ) => any
994
1090
  ? SelectorReturnSource<KPrefix, Res>