THIS PROJECT IS NO LONGER MAINTAINED
A RequireJS plugin for requiring and optimizing translations using i18next.
NOTE: This plugin does not support i18next version 2.x
The plugin supports both RequireJS and Almond.
The require-i18next plugin makes is able to load locales as dependency in requirejs by simply using the prefix i18n! followed by a path to the directory of your locales.
require(["some/module", "i18n!path/to/locales"], function(module, i18n) {
// The i18n variable is an instance of i18next
// So right here you can for example call i18n.t("some_key")
// to get the translation for "some_key"
// (See the i18next docs for more details)
});With i18next you can load multiple namespaces and refer to them when
calling translate with a key (for example i18next.t("namespace:key")).
This plugin gives you the option to load additional namespaces immediately when loading a locale by doing:
require(["some/module", "i18n!path/to/locales:namespace1,namespace2"], function(module, i18n) {
// The additional namespaces "namespace1" and "namespace2" are now loaded
// So right now we can for example call i18n.t("namespace1:some_key")
// to get the translation for "some_key" in namespace "namespace1"
// (See the i18next docs for more details)
});When loading multiple locale files from different locations within the same requirejs module, the locales will be merged. So for example if you load the following locale files in the same module:
// Locale file 1
{
"key1": "value1",
"key2": "value2"
}
// Locale file 2
{
"key1": "value1",
"key2": "value2"
}
// Later in the code
i18n.t("key1");The second translations will overwrite the first translations (because the keys are the same). To prevent these overriding, it is always a good idea to put the keys in a separate (unique) scope, so for example:
// Locale file 1
{
"translations1": {
"key1": "value1",
"key2": "value2"
}
}
// Locale file 2
{
"translations2": {
"key1": "value1",
"key2": "value2"
}
}
// Later in the code
i18n.t("translations1.key1");This way, loading both locales will not override any existing translations within the same namespace.
Below follows a basic example on how to set up the plugin in requirejs.
requirejs.config({
map: {
"*": {
i18n: "path/to/require/i18next/plugin"
}
},
paths: {
i18next: "path/to/i18next"
}
});Now you can use the i18n! prefix to load locales.
Normally i18next is initialized with options by calling i18next.init().This plugin makes it able to define the i18next options in the requirejs configuration:
requirejs.config({
i18next: {
ns : "messages",
fallbackLng : "en",
detectLngQS : "locale",
lowerCaseLng : true,
useCookie : false,
resGetPath : "__ns__.__lng__.json"
}
});The plugin will pass the options to i18next when loading locales.
Currently i18next will try to load the locales it has detected from a user's browser or cookie, first by trying the specific locale, secondly by trying the unspecific locale and finally by trying the fallback locale. So for example when it has detected nl-NL, it will try to load nl-NL -> nl -> en (when en is set as fallback language). So it tries to load each locale, even if you don't have support for one of them.
The plugin adds an extra option "supportedLngs" to define the languages and namespaces you do support and will only try to load a locale if it is supported.
The supported languages can be defined by languages and namespaces pairs:
requirejs.config({
i18next: {
supportedLngs: {
en: ["namespace1", "namespace2"],
nl: ["namespace1"]
}
}
});It is also possible to define the supported languages with a scope:
requirejs.config({
i18next: {
supportedLngs: {
"path/to/locales1": {
en: ["namespace1", "namespace2"],
nl: ["namespace1"]
},
"path/to/locales2": {
en: ["namespace1"]
}
}
}
});With the above example when loading locales with "i18n!path/to/locales1"only the languages defined in the "path/to/locales1" scope will be used as supported languages.
The plugin supports inlining of locales when optimizing with requirejs. When inlining, the plugin will load all the locale files used in each module and add them to the final build file. After the build process, i18next doesn't have to dynamicly load any locales anymore.
Note: the supportedLngs option is needed for inlining locales (see Advanced configuration)
({
// Enable inlining locales
inlineI18next: true,
// Plugin code is not needed anymore when inlining locales
stubModules: ["path/to/require/i18next/plugin"],
// Add the i18next lib as dependency to the module
// (it is not included by the plugin when building)
shim: {
"main": ["i18next"]
},
// The name of the module to build
name: "main",
...
})({
// Enable inlining locales
inlineI18next: true,
// Plugin code is not needed anymore when inlining locales
stubModules: ["path/to/require/i18next/plugin"],
// Add the i18next lib as dependency to the modules which use the plugin
// (it is not included by the plugin when building)
shim: {
"first": ["i18next"],
"second": ["i18next"]
},
// The modules to build
modules: [
{
name: "first"
},
{
name: "second"
}
],
...
})This project is released under the MIT license.