type Omit = Pick>; type MergeBy = Omit & K; export interface FallbackLngObjList { [language: string]: readonly string[]; } export type FallbackLng = | string | readonly string[] | FallbackLngObjList | ((code: string) => string | readonly string[] | FallbackLngObjList); export type FormatFunction = ( value: any, format?: string, lng?: string, options?: InterpolationOptions & { [key: string]: any }, ) => string; export interface InterpolationOptions { /** * Format function see formatting for details * @default noop */ format?: FormatFunction; /** * Used to separate format from interpolation value * @default ',' */ formatSeparator?: string; /** * Escape function * @default str => str */ escape?(str: string): string; /** * Always format interpolated values. * @default false */ alwaysFormat?: boolean; /** * Escape passed in values to avoid xss injection * @default true */ escapeValue?: boolean; /** * If true, then value passed into escape function is not casted to string, use with custom escape function that does its own type check * @default false */ useRawValueToEscape?: boolean; /** * Prefix for interpolation * @default '{{' */ prefix?: string; /** * Suffix for interpolation * @default '}}' */ suffix?: string; /** * Escaped prefix for interpolation (regexSafe) * @default undefined */ prefixEscaped?: string; /** * Escaped suffix for interpolation (regexSafe) * @default undefined */ suffixEscaped?: string; /** * Suffix to unescaped mode * @default undefined */ unescapeSuffix?: string; /** * Prefix to unescaped mode * @default '-' */ unescapePrefix?: string; /** * Prefix for nesting * @default '$t(' */ nestingPrefix?: string; /** * Suffix for nesting * @default ')' */ nestingSuffix?: string; /** * Escaped prefix for nesting (regexSafe) * @default undefined */ nestingPrefixEscaped?: string; /** * Escaped suffix for nesting (regexSafe) * @default undefined */ nestingSuffixEscaped?: string; /** * Separates options from key * @default ',' */ nestingOptionsSeparator?: string; /** * Global variables to use in interpolation replacements * @default undefined */ defaultVariables?: { [index: string]: any }; /** * After how many interpolation runs to break out before throwing a stack overflow * @default 1000 */ maxReplaces?: number; /** * If true, it will skip to interpolate the variables * @default true */ skipOnVariables?: boolean; } export interface ReactOptions { /** * Set it to fallback to let passed namespaces to translated hoc act as fallbacks * @default 'default' */ nsMode?: 'default' | 'fallback'; /** * Set it to the default parent element created by the Trans component. * @default 'div' */ defaultTransParent?: string; /** * Set which events trigger a re-render, can be set to false or string of events * @default 'languageChanged' */ bindI18n?: string | false; /** * Set which events on store trigger a re-render, can be set to false or string of events * @default '' */ bindI18nStore?: string | false; /** * Set fallback value for Trans components without children * @default undefined */ transEmptyNodeValue?: string; /** * Set it to false if you do not want to use Suspense * @default true */ useSuspense?: boolean; /** * Function to generate an i18nKey from the defaultValue (or Trans children) * when no key is provided. * By default, the defaultValue (Trans text) itself is used as the key. * If you want to require keys for all translations, supply a function * that always throws an error. * @default undefined */ hashTransKey?(defaultValue: TOptionsBase['defaultValue']): TOptionsBase['defaultValue']; /** * Convert eg.
found in translations to a react component of type br * @default true */ transSupportBasicHtmlNodes?: boolean; /** * Which nodes not to convert in defaultValue generation in the Trans component. * @default ['br', 'strong', 'i', 'p'] */ transKeepBasicHtmlNodesFor?: readonly string[]; /** * Wrap text nodes in a user-specified element. * @default '' */ transWrapTextNodes?: string; /** * Optional keyPrefix that will be automatically applied to returned t function in useTranslation for example. * @default undefined */ keyPrefix?: string; /** * Unescape function * by default it unescapes some basic html entities */ unescape?(str: string): string; } /** * This interface can be augmented by users to add types to `i18next` default PluginOptions. */ export interface PluginOptions {} interface DefaultPluginOptions { /** * Options for language detection - check documentation of plugin * @default undefined */ detection?: object; /** * Options for backend - check documentation of plugin * @default undefined */ backend?: object; /** * Options for cache layer - check documentation of plugin * @default undefined */ cache?: object; /** * Options for i18n message format - check documentation of plugin * @default undefined */ i18nFormat?: object; } export interface InitOptions extends MergeBy { /** * Logs info level to console output. Helps finding issues with loading not working. * @default false */ debug?: boolean; /** * Resources to initialize with (if not using loading or not appending using addResourceBundle) * @default undefined */ resources?: Resource; /** * Allow initializing with bundled resources while using a backend to load non bundled ones. * @default false */ partialBundledLanguages?: boolean; /** * Language to use (overrides language detection) * @default undefined */ lng?: string; /** * Language to use if translations in user language are not available. * @default 'dev' */ fallbackLng?: false | FallbackLng; /** * Array of allowed languages * @default false */ supportedLngs?: false | readonly string[]; /** * If true will pass eg. en-US if finding en in supportedLngs * @default false */ nonExplicitSupportedLngs?: boolean; /** * Language codes to lookup, given set language is * 'en-US': 'all' --> ['en-US', 'en', 'dev'], * 'currentOnly' --> 'en-US', * 'languageOnly' --> 'en' * @default 'all' */ load?: 'all' | 'currentOnly' | 'languageOnly'; /** * Array of languages to preload. Important on server-side to assert translations are loaded before rendering views. * @default false */ preload?: false | readonly string[]; /** * Language will be lowercased eg. en-US --> en-us * @default false */ lowerCaseLng?: boolean; /** * Language will be lowercased EN --> en while leaving full locales like en-US * @default false */ cleanCode?: boolean; /** * String or array of namespaces to load * @default 'translation' */ ns?: string | readonly string[]; /** * Default namespace used if not passed to translation function * @default 'translation' */ defaultNS?: string | false | readonly string[]; /** * String or array of namespaces to lookup key if not found in given namespace. * @default false */ fallbackNS?: false | string | readonly string[]; /** * Calls save missing key function on backend if key not found. * @default false */ saveMissing?: boolean; /** * Calls save missing key function on backend if key not found also for plural forms. * @default false */ saveMissingPlurals?: boolean; /** * Experimental: enable to update default values using the saveMissing * (Works only if defaultValue different from translated value. * Only useful on initial development or when keeping code as source of truth not changing values outside of code. * Only supported if backend supports it already) * @default false */ updateMissing?: boolean; /** * @default 'fallback' */ saveMissingTo?: 'current' | 'all' | 'fallback'; /** * Used to not fallback to the key as default value, when using saveMissing functionality. * i.e. when using with i18next-http-backend this will result in having a key with an empty string value. * @default false */ missingKeyNoValueFallbackToKey?: boolean; /** * Used for custom missing key handling (needs saveMissing set to true!) * @default false */ missingKeyHandler?: | false | (( lngs: readonly string[], ns: string, key: string, fallbackValue: string, updateMissing: boolean, options: any, ) => void); /** * Receives a key that was not found in `t()` and returns a value, that will be returned by `t()` * @default noop */ parseMissingKeyHandler?(key: string, defaultValue?: string): any; /** * Appends namespace to missing key * @default false */ appendNamespaceToMissingKey?: boolean; /** * Gets called in case a interpolation value is undefined. This method will not be called if the value is empty string or null * @default noop */ missingInterpolationHandler?: (text: string, value: any, options: InitOptions) => any; /** * Will use 'plural' as suffix for languages only having 1 plural form, setting it to false will suffix all with numbers * @default true */ simplifyPluralSuffix?: boolean; /** * String or array of postProcessors to apply per default * @default false */ postProcess?: false | string | readonly string[]; /** * passthrough the resolved object including 'usedNS', 'usedLang' etc into options object of postprocessors as 'i18nResolved' property * @default false */ postProcessPassResolved?: boolean; /** * Allows null values as valid translation * @default true */ returnNull?: boolean; /** * Allows empty string as valid translation * @default true */ returnEmptyString?: boolean; /** * Allows objects as valid translation result * @default false */ returnObjects?: boolean; /** * Returns an object that includes information about the used language, namespace, key and value */ returnDetails?: boolean; /** * Gets called if object was passed in as key but returnObjects was set to false * @default noop */ returnedObjectHandler?(key: string, value: string, options: any): void; /** * Char, eg. '\n' that arrays will be joined by * @default false */ joinArrays?: false | string; /** * Sets defaultValue * @default args => ({ defaultValue: args[1] }) */ overloadTranslationOptionHandler?(args: string[]): TOptions; /** * @see https://www.i18next.com/interpolation.html */ interpolation?: InterpolationOptions; /** * Options for react - check documentation of plugin * @default undefined */ react?: ReactOptions; /** * Triggers resource loading in init function inside a setTimeout (default async behaviour). * Set it to false if your backend loads resources sync - that way calling i18next.t after * init is possible without relaying on the init callback. * @default true */ initImmediate?: boolean; /** * Char to separate keys * @default '.' */ keySeparator?: false | string; /** * Char to split namespace from key * @default ':' */ nsSeparator?: false | string; /** * Char to split plural from key * @default '_' */ pluralSeparator?: string; /** * Char to split context from key * @default '_' */ contextSeparator?: string; /** * Prefixes the namespace to the returned key when using `cimode` * @default false */ appendNamespaceToCIMode?: boolean; /** * Compatibility JSON version * @default 'v4' */ compatibilityJSON?: 'v1' | 'v2' | 'v3' | 'v4'; /** * Options for https://github.com/locize/locize-lastused * @default undefined */ locizeLastUsed?: { /** * The id of your locize project */ projectId: string; /** * An api key if you want to send missing keys */ apiKey?: string; /** * The reference language of your project * @default 'en' */ referenceLng?: string; /** * Version * @default 'latest' */ version?: string; /** * Debounce interval to send data in milliseconds * @default 90000 */ debounceSubmit?: number; /** * Hostnames that are allowed to send last used data. * Please keep those to your local system, staging, test servers (not production) * @default ['localhost'] */ allowedHosts?: readonly string[]; }; /** * Automatically lookup for a flat key if a nested key is not found an vice-versa * @default true */ ignoreJSONStructure?: boolean; /** * Limit parallelism of calls to backend * This is needed to prevent trying to open thousands of * sockets or file descriptors, which can cause failures * and actually make the entire process take longer. * @default 10 */ maxParallelReads?: number; /** * The maximum number of retries to perform. * Note that retries are only performed when a request has no response * and throws an error. * The default value is used if value is set below 0. * @default 5 */ maxRetries?: number; /** * Set how long to wait, in milliseconds, betweeen retries of failed requests. * This number is compounded by a factor of 2 for subsequent retry. * The default value is used if value is set below 1ms. * @default 350 */ retryTimeout?: number; } export interface TOptionsBase { /** * Default value to return if a translation was not found */ defaultValue?: any; /** * Count value used for plurals */ count?: number; /** * Used for contexts (eg. male\female) */ context?: any; /** * Object with vars for interpolation - or put them directly in options */ replace?: any; /** * Override language to use */ lng?: string; /** * Override languages to use */ lngs?: readonly string[]; /** * Override language to lookup key if not found see fallbacks for details */ fallbackLng?: FallbackLng; /** * Override namespaces (string or array) */ ns?: string | readonly string[]; /** * Override char to separate keys */ keySeparator?: false | string; /** * Override char to split namespace from key */ nsSeparator?: false | string; /** * Accessing an object not a translation string (can be set globally too) */ returnObjects?: boolean; /** * Returns an object that includes information about the used language, namespace, key and value */ returnDetails?: boolean; /** * Char, eg. '\n' that arrays will be joined by (can be set globally too) */ joinArrays?: string; /** * String or array of postProcessors to apply see interval plurals as a sample */ postProcess?: string | readonly string[]; /** * Override interpolation options */ interpolation?: InterpolationOptions; } /** * indexer that is open to any value */ export type StringMap = { [key: string]: any }; /** * Options that allow open ended values for interpolation unless type is provided. */ export type TOptions = TOptionsBase & TInterpolationMap; export type Callback = (error: any, t: TFunction) => void; /** * Uses similar args as the t function and returns true if a key exists. */ export interface ExistsFunction< TKeys extends string = string, TInterpolationMap extends object = StringMap, > { (key: TKeys | TKeys[], options?: TOptions): boolean; } export interface WithT { // Expose parameterized t in the i18next interface hierarchy t: TFunction; } /** * Object returned from t() function when passed returnDetails: true option. */ export type TFunctionDetailedResult = { /** * The plain used key */ usedKey: string; /** * The translation result. */ res: T; /** * The key with context / plural */ exactUsedKey: string; /** * The used language for this translation. */ usedLng: string; /** * The used namespace for this translation. */ usedNS: string; }; export type TFunctionResult = | string | object | TFunctionDetailedResult | Array | undefined | null; export type TFunctionKeys = string | TemplateStringsArray; export interface TFunction { // basic usage < TResult extends TFunctionResult = string, TKeys extends TFunctionKeys = string, TInterpolationMap extends object = StringMap, >( key: TKeys | TKeys[], ): TResult; < TResult extends TFunctionResult = TFunctionDetailedResult, TKeys extends TFunctionKeys = string, TInterpolationMap extends object = StringMap, >( key: TKeys | TKeys[], options?: TOptions & { returnDetails: true; returnObjects: true }, ): TResult; < TResult extends TFunctionResult = TFunctionDetailedResult, TKeys extends TFunctionKeys = string, TInterpolationMap extends object = StringMap, >( key: TKeys | TKeys[], options?: TOptions & { returnDetails: true }, ): TResult; < TResult extends TFunctionResult = object, TKeys extends TFunctionKeys = string, TInterpolationMap extends object = StringMap, >( key: TKeys | TKeys[], options?: TOptions & { returnObjects: true }, ): TResult; < TResult extends TFunctionResult = string, TKeys extends TFunctionKeys = string, TInterpolationMap extends object = StringMap, >( key: TKeys | TKeys[], options?: TOptions | string, ): TResult; // overloaded usage < TResult extends TFunctionResult = string, TKeys extends TFunctionKeys = string, TInterpolationMap extends object = StringMap, >( key: TKeys | TKeys[], defaultValue?: string, options?: TOptions | string, ): TResult; } export interface Resource { [language: string]: ResourceLanguage; } export interface ResourceLanguage { [namespace: string]: ResourceKey; } export type ResourceKey = | string | { [key: string]: any; }; export interface Interpolator { init(options: InterpolationOptions, reset: boolean): undefined; reset(): undefined; resetRegExp(): undefined; interpolate(str: string, data: object, lng: string, options: InterpolationOptions): string; nest(str: string, fc: (...args: any[]) => any, options: InterpolationOptions): string; } export class ResourceStore { constructor(data: Resource, options: InitOptions); public data: Resource; public options: InitOptions; /** * Gets fired when resources got added or removed */ on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void; /** * Remove event listener * removes all callback when callback not specified */ off(event: 'added' | 'removed', callback?: (lng: string, ns: string) => void): void; } export interface Formatter { init(services: Services, i18nextOptions: InitOptions): void; add(name: string, fc: (value: any, lng: string | undefined, options: any) => string): void; format: FormatFunction; } export interface Services { backendConnector: any; i18nFormat: any; interpolator: Interpolator; languageDetector: any; languageUtils: any; logger: any; pluralResolver: any; resourceStore: ResourceStore; formatter?: Formatter; } export type ModuleType = | 'backend' | 'logger' | 'languageDetector' | 'postProcessor' | 'i18nFormat' | 'formatter' | '3rdParty'; export interface Module { type: ModuleType; } export type CallbackError = Error | null | undefined; export type ReadCallback = ( err: CallbackError, data: ResourceKey | boolean | null | undefined, ) => void; export type MultiReadCallback = (err: CallbackError, data: Resource | null | undefined) => void; /** * Used to load data for i18next. * Can be provided as a singleton or as a prototype constructor (preferred for supporting multiple instances of i18next). * For singleton set property `type` to `'backend'` For a prototype constructor set static property. */ export interface BackendModule extends Module { type: 'backend'; init(services: Services, backendOptions: TOptions, i18nextOptions: InitOptions): void; read(language: string, namespace: string, callback: ReadCallback): void; /** Save the missing translation */ create?( languages: readonly string[], namespace: string, key: string, fallbackValue: string, ): void; /** Load multiple languages and namespaces. For backends supporting multiple resources loading */ readMulti?( languages: readonly string[], namespaces: readonly string[], callback: MultiReadCallback, ): void; /** Store the translation. For backends acting as cache layer */ save?(language: string, namespace: string, data: ResourceLanguage): void; } /** * Used to detect language in user land. * Can be provided as a singleton or as a prototype constructor (preferred for supporting multiple instances of i18next). * For singleton set property `type` to `'languageDetector'` For a prototype constructor set static property. */ export interface LanguageDetectorModule extends Module { type: 'languageDetector'; init(services: Services, detectorOptions: object, i18nextOptions: InitOptions): void; /** Must return detected language */ detect(): string | readonly string[] | undefined; cacheUserLanguage(lng: string): void; } /** * Used to detect language in user land. * Can be provided as a singleton or as a prototype constructor (preferred for supporting multiple instances of i18next). * For singleton set property `type` to `'languageDetector'` For a prototype constructor set static property. */ export interface LanguageDetectorAsyncModule extends Module { type: 'languageDetector'; /** Set to true to enable async detection */ async: true; init(services: Services, detectorOptions: object, i18nextOptions: InitOptions): void; /** Must call callback passing detected language */ detect(callback: (lng: string | readonly string[] | undefined) => void): void; cacheUserLanguage(lng: string): void; } /** * Used to extend or manipulate the translated values before returning them in `t` function. * Need to be a singleton object. */ export interface PostProcessorModule extends Module { /** Unique name */ name: string; type: 'postProcessor'; process(value: string, key: string, options: TOptions, translator: any): string; } /** * Override the built-in console logger. * Do not need to be a prototype function. */ export interface LoggerModule extends Module { type: 'logger'; log(...args: any[]): void; warn(...args: any[]): void; error(...args: any[]): void; } export interface I18nFormatModule extends Module { type: 'i18nFormat'; } export interface FormatterModule extends Module, Formatter { type: 'formatter'; } export interface ThirdPartyModule extends Module { type: '3rdParty'; init(i18next: i18n): void; } export interface Modules { backend?: BackendModule; logger?: LoggerModule; languageDetector?: LanguageDetectorModule | LanguageDetectorAsyncModule; i18nFormat?: I18nFormatModule; formatter?: FormatterModule; external: ThirdPartyModule[]; } // helper to identify class https://stackoverflow.com/a/45983481/2363935 export interface Newable { new (...args: any[]): T; } export interface NewableModule extends Newable { type: T['type']; } export interface i18n { // Expose parameterized t in the i18next interface hierarchy t: TFunction; /** * The default of the i18next module is an i18next instance ready to be initialized by calling init. * You can create additional instances using the createInstance function. * * @param options - Initial options. * @param callback - will be called after all translations were loaded or with an error when failed (in case of using a backend). */ init(callback?: Callback): Promise; init(options: InitOptions, callback?: Callback): Promise; loadResources(callback?: (err: any) => void): void; /** * The use function is there to load additional plugins to i18next. * For available module see the plugins page and don't forget to read the documentation of the plugin. * * @param module Accepts a class or object */ use(module: T | NewableModule | Newable): this; /** * List of modules used */ modules: Modules; /** * Internal container for all used plugins and implementation details like languageUtils, pluralResolvers, etc. */ services: Services; /** * Internal container for translation resources */ store: ResourceStore; /** * Uses similar args as the t function and returns true if a key exists. */ exists: ExistsFunction; /** * Returns a resource data by language. */ getDataByLanguage(lng: string): { [key: string]: { [key: string]: string } } | undefined; /** * Returns a t function that defaults to given language or namespace. * Both params could be arrays of languages or namespaces and will be treated as fallbacks in that case. * 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. * * Accepts optional keyPrefix that will be automatically applied to returned t function. */ getFixedT( lng: string | readonly string[], ns?: string | readonly string[], keyPrefix?: string, ): TFunction; getFixedT(lng: null, ns: string | readonly string[] | null, keyPrefix?: string): TFunction; /** * Changes the language. The callback will be called as soon translations were loaded or an error occurs while loading. * HINT: For easy testing - setting lng to 'cimode' will set t function to always return the key. */ changeLanguage(lng?: string, callback?: Callback): Promise; /** * Is set to the current detected or set language. * If you need the primary used language depending on your configuration (supportedLngs, load) you will prefer using i18next.languages[0]. */ language: string; /** * Is set to an array of language-codes that will be used it order to lookup the translation value. */ languages: readonly string[]; /** * Is set to the current resolved language. * It can be used as primary used language, for example in a language switcher. */ resolvedLanguage: string; /** * Loads additional namespaces not defined in init options. */ loadNamespaces(ns: string | readonly string[], callback?: Callback): Promise; /** * Loads additional languages not defined in init options (preload). */ loadLanguages(lngs: string | readonly string[], callback?: Callback): Promise; /** * 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. */ reloadResources( lngs?: string | readonly string[], ns?: string | readonly string[], callback?: () => void, ): Promise; reloadResources(lngs: null, ns: string | readonly string[], callback?: () => void): Promise; /** * Changes the default namespace. */ setDefaultNamespace(ns: string): void; /** * Checks if a namespace has been loaded. */ hasLoadedNamespace(ns: string, options?: Pick): boolean; /** * Returns rtl or ltr depending on languages read direction. */ dir(lng?: string): 'ltr' | 'rtl'; /** * Exposes interpolation.format function added on init. */ format: FormatFunction; /** * Will return a new i18next instance. * Please read the options page for details on configuration options. * Providing a callback will automatically call init. * The callback will be called after all translations were loaded or with an error when failed (in case of using a backend). */ createInstance(options?: InitOptions, callback?: Callback): i18n; /** * Creates a clone of the current instance. Shares store, plugins and initial configuration. * Can be used to create an instance sharing storage but being independent on set language or namespaces. */ cloneInstance(options?: InitOptions, callback?: Callback): i18n; /** * Gets fired after initialization. */ on(event: 'initialized', callback: (options: InitOptions) => void): void; /** * Gets fired on loaded resources. */ on( event: 'loaded', callback: (loaded: { [language: string]: { [namespace: string]: boolean } }) => void, ): void; /** * Gets fired if loading resources failed. */ on(event: 'failedLoading', callback: (lng: string, ns: string, msg: string) => void): void; /** * Gets fired on accessing a key not existing. */ on( event: 'missingKey', callback: (lngs: readonly string[], namespace: string, key: string, res: string) => void, ): void; /** * Gets fired when resources got added or removed. */ on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void; /** * Gets fired when changeLanguage got called. */ on(event: 'languageChanged', callback: (lng: string) => void): void; /** * Event listener */ on(event: string, listener: (...args: any[]) => void): void; /** * Remove event listener * removes all callback when callback not specified */ off(event: string, listener?: (...args: any[]) => void): void; /** * Gets one value by given key. */ getResource( lng: string, ns: string, key: string, options?: Pick, ): any; /** * Adds one key/value. */ addResource( lng: string, ns: string, key: string, value: string, options?: { keySeparator?: string; silent?: boolean }, ): i18n; /** * Adds multiple key/values. */ addResources(lng: string, ns: string, resources: any): i18n; /** * Adds a complete bundle. * Setting deep param to true will extend existing translations in that file. * Setting overwrite to true it will overwrite existing translations in that file. */ addResourceBundle( lng: string, ns: string, resources: any, deep?: boolean, overwrite?: boolean, ): i18n; /** * Checks if a resource bundle exists. */ hasResourceBundle(lng: string, ns: string): boolean; /** * Returns a resource bundle. */ getResourceBundle(lng: string, ns: string): any; /** * Removes an existing bundle. */ removeResourceBundle(lng: string, ns: string): i18n; /** * Current options */ options: InitOptions; /** * Is initialized */ isInitialized: boolean; /** * Emit event */ emit(eventName: string): void; } declare const i18next: i18n; export default i18next; export const createInstance: i18n['createInstance']; export const init: i18n['init']; export const loadResources: i18n['loadResources']; export const reloadResources: i18n['reloadResources']; export const use: i18n['use']; export const changeLanguage: i18n['changeLanguage']; export const getFixedT: i18n['getFixedT']; export const t: i18n['t']; export const exists: i18n['exists']; export const setDefaultNamespace: i18n['setDefaultNamespace']; export const hasLoadedNamespace: i18n['hasLoadedNamespace']; export const loadNamespaces: i18n['loadNamespaces']; export const loadLanguages: i18n['loadLanguages'];