Configuration Options

i18next.init(options, callback)

All options for calling init() or createInstance().

Logging

optiondefaultdescription

debug

false

logs info level to console output. Helps finding issues with loading not working.

Languages, namespaces, resources

optiondefaultdescription

resources

undefined

resources to initialize with (if not using a backend plugin or not using addResourceBundle)

lng

undefined

language to use (overrides language detection). If set to 'cimode' the output text will be the key. Make sure you use the 'en-US' format, instead of underscores or similar.

appendNamespaceToCIMode

false

prefixes the namespace to the returned key when using lng: 'cimode'

fallbackLng

'dev'

language to use if translations in user language are not available. Setting it explicitly to false will not trigger to load the fallbackLng at all. See the Fallback docs.

supportedLngs

false

array of allowed languages

nonExplicitSupportedLngs

false

if true, will consider variants as supported when the main language is. E.g. en-US will be valid if en is in supportedLngs.

If true and using a backend like i18next-http-backend, this can cause some request errors.

load

'all'

strategy to define which language codes to lookup. Example: given set language is en-US: - 'all'['en-US', 'en', 'dev'] - 'currentOnly''en-US' - 'languageOnly''en'

preload

false

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

lowerCaseLng

false

locale will be fully lowercased; e.g. en-USen-us

cleanCode

false

main language will be lowercased; e.g. ENen, while leaving full locales like en-US

ns

'translation' (setting it to an empty array [] will not load any namespaces on init)

string or array of namespaces to load

defaultNS

'translation'

(if a ns option and no defaultNS option is defined, the first namespace is used as defaultNS option) (setting it to false or an empty array [] will disable this fallback behaviour)

default namespace used if not passed to the translation function

fallbackNS

false

string or array of namespaces to lookup key if not found in given namespace. See NS fallback docs.

partialBundledLanguages

false

allows some resources to be set on initialization while others can be loaded using a backend connector

Missing keys

The missing keys functionality of i18next is very useful during development. If enabled (saveMissing: true), it collects the used i18n keys that are not yet part of your translation resources and tries to save them to the used backend (a backend plugin that offers the create function is necessary for this).

In this video you can see how the saveMissing functionality is used.

optiondefaultdescription

saveMissing

false

calls save missing key function on backend if key not found (only for backends that supports the create function, i.e. i18next-fs-backend, i18next-http-backend, i18next-locize-backend etc.)

updateMissing

false

experimental: enable to update default values using the saveMissing (Works only if defaultValue is 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)

saveMissingTo

'fallback'

'current' or 'all' By default it uses the configured fallback language to save the missing keys to. 'current' will use the current used/detected language (i18next.language) and 'all' will save it to all languages included in i18next.languages.

saveMissingPlurals

true

will save all plural forms instead of only singular if t was called for plurals

missingKeyHandler

false

function(lngs, ns, key, fallbackValue, updateMissing, options) { } used for custom missing key handling (needs saveMissing set to true!)

The options are an internal value container similar to the t() options. The fallbackValue argument is the value that is shown if the translations are not provided (usually the defaultValue). The updateMissing argument is set to true if the missingKeyHandler function was invoked because of the updateMissing functionality.

parseMissingKeyHandler

noop

function(key, defaultValue) { // return value to display }

appendNamespaceToMissingKey

false

appends namespace to missing key

missingInterpolationHandler

noop

function(text, value) { return 'stringWithAlternativeValueOrUndefined' } gets called in case a interpolation value is undefined. This method will not be called if the value is an empty string or null

missingKeyNoValueFallbackToKey

false

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.

Translation defaults

optiondefaultdescription

postProcess

false

string or array of postProcessors to apply per default

returnNull

false

allows null values as valid translation

returnEmptyString

true

allows empty string as valid translation

returnObjects

false

allows objects as valid translation result

returnDetails

false

returns an object that includes information about the used language, namespace, key and value

returnedObjectHandler

noop

function(key, value, options) {} gets called if object was passed in as key but returnObjects was set to false

joinArrays

false

char that arrays will be joined by; e.g. ", "

overloadTranslationOptionHandler

function(args) { return { defaultValue: args[1] }; };

default: sets defaultValue

interpolation

skipInterpolation

false

Allow translate function to skip interpolation and return raw values instead

simplifyPluralSuffix

(used in format < format v4)

true

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

Plugin options

optiondefaultdescription

detection

undefined

options for language detection - check docs

backend

undefined

options for backend - check docs

cache

undefined

options for a cache layer in backends - check docs

Others

optiondefaultdescription

initAsync

true

triggers resource loading in init() inside a setTimeout (default async behaviour). Set it to false if your backend loads resources synchronously - that way, calling i18next.t() after init() is possible without relying on the initialization callback. This option only works for sync (blocking) loading backend, like i18next-fs-backend!

keySeparator

'.'

char to separate keys. If working with a flat JSON, it's recommended to set this to false.

nsSeparator

':'

char to split namespace from key

pluralSeparator

'_'

char to split plural from key

contextSeparator

'_'

char to split context from key

ignoreJSONStructure

true

if a key is not found as nested key, it will try to lookup as flat key

maxParallelReads

10

limits parallel reads to the backend to prevent opening up to thousands of sockets or file descriptors at the same time, leading to EMFILE errors if ulimit -n is exceeded (debug: true must be set to see them). limiting parallelism usually makes loading all items substantially faster than allowing all reads to start before any have finished.

initImmediate

Sample using initImmediate when using a backend plugin allowing sync (blocking) loads.

This option only works for sync (blocking) loading backend, like i18next-fs-backend!

import i18next from 'i18next';
import Backend from 'i18next-fs-backend';

// not working
i18next
  .use(Backend)
  .init();

i18next.t('key'); // -> will not return value as init was run async

/*
execution order of function calls
- init
- t
- loadResources (as called inside timeout)
*/

// working
i18next
  .use(Backend)
  .init({ initImmediate: false });

i18next.t('key'); // -> will return value

/*
execution order of function calls
- init
- loadResources (as called without timeout)
- t
*/

Last updated