Overview
Translation Function
Fallback
Doing graceful fallbacks is a core principle of i18next. This enables you to display the most accurate content possible, while not repeating content over and over.
Language fallback
Variant resolving - fallback from dialects or scripts
By default, if a variant (containing region, script, etc) is not found, i18next will look for the same key in the broader version of that language. With this in mind, a common strategy if you're supporting language variants is to write common text inside the pure language, specifying only what differs in the variants.
Example:
1
// fallback to one language
2
i18next.init({
3
lng: "en-GB",
4
resources: {
5
"en-GB": {
6
"translation": {
7
"i18n": "Internationalisation"
8
}
9
},
10
"en": {
11
"translation": {
12
"i18n": "Internationalization",
13
"i18n_short": "i18n"
14
}
15
}
16
}
17
}, () => {
18
i18next.t('i18n'); // -> finds "Internationalisation"
19
i18next.t('i18n_short'); // -> falls back to "en": "i18n"
20
​
21
// force using en
22
i18next.t('i18n', { lng: 'en' }); // -> "Internationalization"
23
});
Copied!
Fallback to different languages
If you can not provide the preferred language for a user, you can specify another language as fallback. This is useful to indicate the main language or, for instance, if you want to keep the fallbacks different per region.
1
// fallback to one language
2
i18next.init({
3
fallbackLng: 'en'
4
});
5
​
6
// fallback ordered
7
i18next.init({
8
fallbackLng: ['fr', 'en']
9
});
10
​
11
// fallback depending on user language
12
i18next.init({
13
fallbackLng: {
14
'de-CH': ['fr', 'it'], //French and Italian are also spoken in Switzerland
15
'zh-Hant': ['zh-Hans', 'en'],
16
'es': ['fr'],
17
'default': ['en']
18
}
19
});
20
​
21
// function that returns an array of fallbacks
22
// your function may also return a string or object as above
23
i18next.init({
24
fallbackLng: (code) => {
25
if (!code || code === 'en') return ['en-US'];
26
const fallbacks = [code];
27
​
28
// We maintain en-US and en-AU. Some regions will prefer en-AU.
29
if (code.startsWith('en-') && !['en-US', 'en-AU'].includes(code)) {
30
if (['en-GB', 'en-NZ', 'en-IR'].includes(code)) fallbacks.push('en-AU');
31
else fallbacks.push('en-US');
32
return fallbacks;
33
}
34
​
35
// add pure lang
36
const langPart = code.split('-')[0];
37
if (langPart !== code) fallbacks.push(langPart);
38
​
39
// finally, developer language
40
fallbacks.push('en-AU');
41
return fallbacks;
42
}
43
});
Copied!
The default is set to
dev which means developer language. At first this might look strange to set the default to a language, but this enables to set the saveMissing feature to send new keys to that developer specific language. From there your translators can modify the texts to a translation file containing, for instance, proper English, including defined terminology. For production use, just set fallbackLng to an existing language.Namespace fallback
i18next by default loads its translations from one file named
translation. However, you can configure it to load from multiple files, called namespaces.Besides defining multiple namespaces to load from, you also can set fallback namespaces. Thus, if a key to translate isn't found in the given namespace, it will look it up in the indicated fallbacks.
app.json
1
{
2
"title": "i18next"
3
}
Copied!
common.json
1
{
2
"button": {
3
"save": "save"
4
}
5
}
Copied!
Sample
1
i18next.init({
2
// files to load
3
ns: ['app', 'common'],
4
​
5
// default namespace (needs no prefix on calling t)
6
defaultNS: 'app',
7
​
8
// fallback, can be a string or an array of namespaces
9
fallbackNS: 'common'
10
}, () => {
11
i18next.t('title') // -> "i18next"
12
​
13
i18next.t('button.save') // -> "save" (fallback from common)
14
​
15
// without fallbackNS you would have to prefix namespace
16
// to access keys in that namespace
17
// and this is not recommended when used in combination with natural language keys
18
i18next.t('common:button.save') // -> "save"
19
// better use the ns option:
20
i18next.t('button.save', { ns: 'common' }) // -> "save"
21
});
Copied!
Key fallback
Key not found
If a key does not return a value the key acts as fallback:
1
i18next.t('notExistingKey'); // -> "notExistingKey"
Copied!
So you could configure i18next to have the key being the fallback instead of loading a fallback language:
de.json
1
{
2
"No one says a key can not be the fallback.": "Niemand sagt ein key kann nicht als Ersatz dienen."
3
}
Copied!
1
i18next.init({
2
lng: 'de',
3
​
4
// allow keys to be phrases having `:`, `.`
5
nsSeparator: false,
6
keySeparator: false,
7
​
8
// do not load a fallback
9
fallbackLng: false
10
});
11
​
12
i18next.t('No one says a key can not be the fallback.')
13
// -> "Niemand sagt ein key kann nicht als Ersatz dienen."
14
​
15
​
16
i18next.t('This will be shown if the current loaded translations do not have this.');
17
// -> "This will be shown if the current loaded translations do not have this."
Copied!
While this works and might reduce files to load it makes the management of translations a lot harder as you will need to update changes to fallback values in code and JSON files.
Possible - but not recommended.
Missing values for existing keys
In addition to the above, if you want missing values to fallback to the key in cases where the keys (e.g. got extracted by a code parser) exist in your JSON translation file with empty string as value, you also need this setting:
1
// allow an empty value to count as invalid (by default is true)
2
returnEmptyString: false
Copied!
Calling with fallback keys
Calling the t function with an array of keys enables you to translate dynamic keys providing a non specific fallback value.
As a sample think of an error code you get and you like to show a specific warning in some cases:
translation.json
1
{
2
"error": {
3
"unspecific": "Something went wrong.",
4
"404": "The page was not found."
5
}
6
}
Copied!
Sample
1
// const error = '404';
2
i18next.t([`error.${error}`, 'error.unspecific']) // -> "The page was not found"
3
​
4
// const error = '502';
5
i18next.t([`error.${error}`, 'error.unspecific']) // -> "Something went wrong"
Copied!
Last modified 7mo ago