i18next 26.7.1 → 27.0.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.
@@ -1,5 +1,9 @@
1
1
  import type { $MergeBy, $PreservedValue, $Dictionary } from './helpers.js';
2
2
 
3
+ // Only the declarations marked `export` are public: without an export list, every declaration of a
4
+ // .d.ts module counts as exported, and the `_` helpers below were importable.
5
+ export {};
6
+
3
7
  /**
4
8
  * This interface can be augmented by users to add types to `i18next` default TypeOptions.
5
9
  *
@@ -116,7 +120,7 @@ export type TypeOptions = $MergeBy<
116
120
  returnNull: false;
117
121
 
118
122
  /** @see {InitOptions.returnEmptyString} */
119
- returnEmptyString: true;
123
+ returnEmptyString: false;
120
124
 
121
125
  /** @see {InitOptions.returnObjects} */
122
126
  returnObjects: false;
@@ -139,12 +143,6 @@ export type TypeOptions = $MergeBy<
139
143
  /** @see {InitOptions.fallbackNS} */
140
144
  fallbackNS: false;
141
145
 
142
- /**
143
- * @see {InitOptions.compatibilityJSON}
144
- * @deprecated has no effect, removed in v27. Remove it from `CustomTypeOptions`.
145
- */
146
- compatibilityJSON: 'v4';
147
-
148
146
  /** @see {InitOptions.resources} */
149
147
  resources: object;
150
148
 
@@ -167,8 +165,11 @@ export type TypeOptions = $MergeBy<
167
165
  * string-key API (with `strictKeyChecks`, also to `t(key, defaultValue)`) and
168
166
  * to the selector API. Messages under `parseInterpolation: 'icu'` or `'mf2'`
169
167
  * require their arguments regardless of this flag.
168
+ *
169
+ * On by default since v27; set it to `false` to keep the v26 types.
170
+ * @default true
170
171
  */
171
- strictInterpolationChecks: false;
172
+ strictInterpolationChecks: true;
172
173
 
173
174
  /**
174
175
  * Prefix for interpolation
@@ -390,18 +391,6 @@ export interface InterpolationOptions {
390
391
  * @default '}}'
391
392
  */
392
393
  suffix?: string;
393
- /**
394
- * Escaped prefix for interpolation (regexSafe)
395
- * @default undefined
396
- * @deprecated inserted into the RegExp unescaped, removed in v27. Pass the literal delimiter as `prefix`.
397
- */
398
- prefixEscaped?: string;
399
- /**
400
- * Escaped suffix for interpolation (regexSafe)
401
- * @default undefined
402
- * @deprecated inserted into the RegExp unescaped, removed in v27. Pass the literal delimiter as `suffix`.
403
- */
404
- suffixEscaped?: string;
405
394
  /**
406
395
  * Suffix to unescaped mode
407
396
  * @default undefined
@@ -422,18 +411,6 @@ export interface InterpolationOptions {
422
411
  * @default ')'
423
412
  */
424
413
  nestingSuffix?: string;
425
- /**
426
- * Escaped prefix for nesting (regexSafe)
427
- * @default undefined
428
- * @deprecated inserted into the RegExp unescaped, removed in v27. Pass the literal delimiter as `nestingPrefix`.
429
- */
430
- nestingPrefixEscaped?: string;
431
- /**
432
- * Escaped suffix for nesting (regexSafe)
433
- * @default undefined
434
- * @deprecated inserted into the RegExp unescaped, removed in v27. Pass the literal delimiter as `nestingSuffix`.
435
- */
436
- nestingSuffixEscaped?: string;
437
414
  /**
438
415
  * Separates options from key
439
416
  * @default ','
@@ -468,83 +445,11 @@ export type FallbackLng =
468
445
  | FallbackLngObjList
469
446
  | ((code: string) => string | readonly string[] | FallbackLngObjList);
470
447
 
471
- export interface ReactOptions {
472
- /**
473
- * Set it to fallback to let passed namespaces to translated hoc act as fallbacks
474
- * @default 'default'
475
- */
476
- nsMode?: 'default' | 'fallback';
477
- /**
478
- * Set it to the default parent element created by the Trans component.
479
- * @default 'div'
480
- */
481
- defaultTransParent?: string;
482
- /**
483
- * Set which events trigger a re-render, can be set to false or string of events
484
- * @default 'languageChanged'
485
- */
486
- bindI18n?: string | false;
487
- /**
488
- * Set which events on store trigger a re-render, can be set to false or string of events
489
- * @default ''
490
- */
491
- bindI18nStore?: string | false;
492
- /**
493
- * Set fallback value for Trans components without children
494
- * @default undefined
495
- */
496
- transEmptyNodeValue?: string;
497
- /**
498
- * Set it to false if you do not want to use Suspense
499
- * @default true
500
- */
501
- useSuspense?: boolean;
502
- /**
503
- * Function to generate an i18nKey from the defaultValue (or Trans children)
504
- * when no key is provided.
505
- * By default, the defaultValue (Trans text) itself is used as the key.
506
- * If you want to require keys for all translations, supply a function
507
- * that always throws an error.
508
- * @default undefined
509
- */
510
- hashTransKey?(defaultValue: TOptionsBase['defaultValue']): TOptionsBase['defaultValue'];
511
- /**
512
- * Convert eg. <br/> found in translations to a react component of type br
513
- * @default true
514
- */
515
- transSupportBasicHtmlNodes?: boolean;
516
- /**
517
- * Which nodes not to convert in defaultValue generation in the Trans component.
518
- * @default ['br', 'strong', 'i', 'p']
519
- */
520
- transKeepBasicHtmlNodesFor?: readonly string[];
521
- /**
522
- * Wrap text nodes in a user-specified element.
523
- * @default ''
524
- */
525
- transWrapTextNodes?: string;
526
- /**
527
- * Default props to apply to all Trans components.
528
- * Component-level props will override these defaults.
529
- */
530
- transDefaultProps?: {
531
- tOptions?: TOptions;
532
- values?: object;
533
- shouldUnescape?: boolean;
534
- components?: readonly unknown[] | { readonly [tagName: string]: unknown }; // Use `unknown` (or `any`) to be permissive without importing React.
535
- };
536
- /**
537
- * Optional keyPrefix that will be automatically applied to returned t function in useTranslation for example.
538
- * Accepts a string or a selector function (e.g. `$ => $.deeply.nested`).
539
- * @default undefined
540
- */
541
- keyPrefix?: string | (($: any) => any);
542
- /**
543
- * Unescape function
544
- * by default it unescapes some basic html entities
545
- */
546
- unescape?(str: string): string;
547
- }
448
+ /**
449
+ * The `react` options of react-i18next, which fills in this interface (since v27; before, i18next
450
+ * declared them). Without react-i18next in the program, `react` takes any object.
451
+ */
452
+ export interface ReactOptions {}
548
453
 
549
454
  export type ResourceKey =
550
455
  | string
@@ -587,7 +492,8 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
587
492
 
588
493
  /**
589
494
  * Language to use if translations in user language are not available.
590
- * @default 'dev'
495
+ * Since v27 there is none by default; `'dev'` was the default before.
496
+ * @default false
591
497
  */
592
498
  fallbackLng?: false | FallbackLng;
593
499
 
@@ -604,7 +510,7 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
604
510
  nonExplicitSupportedLngs?: boolean;
605
511
 
606
512
  /**
607
- * Language codes to lookup, given set language is 'en-US':
513
+ * Language codes to lookup, given set language is 'en-US' and fallbackLng 'dev':
608
514
  * 'all' --> ['en-US', 'en', 'dev'],
609
515
  * 'currentOnly' --> 'en-US',
610
516
  * 'languageOnly' --> 'en'
@@ -625,11 +531,11 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
625
531
  lowerCaseLng?: boolean;
626
532
 
627
533
  /**
628
- * Language will be lowercased EN --> en while leaving full locales like en-US
629
- *
630
- * From v27 codes without a region are canonicalized by default, as codes with one already are
631
- * (`'EN'` → `'en'`, `'iw'` → `'he'`), and this option is deprecated.
632
- * @default false
534
+ * Since v27, codes without a region get their canonical casing (`'EN'` → `'en'`); aliases like
535
+ * `'tl'` or `'iw'` stay. `false` keeps them as they are, as before v27. `true` also lower-cases a
536
+ * code that is not BCP 47.
537
+ * @deprecated canonical codes are the default since v27
538
+ * @default undefined
633
539
  */
634
540
  cleanCode?: boolean;
635
541
 
@@ -741,8 +647,9 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
741
647
  returnNull?: boolean;
742
648
 
743
649
  /**
744
- * Allows empty string as valid translation
745
- * @default true
650
+ * Allows empty string as valid translation. Since v27 an empty string falls back like a missing value
651
+ * by default.
652
+ * @default false
746
653
  */
747
654
  returnEmptyString?: boolean;
748
655
 
@@ -760,7 +667,7 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
760
667
 
761
668
  /**
762
669
  * Gets called if object was passed in as key but returnObjects was set to false.
763
- * What it returns is what `t()` returns.
670
+ * What it returns is what `t()` returns; without it, `t()` returns the key (since v27).
764
671
  * @default noop
765
672
  */
766
673
  returnedObjectHandler?(key: string, value: string, options: any): unknown;
@@ -839,55 +746,6 @@ export interface InitOptions<T = object> extends PluginOptions<T> {
839
746
  */
840
747
  appendNamespaceToCIMode?: boolean;
841
748
 
842
- /**
843
- * Compatibility JSON version
844
- * @warning only `v4` is available and supported by typescript
845
- * @default 'v4'
846
- * @deprecated has no effect since v24 (only the v4 JSON format is supported), removed in v27. Remove the option.
847
- */
848
- compatibilityJSON?: 'v4';
849
-
850
- /**
851
- * Options for https://github.com/locize/locize-lastused
852
- * @default undefined
853
- */
854
- locizeLastUsed?: {
855
- /**
856
- * The id of your locize project
857
- */
858
- projectId: string;
859
-
860
- /**
861
- * An api key if you want to send missing keys
862
- */
863
- apiKey?: string;
864
-
865
- /**
866
- * The reference language of your project
867
- * @default 'en'
868
- */
869
- referenceLng?: string;
870
-
871
- /**
872
- * Version
873
- * @default 'latest'
874
- */
875
- version?: string;
876
-
877
- /**
878
- * Debounce interval to send data in milliseconds
879
- * @default 90000
880
- */
881
- debounceSubmit?: number;
882
-
883
- /**
884
- * Hostnames that are allowed to send last used data.
885
- * Please keep those to your local system, staging, test servers (not production)
886
- * @default ['localhost']
887
- */
888
- allowedHosts?: readonly string[];
889
- };
890
-
891
749
  /**
892
750
  * Automatically lookup for a flat key if a nested key is not found an vice-versa
893
751
  * @default true