1 | export interface FallbackLngObjList {
|
2 | [language: string]: string[];
|
3 | }
|
4 |
|
5 | export type FallbackLng = string | string[] | FallbackLngObjList;
|
6 |
|
7 | export type FormatFunction = (value: any, format?: string, lng?: string) => string;
|
8 |
|
9 | export interface InterpolationOptions {
|
10 | /**
|
11 | * Format function see formatting for details
|
12 | * @default noop
|
13 | */
|
14 | format?: FormatFunction;
|
15 | /**
|
16 | * Used to separate format from interpolation value
|
17 | * @default ','
|
18 | */
|
19 | formatSeparator?: string;
|
20 | /**
|
21 | * Escape function
|
22 | * @default str => str
|
23 | */
|
24 | escape?(str: string): string;
|
25 |
|
26 | /**
|
27 | * Escape passed in values to avoid xss injection
|
28 | * @default true
|
29 | */
|
30 | escapeValue?: boolean;
|
31 | /**
|
32 | * If true, then value passed into escape function is not casted to string, use with custom escape function that does its own type check
|
33 | * @default false
|
34 | */
|
35 | useRawValueToEscape?: boolean;
|
36 | /**
|
37 | * Prefix for interpolation
|
38 | * @default '{{'
|
39 | */
|
40 | prefix?: string;
|
41 | /**
|
42 | * Suffix for interpolation
|
43 | * @default '}}'
|
44 | */
|
45 | suffix?: string;
|
46 | /**
|
47 | * Escaped prefix for interpolation (regexSafe)
|
48 | * @default undefined
|
49 | */
|
50 | prefixEscaped?: string;
|
51 | /**
|
52 | * Escaped suffix for interpolation (regexSafe)
|
53 | * @default undefined
|
54 | */
|
55 | suffixEscaped?: string;
|
56 | /**
|
57 | * Suffix to unescaped mode
|
58 | * @default undefined
|
59 | */
|
60 | unescapeSuffix?: string;
|
61 | /**
|
62 | * Prefix to unescaped mode
|
63 | * @default '-'
|
64 | */
|
65 | unescapePrefix?: string;
|
66 | /**
|
67 | * Prefix for nesting
|
68 | * @default '$t('
|
69 | */
|
70 | nestingPrefix?: string;
|
71 | /**
|
72 | * Suffix for nesting
|
73 | * @default ')'
|
74 | */
|
75 | nestingSuffix?: string;
|
76 | /**
|
77 | * Escaped prefix for nesting (regexSafe)
|
78 | * @default undefined
|
79 | */
|
80 | nestingPrefixEscaped?: string;
|
81 | /**
|
82 | * Escaped suffix for nesting (regexSafe)
|
83 | * @default undefined
|
84 | */
|
85 | nestingSuffixEscaped?: string;
|
86 | /**
|
87 | * Separates options from key
|
88 | * @default ','
|
89 | */
|
90 | nestingOptionsSeparator?: string;
|
91 | /**
|
92 | * Global variables to use in interpolation replacements
|
93 | * @default undefined
|
94 | */
|
95 |
|
96 | defaultVariables?: { [index: string]: any };
|
97 | /**
|
98 | * After how many interpolation runs to break out before throwing a stack overflow
|
99 | * @default 1000
|
100 | */
|
101 | maxReplaces?: number;
|
102 |
|
103 | /**
|
104 | * If true, it will skip to interpolate the variables
|
105 | * @default false
|
106 | */
|
107 | skipOnVariables?: boolean;
|
108 | }
|
109 |
|
110 | export interface ReactOptions {
|
111 | /**
|
112 | * Set to true if you like to wait for loaded in every translated hoc
|
113 | * @default false
|
114 | */
|
115 | wait?: boolean;
|
116 | /**
|
117 | * Set it to fallback to let passed namespaces to translated hoc act as fallbacks
|
118 | * @default 'default'
|
119 | */
|
120 | nsMode?: 'default' | 'fallback';
|
121 | /**
|
122 | * Set it to the default parent element created by the Trans component.
|
123 | * @default 'div'
|
124 | */
|
125 | defaultTransParent?: string;
|
126 | /**
|
127 | * Set which events trigger a re-render, can be set to false or string of events
|
128 | * @default 'languageChanged'
|
129 | */
|
130 | bindI18n?: string | false;
|
131 | /**
|
132 | * Set which events on store trigger a re-render, can be set to false or string of events
|
133 | * @default ''
|
134 | */
|
135 | bindI18nStore?: string | false;
|
136 | /**
|
137 | * Set fallback value for Trans components without children
|
138 | * @default undefined
|
139 | */
|
140 | transEmptyNodeValue?: string;
|
141 | /**
|
142 | * Set it to false if you do not want to use Suspense
|
143 | * @default true
|
144 | */
|
145 | useSuspense?: boolean;
|
146 | /**
|
147 | * Function to generate an i18nKey from the defaultValue (or Trans children)
|
148 | * when no key is provided.
|
149 | * By default, the defaultValue (Trans text) itself is used as the key.
|
150 | * If you want to require keys for all translations, supply a function
|
151 | * that always throws an error.
|
152 | * @default undefined
|
153 | */
|
154 | hashTransKey?(defaultValue: TOptionsBase['defaultValue']): TOptionsBase['defaultValue'];
|
155 | /**
|
156 | * Convert eg. <br/> found in translations to a react component of type br
|
157 | * @default true
|
158 | */
|
159 | transSupportBasicHtmlNodes?: boolean;
|
160 | /**
|
161 | * Which nodes not to convert in defaultValue generation in the Trans component.
|
162 | * @default ['br', 'strong', 'i', 'p']
|
163 | */
|
164 | transKeepBasicHtmlNodesFor?: string[];
|
165 | }
|
166 |
|
167 | export interface InitOptions {
|
168 | /**
|
169 | * Logs info level to console output. Helps finding issues with loading not working.
|
170 | * @default false
|
171 | */
|
172 | debug?: boolean;
|
173 |
|
174 | /**
|
175 | * Resources to initialize with (if not using loading or not appending using addResourceBundle)
|
176 | * @default undefined
|
177 | */
|
178 | resources?: Resource;
|
179 |
|
180 | /**
|
181 | * Allow initializing with bundled resources while using a backend to load non bundled ones.
|
182 | * @default false
|
183 | */
|
184 | partialBundledLanguages?: boolean;
|
185 |
|
186 | /**
|
187 | * Language to use (overrides language detection)
|
188 | * @default undefined
|
189 | */
|
190 | lng?: string;
|
191 |
|
192 | /**
|
193 | * Language to use if translations in user language are not available.
|
194 | * @default 'dev'
|
195 | */
|
196 | fallbackLng?: false | FallbackLng;
|
197 |
|
198 | /**
|
199 | * DEPRECATED use supportedLngs
|
200 | * @default false
|
201 | */
|
202 | whitelist?: false | string[];
|
203 |
|
204 | /**
|
205 | * DEPRECTADED use nonExplicitSupportedLngs
|
206 | * @default false
|
207 | */
|
208 | nonExplicitWhiteliest?: boolean;
|
209 |
|
210 | /**
|
211 | * Array of allowed languages
|
212 | * @default false
|
213 | */
|
214 | supportedLngs?: false | string[];
|
215 |
|
216 | /**
|
217 | * If true will pass eg. en-US if finding en in supportedLngs
|
218 | * @default false
|
219 | */
|
220 | nonExplicitSupportedLngs?: boolean;
|
221 |
|
222 | /**
|
223 | * Language codes to lookup, given set language is
|
224 | * 'en-US': 'all' --> ['en-US', 'en', 'dev'],
|
225 | * 'currentOnly' --> 'en-US',
|
226 | * 'languageOnly' --> 'en'
|
227 | * @default 'all'
|
228 | */
|
229 | load?: 'all' | 'currentOnly' | 'languageOnly';
|
230 |
|
231 | /**
|
232 | * Array of languages to preload. Important on server-side to assert translations are loaded before rendering views.
|
233 | * @default false
|
234 | */
|
235 | preload?: false | string[];
|
236 |
|
237 | /**
|
238 | * Language will be lowercased eg. en-US --> en-us
|
239 | * @default false
|
240 | */
|
241 | lowerCaseLng?: boolean;
|
242 |
|
243 | /**
|
244 | * Language will be lowercased EN --> en while leaving full locales like en-US
|
245 | * @default false
|
246 | */
|
247 | cleanCode?: boolean;
|
248 |
|
249 | /**
|
250 | * String or array of namespaces to load
|
251 | * @default 'translation'
|
252 | */
|
253 | ns?: string | string[];
|
254 |
|
255 | /**
|
256 | * Default namespace used if not passed to translation function
|
257 | * @default 'translation'
|
258 | */
|
259 | defaultNS?: string;
|
260 |
|
261 | /**
|
262 | * String or array of namespaces to lookup key if not found in given namespace.
|
263 | * @default false
|
264 | */
|
265 | fallbackNS?: false | string | string[];
|
266 |
|
267 | /**
|
268 | * Calls save missing key function on backend if key not found
|
269 | * @default false
|
270 | */
|
271 | saveMissing?: boolean;
|
272 |
|
273 | /**
|
274 | * Experimental: enable to update default values using the saveMissing
|
275 | * (Works only if defaultValue different from translated value.
|
276 | * Only useful on initial development or when keeping code as source of truth not changing values outside of code.
|
277 | * Only supported if backend supports it already)
|
278 | * @default false
|
279 | */
|
280 | updateMissing?: boolean;
|
281 |
|
282 | /**
|
283 | * @default 'fallback'
|
284 | */
|
285 | saveMissingTo?: 'current' | 'all' | 'fallback';
|
286 |
|
287 | /**
|
288 | * Used for custom missing key handling (needs saveMissing set to true!)
|
289 | * @default false
|
290 | */
|
291 | missingKeyHandler?:
|
292 | | false
|
293 | | ((lngs: string[], ns: string, key: string, fallbackValue: string) => void);
|
294 |
|
295 | /**
|
296 | * Receives a key that was not found in `t()` and returns a value, that will be returned by `t()`
|
297 | * @default noop
|
298 | */
|
299 | parseMissingKeyHandler?(key: string): any;
|
300 |
|
301 | /**
|
302 | * Appends namespace to missing key
|
303 | * @default false
|
304 | */
|
305 | appendNamespaceToMissingKey?: boolean;
|
306 |
|
307 | /**
|
308 | * Gets called in case a interpolation value is undefined. This method will not be called if the value is empty string or null
|
309 | * @default noop
|
310 | */
|
311 | missingInterpolationHandler?: (text: string, value: any, options: InitOptions) => any;
|
312 |
|
313 | /**
|
314 | * Will use 'plural' as suffix for languages only having 1 plural form, setting it to false will suffix all with numbers
|
315 | * @default true
|
316 | */
|
317 | simplifyPluralSuffix?: boolean;
|
318 |
|
319 | /**
|
320 | * String or array of postProcessors to apply per default
|
321 | * @default false
|
322 | */
|
323 | postProcess?: false | string | string[];
|
324 |
|
325 | /**
|
326 | * passthrough the resolved object including 'usedNS', 'usedLang' etc into options object of postprocessors as 'i18nResolved' property
|
327 | * @default false
|
328 | */
|
329 | postProcessPassResolved?: boolean;
|
330 |
|
331 | /**
|
332 | * Allows null values as valid translation
|
333 | * @default true
|
334 | */
|
335 | returnNull?: boolean;
|
336 |
|
337 | /**
|
338 | * Allows empty string as valid translation
|
339 | * @default true
|
340 | */
|
341 | returnEmptyString?: boolean;
|
342 |
|
343 | /**
|
344 | * Allows objects as valid translation result
|
345 | * @default false
|
346 | */
|
347 | returnObjects?: boolean;
|
348 |
|
349 | /**
|
350 | * Gets called if object was passed in as key but returnObjects was set to false
|
351 | * @default noop
|
352 | */
|
353 | returnedObjectHandler?(key: string, value: string, options: any): void;
|
354 |
|
355 | /**
|
356 | * Char, eg. '\n' that arrays will be joined by
|
357 | * @default false
|
358 | */
|
359 | joinArrays?: false | string;
|
360 |
|
361 | /**
|
362 | * Sets defaultValue
|
363 | * @default args => ({ defaultValue: args[1] })
|
364 | */
|
365 | overloadTranslationOptionHandler?(args: string[]): TOptions;
|
366 |
|
367 | /**
|
368 | * @see https://www.i18next.com/interpolation.html
|
369 | */
|
370 | interpolation?: InterpolationOptions;
|
371 |
|
372 | /**
|
373 | * Options for language detection - check documentation of plugin
|
374 | * @default undefined
|
375 | */
|
376 | detection?: object;
|
377 |
|
378 | /**
|
379 | * Options for backend - check documentation of plugin
|
380 | * @default undefined
|
381 | */
|
382 | backend?: object;
|
383 |
|
384 | /**
|
385 | * Options for cache layer - check documentation of plugin
|
386 | * @default undefined
|
387 | */
|
388 | cache?: object;
|
389 |
|
390 | /**
|
391 | * Options for i18n message format - check documentation of plugin
|
392 | * @default undefined
|
393 | */
|
394 | i18nFormat?: object;
|
395 |
|
396 | /**
|
397 | * Options for react - check documentation of plugin
|
398 | * @default undefined
|
399 | */
|
400 | react?: ReactOptions;
|
401 |
|
402 | /**
|
403 | * Triggers resource loading in init function inside a setTimeout (default async behaviour).
|
404 | * Set it to false if your backend loads resources sync - that way calling i18next.t after
|
405 | * init is possible without relaying on the init callback.
|
406 | * @default true
|
407 | */
|
408 | initImmediate?: boolean;
|
409 |
|
410 | /**
|
411 | * Char to separate keys
|
412 | * @default '.'
|
413 | */
|
414 | keySeparator?: false | string;
|
415 |
|
416 | /**
|
417 | * Char to split namespace from key
|
418 | * @default ':'
|
419 | */
|
420 | nsSeparator?: false | string;
|
421 |
|
422 | /**
|
423 | * Char to split plural from key
|
424 | * @default '_'
|
425 | */
|
426 | pluralSeparator?: string;
|
427 |
|
428 | /**
|
429 | * Char to split context from key
|
430 | * @default '_'
|
431 | */
|
432 | contextSeparator?: string;
|
433 |
|
434 | /**
|
435 | * Prefixes the namespace to the returned key when using `cimode`
|
436 | * @default false
|
437 | */
|
438 | appendNamespaceToCIMode?: boolean;
|
439 |
|
440 | /**
|
441 | * Compatibility JSON version
|
442 | * @default 'v3'
|
443 | */
|
444 | compatibilityJSON?: 'v1' | 'v2' | 'v3';
|
445 |
|
446 | /**
|
447 | * Options for https://github.com/locize/locize-editor
|
448 | * @default undefined
|
449 | */
|
450 | editor?: {
|
451 | /**
|
452 | * Enable on init without the need of adding querystring locize=true
|
453 | * @default false
|
454 | */
|
455 | enabled?: boolean;
|
456 | /**
|
457 | * If set to false you will need to open the editor via API
|
458 | * @default true
|
459 | */
|
460 | autoOpen?: boolean;
|
461 |
|
462 | /**
|
463 | * Enable by adding querystring locize=true; can be set to another value or turned off by setting to false
|
464 | * @default 'locize'
|
465 | */
|
466 | enableByQS?: string | false;
|
467 |
|
468 | /**
|
469 | * Turn on/off by pressing key combination. Combine this with `toggleKeyCode`
|
470 | * @default 'ctrlKey'
|
471 | */
|
472 | toggleKeyModifier?: 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey';
|
473 | /**
|
474 | * Turn on/off by pressing key combination. Combine this with `toggleKeyModifier`
|
475 | * @default 24 (x)
|
476 | */
|
477 | toggleKeyCode?: number;
|
478 |
|
479 | /**
|
480 | * Use lng in editor taken from query string, eg. if running with lng=cimode (i18next, locize)
|
481 | * @default 'useLng'
|
482 | */
|
483 | lngOverrideQS?: string;
|
484 |
|
485 | /**
|
486 | * Use lng in editor, eg. if running with lng=cimode (i18next, locize)
|
487 | * @default null
|
488 | */
|
489 | lngOverride?: string | null;
|
490 |
|
491 | /**
|
492 | * How the editor will open.
|
493 | * Setting to window will open a new window/tab instead
|
494 | * @default 'iframe'
|
495 | */
|
496 | mode?: 'iframe' | 'window';
|
497 |
|
498 | /**
|
499 | * Styles to adapt layout in iframe mode to your website layout.
|
500 | * This will add a style to the `<iframe>`
|
501 | * @default 'z-index: 2000; position: fixed; top: 0; right: 0; bottom: 0; width: 600px; box-shadow: -3px 0 5px 0 rgba(0,0,0,0.5);'
|
502 | */
|
503 | iframeContainerStyle?: string;
|
504 | /**
|
505 | * Styles to adapt layout in iframe mode to your website layout.
|
506 | * This will add a style to the parent of `<iframe>`
|
507 | * @default 'height: 100%; width: 600px; border: none;'
|
508 | */
|
509 | iframeStyle?: string;
|
510 | /**
|
511 | * Styles to adapt layout in iframe mode to your website layout.
|
512 | * This will add a style to `<body>`
|
513 | * @default 'margin-right: 605px;'
|
514 | */
|
515 | bodyStyle?: string;
|
516 |
|
517 | /**
|
518 | * Handle when locize saved the edited translations, eg. reload website
|
519 | * @default noop
|
520 | */
|
521 | onEditorSaved?: (lng: null, ns: string | string[]) => void;
|
522 | };
|
523 |
|
524 | /**
|
525 | * Options for https://github.com/locize/locize-lastused
|
526 | * @default undefined
|
527 | */
|
528 | locizeLastUsed?: {
|
529 | /**
|
530 | * The id of your locize project
|
531 | */
|
532 | projectId: string;
|
533 |
|
534 | /**
|
535 | * An api key if you want to send missing keys
|
536 | */
|
537 | apiKey?: string;
|
538 |
|
539 | /**
|
540 | * The reference language of your project
|
541 | * @default 'en'
|
542 | */
|
543 | referenceLng?: string;
|
544 |
|
545 | /**
|
546 | * Version
|
547 | * @default 'latest'
|
548 | */
|
549 | version?: string;
|
550 |
|
551 | /**
|
552 | * Debounce interval to send data in milliseconds
|
553 | * @default 90000
|
554 | */
|
555 | debounceSubmit?: number;
|
556 |
|
557 | /**
|
558 | * Hostnames that are allowed to send last used data.
|
559 | * Please keep those to your local system, staging, test servers (not production)
|
560 | * @default ['localhost']
|
561 | */
|
562 | allowedHosts?: string[];
|
563 | };
|
564 | }
|
565 |
|
566 | export interface TOptionsBase {
|
567 | /**
|
568 | * Default value to return if a translation was not found
|
569 | */
|
570 | defaultValue?: any;
|
571 | /**
|
572 | * Count value used for plurals
|
573 | */
|
574 | count?: number;
|
575 | /**
|
576 | * Used for contexts (eg. male\female)
|
577 | */
|
578 | context?: any;
|
579 | /**
|
580 | * Object with vars for interpolation - or put them directly in options
|
581 | */
|
582 | replace?: any;
|
583 | /**
|
584 | * Override language to use
|
585 | */
|
586 | lng?: string;
|
587 | /**
|
588 | * Override languages to use
|
589 | */
|
590 | lngs?: string[];
|
591 | /**
|
592 | * Override language to lookup key if not found see fallbacks for details
|
593 | */
|
594 | fallbackLng?: FallbackLng;
|
595 | /**
|
596 | * Override namespaces (string or array)
|
597 | */
|
598 | ns?: string | string[];
|
599 | /**
|
600 | * Override char to separate keys
|
601 | */
|
602 | keySeparator?: false | string;
|
603 | /**
|
604 | * Override char to split namespace from key
|
605 | */
|
606 | nsSeparator?: false | string;
|
607 | /**
|
608 | * Accessing an object not a translation string (can be set globally too)
|
609 | */
|
610 | returnObjects?: boolean;
|
611 | /**
|
612 | * Char, eg. '\n' that arrays will be joined by (can be set globally too)
|
613 | */
|
614 | joinArrays?: string;
|
615 | /**
|
616 | * String or array of postProcessors to apply see interval plurals as a sample
|
617 | */
|
618 | postProcess?: string | string[];
|
619 | /**
|
620 | * Override interpolation options
|
621 | */
|
622 | interpolation?: InterpolationOptions;
|
623 | }
|
624 |
|
625 | /**
|
626 | * indexer that is open to any value
|
627 | */
|
628 | export type StringMap = { [key: string]: any };
|
629 |
|
630 | /**
|
631 | * Options that allow open ended values for interpolation unless type is provided.
|
632 | */
|
633 | export type TOptions<TInterpolationMap extends object = StringMap> = TOptionsBase &
|
634 | TInterpolationMap;
|
635 |
|
636 | export type Callback = (error: any, t: TFunction) => void;
|
637 |
|
638 | /**
|
639 | * Uses similar args as the t function and returns true if a key exists.
|
640 | */
|
641 | export interface ExistsFunction<
|
642 | TKeys extends string = string,
|
643 | TInterpolationMap extends object = StringMap
|
644 | > {
|
645 | (key: TKeys | TKeys[], options?: TOptions<TInterpolationMap>): boolean;
|
646 | }
|
647 |
|
648 | export interface WithT {
|
649 | // Expose parameterized t in the i18next interface hierarchy
|
650 | t: TFunction;
|
651 | }
|
652 |
|
653 | export type TFunctionResult = string | object | Array<string | object> | undefined | null;
|
654 | export type TFunctionKeys = string | TemplateStringsArray;
|
655 | export interface TFunction {
|
656 | // basic usage
|
657 | <
|
658 | TResult extends TFunctionResult = string,
|
659 | TKeys extends TFunctionKeys = string,
|
660 | TInterpolationMap extends object = StringMap
|
661 | >(
|
662 | key: TKeys | TKeys[],
|
663 | options?: TOptions<TInterpolationMap> | string,
|
664 | ): TResult;
|
665 | // overloaded usage
|
666 | <
|
667 | TResult extends TFunctionResult = string,
|
668 | TKeys extends TFunctionKeys = string,
|
669 | TInterpolationMap extends object = StringMap
|
670 | >(
|
671 | key: TKeys | TKeys[],
|
672 | defaultValue?: string,
|
673 | options?: TOptions<TInterpolationMap> | string,
|
674 | ): TResult;
|
675 | }
|
676 |
|
677 | export interface Resource {
|
678 | [language: string]: ResourceLanguage;
|
679 | }
|
680 |
|
681 | export interface ResourceLanguage {
|
682 | [namespace: string]: ResourceKey;
|
683 | }
|
684 |
|
685 | export type ResourceKey =
|
686 | | string
|
687 | | {
|
688 | [key: string]: any;
|
689 | };
|
690 |
|
691 | export interface Interpolator {
|
692 | init(options: InterpolationOptions, reset: boolean): undefined;
|
693 | reset(): undefined;
|
694 | resetRegExp(): undefined;
|
695 | interpolate(str: string, data: object, lng: string, options: InterpolationOptions): string;
|
696 | nest(str: string, fc: (...args: any[]) => any, options: InterpolationOptions): string;
|
697 | }
|
698 |
|
699 | export class ResourceStore {
|
700 | constructor(data: Resource, options: InitOptions);
|
701 |
|
702 | public data: Resource;
|
703 | public options: InitOptions;
|
704 |
|
705 | /**
|
706 | * Gets fired when resources got added or removed
|
707 | */
|
708 | on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void;
|
709 | /**
|
710 | * Remove event listener
|
711 | * removes all callback when callback not specified
|
712 | */
|
713 | off(event: 'added' | 'removed', callback?: (lng: string, ns: string) => void): void;
|
714 | }
|
715 |
|
716 | export interface Services {
|
717 | backendConnector: any;
|
718 | i18nFormat: any;
|
719 | interpolator: Interpolator;
|
720 | languageDetector: any;
|
721 | languageUtils: any;
|
722 | logger: any;
|
723 | pluralResolver: any;
|
724 | resourceStore: ResourceStore;
|
725 | }
|
726 |
|
727 | export interface Module {
|
728 | type: 'backend' | 'logger' | 'languageDetector' | 'postProcessor' | 'i18nFormat' | '3rdParty';
|
729 | }
|
730 |
|
731 | export type CallbackError = Error | null | undefined;
|
732 | export type ReadCallback = (err: CallbackError, data: ResourceKey | boolean) => void;
|
733 | export type MultiReadCallback = (err: CallbackError, data: Resource) => void;
|
734 |
|
735 | /**
|
736 | * Used to load data for i18next.
|
737 | * Can be provided as a singleton or as a prototype constructor (preferred for supporting multiple instances of i18next).
|
738 | * For singleton set property `type` to `'backend'` For a prototype constructor set static property.
|
739 | */
|
740 | export interface BackendModule<TOptions = object> extends Module {
|
741 | type: 'backend';
|
742 | init(services: Services, backendOptions: TOptions, i18nextOptions: InitOptions): void;
|
743 | read(language: string, namespace: string, callback: ReadCallback): void;
|
744 | /** Save the missing translation */
|
745 | create(languages: string[], namespace: string, key: string, fallbackValue: string): void;
|
746 | /** Load multiple languages and namespaces. For backends supporting multiple resources loading */
|
747 | readMulti?(languages: string[], namespaces: string[], callback: ReadCallback): void;
|
748 | /** Store the translation. For backends acting as cache layer */
|
749 | save?(language: string, namespace: string, data: ResourceLanguage): void;
|
750 | }
|
751 |
|
752 | /**
|
753 | * Used to detect language in user land.
|
754 | * Can be provided as a singleton or as a prototype constructor (preferred for supporting multiple instances of i18next).
|
755 | * For singleton set property `type` to `'languageDetector'` For a prototype constructor set static property.
|
756 | */
|
757 | export interface LanguageDetectorModule extends Module {
|
758 | type: 'languageDetector';
|
759 | init(services: Services, detectorOptions: object, i18nextOptions: InitOptions): void;
|
760 | /** Must return detected language */
|
761 | detect(): string | undefined;
|
762 | cacheUserLanguage(lng: string): void;
|
763 | }
|
764 |
|
765 | /**
|
766 | * Used to detect language in user land.
|
767 | * Can be provided as a singleton or as a prototype constructor (preferred for supporting multiple instances of i18next).
|
768 | * For singleton set property `type` to `'languageDetector'` For a prototype constructor set static property.
|
769 | */
|
770 | export interface LanguageDetectorAsyncModule extends Module {
|
771 | type: 'languageDetector';
|
772 | /** Set to true to enable async detection */
|
773 | async: true;
|
774 | init(services: Services, detectorOptions: object, i18nextOptions: InitOptions): void;
|
775 | /** Must call callback passing detected language */
|
776 | detect(callback: (lng: string) => void): void;
|
777 | cacheUserLanguage(lng: string): void;
|
778 | }
|
779 |
|
780 | /**
|
781 | * Used to extend or manipulate the translated values before returning them in `t` function.
|
782 | * Need to be a singleton object.
|
783 | */
|
784 | export interface PostProcessorModule extends Module {
|
785 | /** Unique name */
|
786 | name: string;
|
787 | type: 'postProcessor';
|
788 | process(value: string, key: string, options: TOptions, translator: any): string;
|
789 | }
|
790 |
|
791 | /**
|
792 | * Override the built-in console logger.
|
793 | * Do not need to be a prototype function.
|
794 | */
|
795 | export interface LoggerModule extends Module {
|
796 | type: 'logger';
|
797 | log(...args: any[]): void;
|
798 | warn(...args: any[]): void;
|
799 | error(...args: any[]): void;
|
800 | }
|
801 |
|
802 | export interface I18nFormatModule extends Module {
|
803 | type: 'i18nFormat';
|
804 | }
|
805 |
|
806 | export interface ThirdPartyModule extends Module {
|
807 | type: '3rdParty';
|
808 | init(i18next: i18n): void;
|
809 | }
|
810 |
|
811 | export interface Modules {
|
812 | backend?: BackendModule;
|
813 | logger?: LoggerModule;
|
814 | languageDetector?: LanguageDetectorModule | LanguageDetectorAsyncModule;
|
815 | i18nFormat?: I18nFormatModule;
|
816 | external: ThirdPartyModule[];
|
817 | }
|
818 |
|
819 | // helper to identify class https://stackoverflow.com/a/45983481/2363935
|
820 | export type Newable<T> = { new (...args: any[]): T };
|
821 |
|
822 | export interface i18n {
|
823 | // Expose parameterized t in the i18next interface hierarchy
|
824 | t: TFunction;
|
825 |
|
826 | /**
|
827 | * The default of the i18next module is an i18next instance ready to be initialized by calling init.
|
828 | * You can create additional instances using the createInstance function.
|
829 | *
|
830 | * @param options - Initial options.
|
831 | * @param callback - will be called after all translations were loaded or with an error when failed (in case of using a backend).
|
832 | */
|
833 | init(callback?: Callback): Promise<TFunction>;
|
834 | init(options: InitOptions, callback?: Callback): Promise<TFunction>;
|
835 |
|
836 | loadResources(callback?: (err: any) => void): void;
|
837 |
|
838 | /**
|
839 | * The use function is there to load additional plugins to i18next.
|
840 | * For available module see the plugins page and don't forget to read the documentation of the plugin.
|
841 | *
|
842 | * Accepts a class or object
|
843 | */
|
844 | use<T extends Module>(
|
845 | module: T | Newable<T> | ThirdPartyModule[] | Newable<ThirdPartyModule>[],
|
846 | ): i18n;
|
847 |
|
848 | /**
|
849 | * List of modules used
|
850 | */
|
851 | modules: Modules;
|
852 |
|
853 | /**
|
854 | * Internal container for all used plugins and implementation details like languageUtils, pluralResolvers, etc.
|
855 | */
|
856 | services: Services;
|
857 |
|
858 | /**
|
859 | * Internal container for translation resources
|
860 | */
|
861 | store: ResourceStore;
|
862 |
|
863 | /**
|
864 | * Uses similar args as the t function and returns true if a key exists.
|
865 | */
|
866 | exists: ExistsFunction;
|
867 |
|
868 | /**
|
869 | * Returns a resource data by language.
|
870 | */
|
871 | getDataByLanguage(lng: string): { translation: { [key: string]: string } } | undefined;
|
872 |
|
873 | /**
|
874 | * Returns a t function that defaults to given language or namespace.
|
875 | * Both params could be arrays of languages or namespaces and will be treated as fallbacks in that case.
|
876 | * On the returned function you can like in the t function override the languages or namespaces by passing them in options or by prepending namespace.
|
877 | */
|
878 | getFixedT(lng: string | string[], ns?: string | string[]): TFunction;
|
879 | getFixedT(lng: null, ns: string | string[]): TFunction;
|
880 |
|
881 | /**
|
882 | * Changes the language. The callback will be called as soon translations were loaded or an error occurs while loading.
|
883 | * HINT: For easy testing - setting lng to 'cimode' will set t function to always return the key.
|
884 | */
|
885 | changeLanguage(lng: string, callback?: Callback): Promise<TFunction>;
|
886 |
|
887 | /**
|
888 | * Is set to the current detected or set language.
|
889 | * If you need the primary used language depending on your configuration (supportedLngs, load) you will prefer using i18next.languages[0].
|
890 | */
|
891 | language: string;
|
892 |
|
893 | /**
|
894 | * Is set to an array of language-codes that will be used it order to lookup the translation value.
|
895 | */
|
896 | languages: string[];
|
897 |
|
898 | /**
|
899 | * Loads additional namespaces not defined in init options.
|
900 | */
|
901 | loadNamespaces(ns: string | string[], callback?: Callback): Promise<void>;
|
902 |
|
903 | /**
|
904 | * Loads additional languages not defined in init options (preload).
|
905 | */
|
906 | loadLanguages(lngs: string | string[], callback?: Callback): Promise<void>;
|
907 |
|
908 | /**
|
909 | * Reloads resources on given state. Optionally you can pass an array of languages and namespaces as params if you don't want to reload all.
|
910 | */
|
911 | reloadResources(
|
912 | lngs?: string | string[],
|
913 | ns?: string | string[],
|
914 | callback?: () => void,
|
915 | ): Promise<void>;
|
916 | reloadResources(lngs: null, ns: string | string[], callback?: () => void): Promise<void>;
|
917 |
|
918 | /**
|
919 | * Changes the default namespace.
|
920 | */
|
921 | setDefaultNamespace(ns: string): void;
|
922 |
|
923 | /**
|
924 | * Returns rtl or ltr depending on languages read direction.
|
925 | */
|
926 | dir(lng?: string): 'ltr' | 'rtl';
|
927 |
|
928 | /**
|
929 | * Exposes interpolation.format function added on init.
|
930 | */
|
931 | format: FormatFunction;
|
932 |
|
933 | /**
|
934 | * Will return a new i18next instance.
|
935 | * Please read the options page for details on configuration options.
|
936 | * Providing a callback will automatically call init.
|
937 | * The callback will be called after all translations were loaded or with an error when failed (in case of using a backend).
|
938 | */
|
939 | createInstance(options?: InitOptions, callback?: Callback): i18n;
|
940 |
|
941 | /**
|
942 | * Creates a clone of the current instance. Shares store, plugins and initial configuration.
|
943 | * Can be used to create an instance sharing storage but being independent on set language or namespaces.
|
944 | */
|
945 | cloneInstance(options?: InitOptions, callback?: Callback): i18n;
|
946 |
|
947 | /**
|
948 | * Gets fired after initialization.
|
949 | */
|
950 | on(event: 'initialized', callback: (options: InitOptions) => void): void;
|
951 |
|
952 | /**
|
953 | * Gets fired on loaded resources.
|
954 | */
|
955 | on(event: 'loaded', callback: (loaded: boolean) => void): void;
|
956 |
|
957 | /**
|
958 | * Gets fired if loading resources failed.
|
959 | */
|
960 | on(event: 'failedLoading', callback: (lng: string, ns: string, msg: string) => void): void;
|
961 |
|
962 | /**
|
963 | * Gets fired on accessing a key not existing.
|
964 | */
|
965 | on(
|
966 | event: 'missingKey',
|
967 | callback: (lngs: string[], namespace: string, key: string, res: string) => void,
|
968 | ): void;
|
969 |
|
970 | /**
|
971 | * Gets fired when resources got added or removed.
|
972 | */
|
973 | on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void;
|
974 |
|
975 | /**
|
976 | * Gets fired when changeLanguage got called.
|
977 | */
|
978 | on(event: 'languageChanged', callback: (lng: string) => void): void;
|
979 |
|
980 | /**
|
981 | * Event listener
|
982 | */
|
983 | on(event: string, listener: (...args: any[]) => void): void;
|
984 |
|
985 | /**
|
986 | * Remove event listener
|
987 | * removes all callback when callback not specified
|
988 | */
|
989 | off(event: string, listener?: (...args: any[]) => void): void;
|
990 |
|
991 | /**
|
992 | * Gets one value by given key.
|
993 | */
|
994 | getResource(lng: string, ns: string, key: string, options?: { keySeparator?: string }): any;
|
995 |
|
996 | /**
|
997 | * Adds one key/value.
|
998 | */
|
999 | addResource(
|
1000 | lng: string,
|
1001 | ns: string,
|
1002 | key: string,
|
1003 | value: string,
|
1004 | options?: { keySeparator?: string; silent?: boolean },
|
1005 | ): void;
|
1006 |
|
1007 | /**
|
1008 | * Adds multiple key/values.
|
1009 | */
|
1010 | addResources(lng: string, ns: string, resources: any): void;
|
1011 |
|
1012 | /**
|
1013 | * Adds a complete bundle.
|
1014 | * Setting deep param to true will extend existing translations in that file.
|
1015 | * Setting overwrite to true it will overwrite existing translations in that file.
|
1016 | */
|
1017 | addResourceBundle(
|
1018 | lng: string,
|
1019 | ns: string,
|
1020 | resources: any,
|
1021 | deep?: boolean,
|
1022 | overwrite?: boolean,
|
1023 | ): void;
|
1024 |
|
1025 | /**
|
1026 | * Checks if a resource bundle exists.
|
1027 | */
|
1028 | hasResourceBundle(lng: string, ns: string): boolean;
|
1029 |
|
1030 | /**
|
1031 | * Returns a resource bundle.
|
1032 | */
|
1033 | getResourceBundle(lng: string, ns: string): any;
|
1034 |
|
1035 | /**
|
1036 | * Removes an existing bundle.
|
1037 | */
|
1038 | removeResourceBundle(lng: string, ns: string): void;
|
1039 |
|
1040 | /**
|
1041 | * Current options
|
1042 | */
|
1043 | options: InitOptions;
|
1044 |
|
1045 | /**
|
1046 | * Is initialized
|
1047 | */
|
1048 | isInitialized: boolean;
|
1049 |
|
1050 | /**
|
1051 | * Emit event
|
1052 | */
|
1053 | emit(eventName: string): void;
|
1054 | }
|
1055 |
|
1056 | declare const i18next: i18n;
|
1057 | export default i18next;
|