Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
246 lines (220 sloc) 9.59 KB

Configuration Options

Configuration options

i18next.init(options, callback)

All options for calling init or createInstance.


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 loading or not appending 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 'en-US' language code format and not with underscore 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.

Learn more.

supportedLngs false array of allowed languages
nonExplicitSupportedLngs false if true will pass eg. en-US if finding en in supportedLngs
load 'all' language codes to lookup, 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 serverside to assert translations are loaded before rendering views.
lowerCaseLng false locale will be fully lowercased eg. en-US --> en-us
cleanCode false language will be lowercased EN --> en while leaving full locales like en-US
ns 'translation' string or array of namespaces to load
defaultNS 'translation' default namespace used if not passed to translation function
fallbackNS false string or array of namespaces to lookup key if not found in given namespace. Learn more.
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 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'
saveMissingPlurals true will save all plural forms instead of only singular if t was called for plurals
missingKeyHandler false function(lng, ns, key, fallbackValue) { } used for custom missing key handling (needs saveMissing set to true!)
parseMissingKeyHandler noop function(key) { // 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 empty string or null

translation defaults

option default description
simplifyPluralSuffix true will use 'plural' as suffix for languages only having 1 plural form, setting it to false will suffix all with numbers
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
returnedObjectHandler noop function(key, value, options) {} gets called if object was passed in as key but returnObjects was set to false
joinArrays false char, eg. '\n' that arrays will be joined by
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

plugin options

option default description
detection undefined options for language detection - check documentation of plugin
backend undefined options for backend - check documentation of plugin
cache undefined options for cache layer - check documentation of plugin


option default description
initImmediate true

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 relying on the init 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 keySeparator 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'


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 and i18next-sync-fs-backend!

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

// not working

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
  .init({ initImmediate: false });

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

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