i18n.md

layout	title
doc	requirejs-dplugins/i18n

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:

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:

• The plugin uses the browser's navigator.language or navigator.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 when en-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
        }
    }
});