# Configuration Options `i18next.init(options, callback)` All options for calling [`init()`](/overview/api.md#init) or [`createInstance()`](/overview/api.md#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](/overview/plugins-and-utils.md#backends) or not using [`addResourceBundle`](/overview/api.md#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.*](/how-to/faq.md#how-should-the-language-codes-be-formatted) | | 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](/principles/fallback.md#language-fallback). | | 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'
(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](/translation-function/essentials.md) | | fallbackNS | false | string or array of namespaces to lookup key if not found in given namespace. [See NS fallback docs](/principles/fallback.md#namespace-fallback). | | 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](https://youtu.be/SA_9i4TtxLQ?t=1032) you can see how the saveMissing functionality is used. | option | default | description | | ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | saveMissing | false | calls save missing key function on backend if key not found *(only for backends that supports the* [*create function*](/misc/creating-own-plugins.md#backend)*, i.e.* [*i18next-fs-backend*](https://github.com/i18next/i18next-fs-backend)*,* [*i18next-http-backend*](https://github.com/i18next/i18next-http-backend)*,* [*i18next-locize-backend*](https://github.com/locize/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, options) { // return value to display }
The options are an internal value container similar to the t() options.

| | 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. | {% hint style="info" %} When `saveMissing` is enabled, missing keys are sent to the backend's `create` function during development. In production, you typically want to disable this. If you're using [i18next-locize-backend](https://github.com/locize/i18next-locize-backend), missing keys appear in your Locize project automatically, ready for translation. {% endhint %} ## Translation defaults | option | default | description | | -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 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 | [{...}](/translation-function/interpolation.md#all-interpolation-options) | see [interpolation](/translation-function/interpolation.md#all-interpolation-options) | | 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 docs](/overview/plugins-and-utils.md#language-detector) | | backend | undefined | options for backend - [check docs](/overview/plugins-and-utils.md#backends) | | cache | undefined | options for a cache layer in backends - [check docs](/overview/plugins-and-utils.md#backends) | ## Others | option | default | description | | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enableSelector (TypeScript only) | false |

if set to true, pass a selector function as the first argument to t to make a translation query.

if set to "optimize", i18next is capable of handling arbitrarily large translation sets without slowing down IDE performance. Keeping in mind with this setting, translation keys will not be modified, so you'll need to specify the correct key for pluralization or use a tool like @i18next-selector/vite-plugin.

| | 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**](https://github.com/i18next/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. | | cacheInBuiltFormats | true | Initializes the internal formatter for the [in-built formats](/translation-function/formatting.md#built-in-formats) as cached version. Can be set to false for this type of [issues](https://github.com/i18next/i18next/issues/2227). | ## initAsync Sample using `initAsync` when using a backend plugin allowing sync (blocking) loads. **This option only works for sync (blocking) loading backend, like** [**i18next-fs-backend**](https://github.com/i18next/i18next-fs-backend)**!** {% tabs %} {% tab title="JavaScript" %} ```javascript 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({ initAsync: false }); i18next.t('key'); // -> will return value /* execution order of function calls - init - loadResources (as called without timeout) - t */ ``` {% endtab %} {% tab title="TypeScript" %} ```typescript 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({ initAsync: false }); i18next.t($ => $.key); // -> will return value /* execution order of function calls - init - loadResources (as called without timeout) - t */ ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://www.i18next.com/overview/configuration-options.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.