Configuration Options

i18next.init(options, callback)
All options for calling init() or createInstance().
Logging
option
default
description
debug
false
logs info level to console output. Helps finding issues with loading not working.
Languages, namespaces, resources
option
default
description
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.​
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-US ⇒ en-us
cleanCode
false
main language will be lowercased; e.g. EN ⇒ en, while leaving full locales like en-US
ns
'translation'
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
option
default
description
saveMissing
false
calls save missing key function on backend if key not found
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.
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
option
default
description
postProcess
false
string or array of postProcessors to apply per default
returnNull
true
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
​{...}​
see 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
option
default
description
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
option
default
description
initImmediate
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 and i18next-sync-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
appendNamespaceToCIMode
false
prefixes the namespace to the returned key when using lng: 'cimode'
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
*/

option	default	description
debug	false	logs info level to console output. Helps finding issues with loading not working.

option	default	description
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.
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-US` ⇒ `en-us`
cleanCode	false	main language will be lowercased; e.g. `EN` ⇒ `en`, while leaving full locales like `en-US`
ns	'translation'	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

option	default	description
saveMissing	false	calls save missing key function on backend if key not found
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`.
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.

option	default	description
postProcess	false	string or array of postProcessors to apply per default
returnNull	true	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	{...}	see 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

option	default	description
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

option	default	description
initImmediate	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 and i18next-sync-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
appendNamespaceToCIMode	false	prefixes the namespace to the returned key when using `lng: 'cimode'`
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.

Last modified 1mo ago