i18next

constructor

constructor(data: Resource, options: InitOptions<object>);

property data

data: Resource;

property options

options: InitOptions<object>;

method off

off: (
    event: 'added' | 'removed',
    callback?: (lng: string, ns: string) => void
) => void;

• Remove event listener removes all callback when callback not specified

method on

on: (
    event: 'added' | 'removed',
    callback: (lng: string, ns: string) => void
) => void;

• Gets fired when resources got added or removed

property type

type: 'backend';

method create

create: (
    languages: readonly string[],
    namespace: string,
    key: string,
    fallbackValue: string
) => void;

• Save the missing translation

method init

init: (
    services: Services,
    backendOptions: Options,
    i18nextOptions: InitOptions
) => void;

method read

read: (language: string, namespace: string, callback: ReadCallback) => void;

method readMulti

readMulti: (
    languages: readonly string[],
    namespaces: readonly string[],
    callback: MultiReadCallback
) => void;

• Load multiple languages and namespaces. For backends supporting multiple resources loading

method save

save: (language: string, namespace: string, data: ResourceLanguage) => void;

• Store the translation. For backends acting as cache layer

property $TFunctionBrand

$TFunctionBrand: $IsResourcesDefined extends true
    ? `${Ns extends readonly any[] ? Ns[0] : Ns}`
    : never;

property forkResourceStore

forkResourceStore?: boolean;

• Will create a new instance of the resource store and import the existing translation resources. This way it will not shared the resource store instance. false

call signature

(key: TKeys | TKeys[], options?: TOptions<TInterpolationMap>): boolean;

index signature

[language: string]: readonly string[];

property format

format: FormatFunction;

method add

add: (
    name: string,
    fc: (value: any, lng: string | undefined, options: any) => string
) => void;

method addCached

addCached: (
    name: string,
    fc: (lng: string | undefined, options: any) => (value: any) => string
) => void;

method init

init: (services: Services, i18nextOptions: InitOptions) => void;

property type

type: 'formatter';

property exists

exists: ExistsFunction;

• Uses similar args as the t function and returns true if a key exists.

property format

format: FormatFunction;

• Exposes interpolation.format function added on init.

property initializedLanguageOnce

initializedLanguageOnce: boolean;

• Language was initialized

property initializedStoreOnce

initializedStoreOnce: boolean;

• Store was initialized

property isInitialized

isInitialized: boolean;

• Is initialized

property isInitializing

isInitializing: boolean;

• Is initializing

property language

language: string;

• 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].

property languages

languages: readonly string[];

• Is set to an array of language-codes that will be used it order to lookup the translation value.

property modules

modules: Modules;

• List of modules used

property options

options: InitOptions;

• Current options

property resolvedLanguage

resolvedLanguage?: string;

• Is set to the current resolved language. It can be used as primary used language, for example in a language switcher.

property services

services: Services;

• Internal container for all used plugins and implementation details like languageUtils, pluralResolvers, etc.

property store

store: ResourceStore;

• Internal container for translation resources

property t

t: TFunction<
    [
        ...$NormalizeIntoArray<DefaultNamespace>,
        ...Exclude<
            FlatNamespace,
            InferArrayValuesElseReturnType<DefaultNamespace>
        >[]
    ]
>;

method addResource

addResource: (
    lng: string,
    ns: string,
    key: string,
    value: string,
    options?: { keySeparator?: string; silent?: boolean }
) => i18n;

• Adds one key/value.

method addResourceBundle

addResourceBundle: (
    lng: string,
    ns: string,
    resources: any,
    deep?: boolean,
    overwrite?: boolean
) => 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.

method addResources

addResources: (lng: string, ns: string, resources: any) => i18n;

• Adds multiple key/values.

method changeLanguage

changeLanguage: (lng?: string, callback?: Callback) => Promise<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.

method cloneInstance

cloneInstance: (options?: CloneOptions, 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.

method createInstance

createInstance: (options?: InitOptions, callback?: Callback) => i18n;

• 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).

method dir

dir: (lng?: string) => 'ltr' | 'rtl';

• Returns rtl or ltr depending on languages read direction.

method emit

emit: (eventName: string, ...args: any[]) => void;

• Emit event

method getDataByLanguage

getDataByLanguage: (lng: string) => { [key: string]: { [key: string]: string } };

• Returns a resource data by language.

method getFixedT

getFixedT: <
    Ns extends Namespace<string> = 'translation',
    TKPrefix extends string = undefined,
    ActualNs extends Namespace<string> = Ns extends null ? 'translation' : Ns
>(
    ...args:
        | [lng: string | readonly string[], ns?: Ns, keyPrefix?: TKPrefix]
        | [lng: null, ns: Ns, keyPrefix?: TKPrefix]
) => TFunction<ActualNs, TKPrefix>;

• 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.

method getResource

getResource: (
    lng: string,
    ns: string,
    key: string,
    options?: Pick<InitOptions, 'keySeparator' | 'ignoreJSONStructure'>
) => any;

• Gets one value by given key.

method getResourceBundle

getResourceBundle: (lng: string, ns: string) => any;

• Returns a resource bundle.

method hasLoadedNamespace

hasLoadedNamespace: (
    ns: string | readonly string[],
    options?: {
        lng?: string | readonly string[];
        fallbackLng?: InitOptions['fallbackLng'];
        precheck?: (
            i18n: i18n,
            loadNotPending: (
                lng: string | readonly string[],
                ns: string | readonly string[]
            ) => boolean
        ) => boolean | undefined;
    }
) => boolean;

• Checks if namespace has loaded yet. i.e. used by react-i18next

method hasResourceBundle

hasResourceBundle: (lng: string, ns: string) => boolean;

• Checks if a resource bundle exists.

method init

init: {
    (callback?: Callback): Promise<TFunction>;
    <T>(options: InitOptions<T>, callback?: Callback): Promise<
        TFunction<'translation', undefined>
    >;
};

• 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.

  Parameter options

  Initial options.

  Parameter callback

  will be called after all translations were loaded or with an error when failed (in case of using a backend).

method loadLanguages

loadLanguages: (
    lngs: string | readonly string[],
    callback?: Callback
) => Promise<void>;

• Loads additional languages not defined in init options (preload).

method loadNamespaces

loadNamespaces: (
    ns: string | readonly string[],
    callback?: Callback
) => Promise<void>;

• Loads additional namespaces not defined in init options.

method loadResources

loadResources: (callback?: (err: any) => void) => void;

method off

off: (event: string, listener?: (...args: any[]) => void) => void;

• Remove event listener removes all callback when callback not specified

method on

on: {
    (event: 'initialized', callback: (options: InitOptions) => void): void;
    (
        event: 'loaded',
        callback: (loaded: {
            [language: string]: { [namespace: string]: boolean };
        }) => void
    ): void;
    (
        event: 'failedLoading',
        callback: (lng: string, ns: string, msg: string) => void
    ): void;
    (
        event: 'missingKey',
        callback: (
            lngs: readonly string[],
            namespace: string,
            key: string,
            res: string
        ) => void
    ): void;
    (event: 'languageChanged', callback: (lng: string) => void): void;
    (event: string, listener: (...args: any[]) => void): void;
};

• Gets fired after initialization.

• Gets fired on loaded resources.

• Gets fired if loading resources failed.

• Gets fired on accessing a key not existing.

• Gets fired when changeLanguage got called.

• Event listener

method reloadResources

reloadResources: {
    (
        lngs?: string | readonly string[],
        ns?: string | readonly string[],
        callback?: () => void
    ): Promise<void>;
    (
        lngs: null,
        ns: string | readonly string[],
        callback?: () => void
    ): Promise<void>;
};

• 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.

method removeResourceBundle

removeResourceBundle: (lng: string, ns: string) => i18n;

• Removes an existing bundle.

method setDefaultNamespace

setDefaultNamespace: (ns: string | readonly string[]) => void;

• Changes the default namespace.

method toJSON

toJSON: () => {
    options: InitOptions;
    store: ResourceStore;
    language: string;
    languages: readonly string[];
    resolvedLanguage?: string;
};

• Returns a JSON representation of the i18next instance for serialization.

method use

use: <T extends Module>(module: T | NewableModule<T> | Newable<T>) => this;

• 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.

  Parameter module

  Accepts a class or object

property type

type: 'i18nFormat';

property appendNamespaceToCIMode

appendNamespaceToCIMode?: boolean;

• Prefixes the namespace to the returned key when using cimode false

property appendNamespaceToMissingKey

appendNamespaceToMissingKey?: boolean;

• Appends namespace to missing key false

property cacheInBuiltFormats

cacheInBuiltFormats?: boolean;

• Initializes the internal formatter for the in-built formats as cached version. Can be set to false for this type of issues: https://github.com/i18next/i18next/issues/2227 true

property cleanCode

cleanCode?: boolean;

• Language will be lowercased EN --> en while leaving full locales like en-US false

property compatibilityJSON

compatibilityJSON?: 'v4';

• Compatibility JSON version only v4 is available and supported by typescript 'v4'

property contextSeparator

contextSeparator?: string;

• Char to split context from key '_'

property debug

debug?: boolean;

• Logs info level to console output. Helps finding issues with loading not working. false

property defaultNS

defaultNS?: string | false | readonly string[];

• Default namespace used if not passed to translation function 'translation'

property fallbackLng

fallbackLng?: false | FallbackLng;

• Language to use if translations in user language are not available. 'dev'

property fallbackNS

fallbackNS?: false | string | readonly string[];

• String or array of namespaces to lookup key if not found in given namespace. false

property ignoreJSONStructure

ignoreJSONStructure?: boolean;

• Automatically lookup for a flat key if a nested key is not found an vice-versa true

property initAsync

initAsync?: boolean;

• 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. true

property initImmediate

initImmediate?: boolean;

• Deprecated

  Use initAsync instead.

property interpolation

interpolation?: InterpolationOptions;

• See Also

  • https://www.i18next.com/translation-function/interpolation

property joinArrays

joinArrays?: false | string;

• Char, eg. '\n' that arrays will be joined by false

property keySeparator

keySeparator?: false | string;

• Char to separate keys '.'

property lng

lng?: string;

• Language to use (overrides language detection) undefined

property load

load?: 'all' | 'currentOnly' | 'languageOnly';

• Language codes to lookup, given set language is 'en-US': 'all' --> ['en-US', 'en', 'dev'], 'currentOnly' --> 'en-US', 'languageOnly' --> 'en' 'all'

property locizeLastUsed

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[];
};

• Options for https://github.com/locize/locize-lastused undefined

property lowerCaseLng

lowerCaseLng?: boolean;

• Language will be lowercased eg. en-US --> en-us false

property maxParallelReads

maxParallelReads?: number;

• 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. 10

property maxRetries

maxRetries?: 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. 5

property missingInterpolationHandler

missingInterpolationHandler?: (
    text: string,
    value: any,
    options: InitOptions
) => any;

• Gets called in case a interpolation value is undefined. This method will not be called if the value is empty string or null noop

property missingKeyHandler

missingKeyHandler?:
    | false
    | ((
          lngs: readonly string[],
          ns: string,
          key: string,
          fallbackValue: string,
          updateMissing: boolean,
          options: any
      ) => void);

• Used for custom missing key handling (needs saveMissing set to true!) false

property missingKeyNoValueFallbackToKey

missingKeyNoValueFallbackToKey?: boolean;

• 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. false

property nonExplicitSupportedLngs

nonExplicitSupportedLngs?: boolean;

• If true will pass eg. en-US if finding en in supportedLngs false

property ns

ns?: string | readonly string[];

• String or array of namespaces to load 'translation'

property nsSeparator

nsSeparator?: false | string;

• Char to split namespace from key ':'

property partialBundledLanguages

partialBundledLanguages?: boolean;

• Allow initializing with bundled resources while using a backend to load non bundled ones. false

property pluralSeparator

pluralSeparator?: string;

• Char to split plural from key '_'

property postProcess

postProcess?: false | string | readonly string[];

• String or array of postProcessors to apply per default false

property postProcessPassResolved

postProcessPassResolved?: boolean;

• passthrough the resolved object including 'usedNS', 'usedLang' etc into options object of postprocessors as 'i18nResolved' property false

property preload

preload?: false | readonly string[];

• Array of languages to preload. Important on server-side to assert translations are loaded before rendering views. false

property react

react?: ReactOptions;

• Options for react - check documentation of plugin undefined

property resources

resources?: Resource;

• Resources to initialize with (if not using loading or not appending using addResourceBundle) undefined

property retryTimeout

retryTimeout?: number;

• Set how long to wait, in milliseconds, between 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. 350

property returnDetails

returnDetails?: boolean;

• Returns an object that includes information about the used language, namespace, key and value false

property returnEmptyString

returnEmptyString?: boolean;

• Allows empty string as valid translation true

property returnNull

returnNull?: boolean;

• Allows null values as valid translation false

property returnObjects

returnObjects?: boolean;

• Allows objects as valid translation result false

property saveMissing

saveMissing?: boolean;

• Calls save missing key function on backend if key not found. false

property saveMissingPlurals

saveMissingPlurals?: boolean;

• Calls save missing key function on backend if key not found also for plural forms. false

property saveMissingTo

saveMissingTo?: 'current' | 'all' | 'fallback';

• 'fallback'

property showSupportNotice

showSupportNotice?: boolean;

• Show support notice in console during initialization. true

property simplifyPluralSuffix

simplifyPluralSuffix?: boolean;

• Will use 'plural' as suffix for languages only having 1 plural form, setting it to false will suffix all with numbers true

property supportedLngs

supportedLngs?: false | readonly string[];

• Array of allowed languages false

property updateMissing

updateMissing?: 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) false

method overloadTranslationOptionHandler

overloadTranslationOptionHandler: (args: string[]) => TOptions;

• Sets defaultValue args => ({ defaultValue: args[1] })

method parseMissingKeyHandler

parseMissingKeyHandler: (
    key: string,
    defaultValue?: string,
    options?: any
) => any;

• Receives a key that was not found in t() and returns a value, that will be returned by t() noop

method returnedObjectHandler

returnedObjectHandler: (key: string, value: string, options: any) => void;

• Gets called if object was passed in as key but returnObjects was set to false noop

property alwaysFormat

alwaysFormat?: boolean;

• Always format interpolated values. false

property defaultVariables

defaultVariables?: { [index: string]: any };

• Global variables to use in interpolation replacements undefined

property escapeValue

escapeValue?: boolean;

• Escape passed in values to avoid xss injection true

property format

format?: FormatFunction;

• Format function see formatting for details noop

property formatSeparator

formatSeparator?: string;

• Used to separate format from interpolation value ','

property maxReplaces

maxReplaces?: number;

• After how many interpolation runs to break out before throwing a stack overflow 1000

property nestingOptionsSeparator

nestingOptionsSeparator?: string;

• Separates options from key ','

property nestingPrefix

nestingPrefix?: string;

• Prefix for nesting '$t('

property nestingPrefixEscaped

nestingPrefixEscaped?: string;

• Escaped prefix for nesting (regexSafe) undefined

property nestingSuffix

nestingSuffix?: string;

• Suffix for nesting ')'

property nestingSuffixEscaped

nestingSuffixEscaped?: string;

• Escaped suffix for nesting (regexSafe) undefined

property prefix

prefix?: string;

• Prefix for interpolation '{{'

property prefixEscaped

prefixEscaped?: string;

• Escaped prefix for interpolation (regexSafe) undefined

property skipOnVariables

skipOnVariables?: boolean;

• If true, it will skip to interpolate the variables true

property suffix

suffix?: string;

• Suffix for interpolation '}}'

property suffixEscaped

suffixEscaped?: string;

• Escaped suffix for interpolation (regexSafe) undefined

property unescapePrefix

unescapePrefix?: string;

• Prefix to unescaped mode '-'

property unescapeSuffix

unescapeSuffix?: string;

• Suffix to unescaped mode undefined

property useRawValueToEscape

useRawValueToEscape?: 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 false

method escape

escape: (str: string) => string;

• Escape function str => str

method init

init: (options: InterpolationOptions, reset: boolean) => undefined;

method interpolate

interpolate: (
    str: string,
    data: object,
    lng: string,
    options: InterpolationOptions
) => string;

method nest

nest: (
    str: string,
    fc: (...args: any[]) => any,
    options: InterpolationOptions
) => string;

method reset

reset: () => undefined;

method resetRegExp

resetRegExp: () => undefined;

property async

async: true;

• Set to true to enable async detection

property type

type: 'languageDetector';

method cacheUserLanguage

cacheUserLanguage: (lng: string) => void | Promise<void>;

method detect

detect: (
    callback: (lng: string | readonly string[] | undefined) => void | undefined
) => void | Promise<string | readonly string[] | undefined>;

• Must call callback passing detected language or return a Promise

method init

init: (
    services: Services,
    detectorOptions: object,
    i18nextOptions: InitOptions
) => void;

property type

type: 'languageDetector';

method cacheUserLanguage

cacheUserLanguage: (lng: string) => void;

method detect

detect: () => string | readonly string[] | undefined;