docs(@angular/cli): add i18n commands and story

docs/documentation/home.md

@@ -52,6 +52,7 @@ End-to-end tests are run via [Protractor](https://angular.github.io/protractor/)
 * [ng get/ng set](config)
 * [ng doc](doc)
 * [ng eject](eject)
+* [ng xi18n](xi18n)
 
 ### Additional Information
 There are several [stories](stories) which will walk you through setting up

docs/documentation/serve.md

@@ -5,7 +5,7 @@
 ## Overview
 `ng serve` builds the application and starts a web server
 
-All the build Options are available in serve below are the additional options.
+All the build Options are available in serve, below are the additional options.
 
 ## Options
 `--host` (`-H`) Listens only on localhost by default.

docs/documentation/stories.md

@@ -20,4 +20,5 @@
  - [Routing](stories/routing)
  - [3rd Party Lib](stories/third-party-lib)
  - [Corporate Proxy](stories/using-corporate-proxy)
+ - [Internationalization (i18n)](stories/internationalization)
  - [Serve from Disk](stories/disk-serve)

docs/documentation/stories/internationalization.md

@@ -0,0 +1,72 @@
+# Internationalization (i18n)
+
+If you are working on internationalization, the CLI can help you with the following steps: 
+- extraction
+- serve
+- build
+
+The first thing that you have to do is to setup your application to use i18n.
+To do that you can follow [the cookbook on angular.io](https://angular.io/docs/ts/latest/cookbook/i18n.html).
+
+### Extraction
+When your app is ready, you can extract the strings to translate from your templates with the
+`ng xi18n` command.
+
+By default it will create a file named `messages.xlf` in your `src` folder.
+You can use [parameters from the xi18n command](../xi18n) to change the format,
+the name, the location and the source locale of the extracted file.
+
+For example to create a file in the `src/locale` folder you would use:
+```sh
+ng xi18n --output-path src/locale
+```
+
+### Serve
+Now that you have generated a messages bundle source file, you can translate it.
+Let's say that your file containing the french translations is named `messages.fr.xlf` 
+and is located in the `src/locale` folder.
+If you want to use it when you serve your application you can use the 3 following commands:
+- `--i18n-file` Localization file to use for i18n.
+- `--i18n-format` Format of the localization file specified with --i18n-file.
+- `--locale` Locale to use for i18n.
+
+In our case we can load the french translations with the following command:
+```sh
+ng serve --aot --locale fr --i18n-format xlf --i18n-file src/locale/messages.fr.xlf
+```
+
+Our application is exactly the same but the `LOCALE_ID` has been provided with "fr",
+`TRANSLATIONS_FORMAT` with "xlf" and `TRANSLATIONS` with the content of `messages.fr.xlf`.
+All the strings flagged for i18n have been replaced with their french translations.
+
+Note: this only works for AOT, if you want to use i18n in JIT you will have to update
+your bootstrap file yourself.
+
+### Build
+To build your application with a specific locale you can use the exact same commands
+that you used for `serve`:
+```sh
+ng build --aot --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf
+```
+
+When you build your application for a specific locale, it is probably a good idea to change
+the output path with the command `--output-path` in order to save the files to a different location.
+
+```sh
+ng build --aot --output-path dist/fr --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf
+```
+
+If you end up serving this specific version from a subdirectory, you can also change
+the base url used by your application with the command `--base-href`.
+
+For example if the french version of your application is served from https://myapp.com/fr/
+then you would build the french version like this:
+
+```sh
+ng build --aot --output-path dist/fr --base-href fr --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf
+```
+
+If you need more details about how to create scripts to generate the app in multiple
+languages and how to setup Apache 2 to serve them from different subdirectories,
+you can read [this great tutorial](https://medium.com/@feloy/deploying-an-i18n-angular-app-with-angular-cli-fc788f17e358#.1xq4iy6fp)
+by Philippe Martin.

docs/documentation/xi18n.md

@@ -0,0 +1,21 @@
+<!-- Links in /docs/documentation should NOT have `.md` at the end, because they end up in our wiki at release. -->
+
+# ng xi18n
+
+## Overview
+`ng xi18n` Extracts i18n messages from the templates.
+
+## Options
+`--i18n-format` (`-f`) Output format for the generated file: either `xmb` or `xlf`.
+
+`--output-path` (`-op`) Path where output will be placed.
+
+`--locale` (`-l`) Specifies the source language of the application.
+
+`--outfile` (`-of`)  Name of the file to output.
+
+`--verbose` Adds more details to output logging.
+
+`--progress` Log progress to the console while running.
+
+`--app` (`-a`) Specifies app name to use.