|
| 1 | +# Internationalization (i18n) |
| 2 | + |
| 3 | +If you are working on internationalization, the CLI can help you with the following steps: |
| 4 | +- extraction |
| 5 | +- serve |
| 6 | +- build |
| 7 | + |
| 8 | +The first thing that you have to do is to setup your application to use i18n. |
| 9 | +To do that you can follow [the cookbook on angular.io](https://angular.io/docs/ts/latest/cookbook/i18n.html). |
| 10 | + |
| 11 | +### Extraction |
| 12 | +When your app is ready, you can extract the strings to translate from your templates with the |
| 13 | +`ng xi18n` command. |
| 14 | + |
| 15 | +By default it will create a file named `messages.xlf` in your `src` folder. |
| 16 | +You can use [parameters from the xi18n command](../xi18n) to change the format, |
| 17 | +the name, the location and the source locale of the extracted file. |
| 18 | + |
| 19 | +For example to create a file in the `src/locale` folder you would use: |
| 20 | +```sh |
| 21 | +ng xi18n --output-path src/locale |
| 22 | +``` |
| 23 | + |
| 24 | +### Serve |
| 25 | +Now that you have generated a messages bundle source file, you can translate it. |
| 26 | +Let's say that your file containing the french translations is named `messages.fr.xlf` |
| 27 | +and is located in the `src/locale` folder. |
| 28 | +If you want to use it when you serve your application you can use the 3 following commands: |
| 29 | +- `--i18n-file` Localization file to use for i18n. |
| 30 | +- `--i18n-format` Format of the localization file specified with --i18n-file. |
| 31 | +- `--locale` Locale to use for i18n. |
| 32 | + |
| 33 | +In our case we can load the french translations with the following command: |
| 34 | +```sh |
| 35 | +ng serve --aot --locale fr --i18n-format xlf --i18n-file src/locale/messages.fr.xlf |
| 36 | +``` |
| 37 | + |
| 38 | +Our application is exactly the same but the `LOCALE_ID` has been provided with "fr", |
| 39 | +`TRANSLATIONS_FORMAT` with "xlf" and `TRANSLATIONS` with the content of `messages.fr.xlf`. |
| 40 | +All the strings flagged for i18n have been replaced with their french translations. |
| 41 | + |
| 42 | +Note: this only works for AOT, if you want to use i18n in JIT you will have to update |
| 43 | +your bootstrap file yourself. |
| 44 | + |
| 45 | +### Build |
| 46 | +To build your application with a specific locale you can use the exact same commands |
| 47 | +that you used for `serve`: |
| 48 | +```sh |
| 49 | +ng build --aot --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf |
| 50 | +``` |
| 51 | + |
| 52 | +When you build your application for a specific locale, it is probably a good idea to change |
| 53 | +the output path with the command `--output-path` in order to save the files to a different location. |
| 54 | + |
| 55 | +```sh |
| 56 | +ng build --aot --output-path dist/fr --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf |
| 57 | +``` |
| 58 | + |
| 59 | +If you end up serving this specific version from a subdirectory, you can also change |
| 60 | +the base url used by your application with the command `--base-href`. |
| 61 | + |
| 62 | +For example if the french version of your application is served from https://myapp.com/fr/ |
| 63 | +then you would build the french version like this: |
| 64 | + |
| 65 | +```sh |
| 66 | +ng build --aot --output-path dist/fr --base-href fr --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf |
| 67 | +``` |
| 68 | + |
| 69 | +If you need more details about how to create scripts to generate the app in multiple |
| 70 | +languages and how to setup Apache 2 to serve them from different subdirectories, |
| 71 | +you can read [this great tutorial](https://medium.com/@feloy/deploying-an-i18n-angular-app-with-angular-cli-fc788f17e358#.1xq4iy6fp) |
| 72 | +by Philippe Martin. |
0 commit comments