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:

Add a locale

The addition of a new locale is a three-steps process:

  1. Create a directory under nls/ named after the lower-case locale tag.
  2. 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.
  3. 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:

require.config({
    config: {
        // Set locale to fr
        "requirejs-dplugins/i18n": {
            locale: "fr"
        }
    }
});

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:

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
        }
    }
});