On this page
Plugins
Plugins add what the core leaves out, such as loading translations, detecting the language or another message syntax; `use()` registers them.
i18next comes with a lot of modules. There are modules to:
- load resources, e.g. via http fetch or from the filesystem (Node.js, Deno)
- cache resources using e.g. i18next-localstorage-backend
- detect user language by querystring, navigator, cookie, …
- post processors to further manipulate values, e.g. interval plurals
- i18n formats to write translations in another syntax, e.g. ICU or MF2
import i18next from 'i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
import intervalPlural from 'i18next-intervalplural-postprocessor';
i18next
.use(Backend) // or any other backend implementation
.use(LanguageDetector) // or any other implementation
.use(intervalPlural) // or any other post processor
.init(options);
For usage details please read the documentation of the plugin (readme file in the repository or npm website).
Writing your own plugin
Each plugin type implements the interface below. You can provide a singleton or a prototype constructor (preferred for supporting multiple instances of i18next).
Backend
Backend plugins are used to load data for i18next.
{
type: 'backend',
callbackApi: false, // read and create return a promise or a value, see below
init: function(services, backendOptions, i18nextOptions) {
/* use services and options */
},
read: function(language, namespace) {
/* return the resources, or a promise of them;
reject or throw if loading fails */
return Promise.resolve({ key: 'value' });
},
// optional, only used through i18next-multiload-backend-adapter
readMulti: function(languages, namespaces) {
/* return multiple resources, useful e.g. to load them in one request */
return Promise.resolve({
en: { translation: { key: 'value' } },
de: { translation: { key: 'value' } }
});
},
// only used in backends acting as cache layer
save: function(language, namespace, data) {
// store the translations
},
create: function(languages, namespace, key, fallbackValue, options) {
/* save the missing translation;
options.isUpdate tells an update from a new key */
}
}
callbackApi (as an instance or static property) declares how i18next calls read and create:
false:read(language, namespace)andcreate(languages, namespace, key, fallbackValue, options)return a promise or a valuetrue:read(language, namespace, callback)andcreate(languages, namespace, key, fallbackValue, callback, options)(see Older ways)
Without it, i18next guesses from the number of parameters (Function.length), which default and rest parameters change; guessing is deprecated and logs a warning in debug mode.
To reload resources, for example on an interval, call services.utils.reloadResources() instead of the backendConnector: it reads through your backend with retries and emits loaded, as i18next.reloadResources() does. Without arguments it reloads everything i18next loaded or tried to load through your backend, also for clones, and retries the bundles that failed.
readMulti is only called by i18next-multiload-backend-adapter.
languageDetector
Language detector plugins are used to detect language in user land.
{
type: 'languageDetector',
async: true, // detect returns a promise
callbackApi: false, // detect() returns a promise
// (true: detect(callback), see Older ways)
init: function(services, detectorOptions, i18nextOptions) { // optional
/* use services and options */
},
detect: async function() {
/* return the detected language, e.g. from AsyncStorage */
return 'de';
},
cacheUserLanguage: function(lng) { // optional; i18next does not wait for it
/* cache language */
}
}
A detector that answers at once leaves out async and returns the language from detect() directly.
A detector that takes the language from a request, a URL or storage can check it with isSafeLanguageCode(code), exported by i18next: letters, digits, -, _, @ and . (no ..), at most 128 characters. It is not a BCP 47 check, so codes like en_US pass; markup, slashes and spaces do not.
Post processor
Post processors are used to extend or manipulate the translated values before returning them in the t function.
A post processor can be a plain object.
{
type: 'postProcessor',
name: 'nameOfProcessor',
process: function(value, key, options, translator) {
/* return manipulated value */
return value;
}
}
Logger
Override the built-in console logger.
A logger can be a plain object.
{
type: 'logger',
log: function(args) {},
warn: function(args) {},
error: function(args) {}
}
Formatter
Override the built-in formatter.
{
type: 'formatter',
init: function(services, i18nextOptions) {},
add: function(name, fc) {},
addCached: function(name, fc) {},
format: function(value, format, lng, options) {
if (!format && value instanceof Date) {
return value.toUTCString()
}
return value
}
}
i18n format
i18n format plugins replace the i18next message format with another syntax, like i18next-icu or i18next-mf2. Only one i18nFormat plugin can be used per i18next instance.
{
type: 'i18nFormat',
// called on i18next.init with the i18next instance;
// by convention the plugin reads its options from i18next.options.i18nFormat
init: function(i18next) {},
// called instead of i18next's interpolation and nesting (also when
// skipInterpolation is set);
// the return value goes through post processing and is returned by t
parse: function(res, options, lng, ns, key, info) {
// res: the found value, or the defaultValue or key if nothing was found
// options: the t options, merged over interpolation.defaultVariables
// info.resolved: { res, usedKey, exactUsedKey, usedLng, usedNS }
return res;
},
// called instead of i18next's plural and context suffix lookup, for each
// language code and namespace;
// finalKeys starts as [key], push more keys to it (the last one is looked up
// first)
addLookupKeys: function(finalKeys, key, code, ns, options) {
return finalKeys;
},
// optional: if true, i18next handles objects and arrays as usual
// (returnObjects, joinArrays);
// if not set, they are passed to parse
handleAsObject: false,
// optional: replaces the lookup in the resource store
// getResource: function(code, ns, key, options) {}
}
Helpful tips
Set the plugin type
A plugin class needs its type as a static property:
class Backend {
// read, create, …
}
Backend.type = 'backend';
Without it, i18next.use(Backend) throws "You are passing a wrong module! Please check the object you are passing to i18next.use()".
Options arrive in init, not in the constructor
i18next creates a plugin class without arguments and then calls init with the options from i18next.init (for a backend, its backend options). Read and check them there:
class Backend {
init(services, backendOptions = {}, i18nextOptions) {
this.loadPath = backendOptions.loadPath ?? '/locales';
}
read(language, namespace) {
return fetch(`${this.loadPath}/${language}/${namespace}.json`)
.then((res) => res.json());
}
}
Backend.type = 'backend';
Backend.callbackApi = false;
Older ways
Callback backends and detectors
With callbackApi: true, read and create take a callback instead of returning a promise:
{
type: 'backend',
callbackApi: true,
read: function(language, namespace, callback) {
callback(null, { key: 'value' });
/* if loading fails: callback(error, null) */
},
readMulti: function(languages, namespaces, callback) {
callback(null, { en: { translation: { key: 'value' } } });
},
create: function(languages, namespace, key, fallbackValue, callback, options) {}
}
An async language detector with callbackApi: true gets a callback in detect:
{
type: 'languageDetector',
async: true,
callbackApi: true,
detect: function(callback) {
callback('de');
}
}