docs: add i18n story

docs/documentation/stories/i18n.md

@@ -0,0 +1,73 @@
+# Internationalization (i18n)
+
+## Extract messages
+
+First, you have to edit your `src/tsconfig.js` file to exclude the `test.ts` file from compilation, and to specify an output directory where your translations files will be extracted:
+
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "exclude": [ "test.ts" ],
+  "angularCompilerOptions": { 
+    "genDir": "i18n" 
+  }
+}
+```
+
+You can now extract the i18n-marked texts with the following command:
+
+```bash
+$ cd src && ../node_modules/.bin/ng-x18n
+```
+
+Alternatively, you can add a script definition to your `package.json` file:
+
+```json
+{
+  ...
+  "scripts": {
+    ...
+    "xi18n": "cd src && ng-xi18n"
+  },
+  ...
+}
+```
+
+This way, you can now execute the extraction process with this simple command:
+
+```bash
+$ npm run xi18n
+```
+
+After this extraction process, you will find a `messages.xlf` file in the `src/i18n` directory (or any other directory specified in the `angularCompilerOptions/genDir` option above).
+
+You can copy this source file to language-specific files, for example `src/i18n/messages.en.xlf` and `src/i18n/messages.fr.xlf`.
+
+
+## Serve with AOT compilation 
+
+When serving your app with AOT compilation, you can specify the language-specific file that you want to use:
+
+```bash
+$ ng serve --aot \
+  --i18n-file=src/i18n/messages.fr.xlf \
+  --locale=fr
+```
+
+
+## AOT build
+
+When building your app with AOT compilation, you can specify the language-specific file to use and a specific output path, to be able to build the different packs for the different languages:
+
+```bash
+$ ng build --aot \
+  --output-path=dist/fr \  
+  --i18n-file=src/i18n/messages.fr.xlf \
+  --locale=fr
+$ ng build --aot \
+  --output-path=dist/en \  
+  --i18n-file=src/i18n/messages.en.xlf \
+  --locale=en  
+```