Skip to content

docs: update intl wiki #10543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 1, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 54 additions & 23 deletions docs/documentation/stories/internationalization.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,50 +21,81 @@ For example to create a file in the `src/locale` folder you would use:
ng xi18n --output-path src/locale
```

### Serve
### Building and serving
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 4 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.
- `--missing-translation` Defines the strategy to use for missing i18n translations.

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 --missing-translation error
If you want to use it when you serve your application you can use the 4 following options:
- `i18nFile` Localization file to use for i18n.
- `i18nFormat` Format of the localization file specified with --i18n-file.
- `i18nLocale` Locale to use for i18n.
- `i18nMissingTranslation` Defines the strategy to use for missing i18n translations.

In our case we can load the french translations with the following configuration:
```json
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": { ... },
"configurations": {
"fr": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
"i18nMissingTranslation": "error",
}
// ...
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"browserTarget": "your-project-name:build"
},
"configurations": {
"production": {
"browserTarget": "your-project-name:build:production"
},
"fr": {
"browserTarget": "your-project-name:build:fr"
}
}
},
```

To build the application using the French i18n options, use `ng build --configuration=fr`.
To serve, use `ng serve --configuration=fr`.

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/locale/messages.fr.xlf --missing-translation error
```
### Using multiple languages

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/locale/messages.fr.xlf --missing-translation error
```
the output path with the `outputPath` options in order to save the files to a different location.

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`.
the base url used by your application with the `baseHref` option.

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/locale/messages.fr.xlf --missing-translation error
```json
"configurations": {
"fr": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"baseHref": "/fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
"i18nMissingTranslation": "error",
}
```

If you need more details about how to create scripts to generate the app in multiple
Expand Down