add doc for i18n

Author: clmath

docs/i18n.md

@@ -0,0 +1,251 @@
+---
+layout: default
+title: requirejs-dplugins/i18n
+---
+
+# requirejs-dplugins/i18n
+
+`requirejs-dplugins/i18n` is a [requirejs plugin](http://requirejs.org/docs/plugins.html) which provides support for
+ localized string.
+
+##### Table of Contents
+[Creating an i18n bundle](#creating-an-i18n-bundle)  
+[Using an i18n bundle](#using-an-i18n-bundle)  
+[Building i18n bundles](#building-i18n-bundles)  
+
+## Creating an i18n bundle
+
+Assume a `my` package, containing a `lamp` module. This module provides a string representing the color of the lamp.
+```js
+// 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.
+
+```js
+// 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.
+1. 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.
+1. Add the locale in the root hashmap.
+
+With the previous setup, following those steps to add the `fr` locale leads to:
+
+```js
+// my/nls/fr/colors.js
+define({
+	red: "rouge",
+	green: "vert",
+	blue: "bleu"
+});
+```
+```js
+// 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:
+```js
+// 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](https://github.com/ibm-js/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:
+
+```js
+{
+	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
+        }
+    }
+});
+```