requirejs-dplugins/i18n!
requirejs-dplugins/i18n
is a RequireJS plugin which provides support for
localized string.
Table of Contents
Differences with RequireJS i18n plugin
Creating an i18n bundle
Using an i18n bundle
Building i18n bundles
Locale detection
Differences with RequireJS i18n plugin
If an application is not built, this plugin will behave exactly like RequireJS i18n plugin. The only difference is the way they build i18n bundles.
While RequireJS i18n plugin adds bundles of a specified locale to the common layer,
requirejs-dplugins/i18n
will create specific nls layers for each locale specified in the localesList
option. The
plugin will then load the appropriate nls layer depending on the user locale.
Creating an i18n bundle
Assume a my
package, containing a lamp
module. This module provides a string representing the color of
the lamp.
// my/lamp.js
define([], function() {
return {
color: "red"
}
});
The root file
To setup a new i18n bundle, you need to create a new root module in a nls
directory.
The root module is a hashmap of all the available locales for this bundle. This allows the plugin to load the right
locale without having 404s. This module also contains a special root
property containing the default strings.
With the previous setup, to localize the color name in my/lamp
, one will create a my/nls/colors.js
file.
// my/nls/colors.js
define({
root: {
// Default locale is en
red: "red",
green: "green",
blue: "blue"
}
// Additional locales should be listed as siblings of the root property.
});
This leads to the following directory structure:
└── my/
├── nls/
│ └── colors.js
└── lamp.js
Notes:
nls
is a mandatory marker used by the plugin to recognize i18n data and to infer the underlying directory tree.- If you rather keep your root files simple, you can add the default strings as a
root
locale like any other locale.
Add a locale
The addition of a new locale is a three-steps process:
- Create a directory under
nls/
named after the lower-case locale tag. - Create a file in this directory with the same name as the root module. This file should contain the localized string for the corresponding locale.
- Add the locale in the root hashmap.
With the previous setup, following those steps to add the fr
locale leads to:
// my/nls/fr/colors.js
define({
red: "rouge",
green: "vert",
blue: "bleu"
});
// my/nls/colors.js
define({
root: {
// Default locale is en
red: "red",
green: "green",
blue: "blue"
},
// Additional locales should be listed as siblings of the root property.
fr: true
});
And the following directory structure:
└── my/
├── nls/
│ ├── fr/
│ │ └── colors.js
│ └── colors.js
└── lamp.js
Notes:
- The plugin uses the browser's
navigator.language
ornavigator.userLanguage
property to determine the required locale. Then it selects the most suitable locale from the root bundle. The locale can also be set using RequireJS config:
require.config({
config: {
// Set locale to fr
"requirejs-dplugins/i18n": {
locale: "fr"
}
}
});
- If some strings are missing in a localized bundle, the plugin looks for those strings in less specific bundle until
they are found. For instance, when processing a
fr-fr-paris
bundle, the plugin looks into:fr-fr-paris
>fr-fr
>fr
>root
.
Using an i18n bundle
Once the nls
bundle is setup, the plugin can be used to load the bundle. There are two different ways to load a bundle:
* requirejs-dplugins/i18n!./nls/bundle
loads the bundle for the user or config locale.
* requirejs-dplugins/i18n!./nls/locale/bundle
loads the bundle for the locale
specified in the path.
In the previous setup, if one want to display the color in a user's locale, my/lamp
need to be updated to:
// my/lamp.js
define(["requirejs-plugins/i18n!./nls/colors"], function(colors) {
return {
color: colors.red
}
});
Building i18n bundles
This plugin is NOT compatible with r.js. The build tool recommended for an application using requirejs-dplugins
is
grunt-amd-build.
i18n layers
During a build, all i18n bundles required by modules from a layer are concatenated in a per-locale layer,
nls/layername_locale.js
.
In the previous setup, building a layer my
containing my/lamp
results in:
└── my/
├── nls/
│ ├── my_fr.js
│ └── my_root.js
└── my.js
By default, the build creates a layer for all the available locales for each bundle. If only a subset of locales is
needed, it can be specified as an array of locales using the localesList
option. This option should be specified in
the loader configuration of the build tool like this:
{
config: {
"requirejs-dplugins/i18n": {
localesList: ["de", "en", "es", "fr", "it", "ja", "pt"]
}
}
}
When an application is run from a layer, the i18n plugin automatically knows about the corresponding i18n layer. Hence, there is nothing to change in the application.
Layer configuration
Layers can be used in various situation so the plugin offers three options to adapt to most use-cases:
layerOnly
(default: false)If true, the plugin is only looking for i18n bundles in built i18n layers.
enhanceLayer
(default: true)This option is ignored if
layerOnly
is true.This option defines the behaviour of the plugin when a bundle is retrieved from a layer with a less specific locale than requested (ie: bundle
en
from layer whenen-us
was requested).- If false, the plugin only uses the bundle from the layer.
- If true, the plugin loads a more specific individual bundle if one exist.
languagePack
(default: false)If true, this option gives the possibility to add new locales to the application just by adding the corresponding built nls layer. However, this results in more http requests (and some expected 404 in the console), so it should only be used in low latency environments (like cordova applications).
Use-case 1: The application is completely built and the build output is deployed
In this situation, individual bundles are not deployed so the i18n plugin should not look for them.
Hence the runtime configuration should be:
requirejs.config({
config: {
"requirejs-dplugins/i18n": {
layerOnly: true
}
}
});
Use-case 2: The application is partly built and use a mix of layers and individual bundles
In this situation, some individual bundles are deployed but not those already included in a layer.
Hence the runtime configuration should be:
requirejs.config({
config: {
"requirejs-dplugins/i18n": {
enhanceLayer: false
}
}
});
Use-case 3: The application is built and deployed in codorva
In this situation, individual bundles are not deployed so the i18n plugin should not look for them.
Runtime environment is low-latency so the languagePack
option can be used to add support for additional language pack
in the future.
Hence the runtime configuration should be:
requirejs.config({
config: {
"requirejs-dplugins/i18n": {
layerOnly: true,
languagePack: true
}
}
});