docs: Ivy i18n guide updates for localize option (#34053)
PR Close #34053
This commit is contained in:
Charles Lyding
Miško Hevery
parent
dd944ef73f
commit
56f4e56094
|
|
@ -137,15 +137,12 @@ The i18n template translation process has four phases:
|
|||
|
||||
3. Edit the generated translation file: Translate the extracted text into the target language.
|
||||
|
||||
4. Merge the completed translation file into the app. To do this, use the Angular CLI `build` command to compile the app, choosing a [locale-specific configuration](#merge), or specifying the following command options.
|
||||
4. Add the target locale and language translation to the application's configuration.
|
||||
|
||||
* `--i18nFile`=*path to the translation file*
|
||||
* `--i18nFormat`=*format of the translation file (only required if using an earlier version of Angular, or if you [disable Ivy](guide/ivy#opting-out-of-ivy-in-version-9))*
|
||||
* `--i18nLocale`= *locale id*
|
||||
|
||||
The command replaces the original messages with translated text, and generates a new version of the app in the target language.
|
||||
|
||||
You need to build and deploy a separate version of the app for each supported language.
|
||||
5. Merge the completed translation file into the application. To do this, use the Angular CLI `build` command to compile the app, choosing a [locale-specific configuration](#merge), or specifying the `--localize` [option](#localize-config). The command replaces the original messages with translated text, and generates a new version of the app in the target language.
|
||||
* When using individual configurations per locale, you need to build and deploy a separate version of the app for each supported language.
|
||||
* When using the `--localize` option, the CLI will automatically build a separate version of the application
|
||||
for each supported language. This option shortens the build process by removing the requirement to perform a full application build for each supported language. You still need to deploy each language-specific version separately.
|
||||
|
||||
{@a i18n-attribute}
|
||||
### Mark text with the i18n attribute
|
||||
|
|
@ -618,20 +615,15 @@ The sample app and its translation file are now as follows:
|
|||
## Merge the completed translation file into the app
|
||||
|
||||
To merge the translated text into component templates, compile the app with the completed
|
||||
translation file.
|
||||
|
||||
Provide the Angular compiler with three translation-specific pieces of information:
|
||||
|
||||
* The translation file.
|
||||
* The translation file format.
|
||||
* The locale (`fr` or `en-US` for instance).
|
||||
translation file. You will need to provide the path to the translation file, and the supported locale or locales for which you have provided translations. You can do this on the command line, or through a build configuration in the project's `angular.json` file.
|
||||
|
||||
The compilation process is the same whether the translation file is in `.xlf` format or in another
|
||||
format that Angular understands, such as `.xtb`.
|
||||
|
||||
{@a merge-aot}
|
||||
The [AOT compiler](guide/glossary#aot) is part of a build process that produces a small, fast,
|
||||
ready-to-run application package, with Ivy it is now used for both production and development.
|
||||
ready-to-run application package. With Ivy in Angular version 9, AOT is used by default for both
|
||||
development and production builds.
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
|
|
@ -641,29 +633,62 @@ additional information regarding translation merging can be found [here](https:/
|
|||
|
||||
</div>
|
||||
|
||||
When you internationalize with the AOT compiler, you must pre-build a separate application
|
||||
When you internationalize with the AOT compiler, you must build a separate application
|
||||
package for each language and serve the appropriate package based on either server-side language
|
||||
detection or URL parameters.
|
||||
detection or URL parameters. The CLI can be configured to automatically build separate locale-specific versions
|
||||
for each defined locale.
|
||||
|
||||
To instruct the AOT compiler to use your translation configuration, set the three "i18n" build configuration options in your CLI configuration file, `angular.json`.
|
||||
{@a localize-config}
|
||||
The `i18n` project option in your CLI configuration file is used to define locales for a project. The sub-options identify the source language and tell the compiler where to find supported translations for the project.
|
||||
|
||||
* `i18nFile`: the path to the translation file.
|
||||
* `i18nFormat`: the format of the translation file (only required if using an earlier version of Angular, or if you [disable Ivy](guide/ivy#opting-out-of-ivy-in-version-9)).
|
||||
* `i18nLocale`: the locale id.
|
||||
* `sourceLocale` - The locale used within the source code for the application. Defaults to `en-US`.
|
||||
* `locales` - A map of locale identifiers to translation files
|
||||
|
||||
You should also direct the output to a locale-specific folder to keep it separate from other locale versions of your app, by setting the `outputPath` configuration option.
|
||||
<code-example language="json" header="angular.json">
|
||||
"projects": {
|
||||
...
|
||||
"angular.io-example": {
|
||||
...
|
||||
"i18n": {
|
||||
"sourceLocale": "en-US",
|
||||
"locales": {
|
||||
"fr": "src/locale/messages.fr.xlf"
|
||||
}
|
||||
}
|
||||
...
|
||||
"targets": {
|
||||
...
|
||||
}
|
||||
}
|
||||
}
|
||||
</code-example>
|
||||
|
||||
```
|
||||
To instruct the AOT compiler to use your translation configuration, set the `localize` build configuration option in your CLI configuration file, `angular.json`. The option supports the following values:
|
||||
|
||||
* `true` - Build and generate locale-specific versions for all defined locales including the source locale.
|
||||
* `false` - (default) Disable localization and do not generate locale-specific versions.
|
||||
* Array of locale identifiers - Build and generate locale-specific versions for one or more specified locales.
|
||||
|
||||
When using the `localize` option, the CLI places the output in a locale-specific directory to keep it separate from other locale versions of your application. The directories are placed within the configured `outputPath` for the project.
|
||||
The CLI also adjusts the HTML base HREF for each version of the application by adding the locale to the configured `baseHref`.
|
||||
|
||||
You can also provide the `--localize` option to the `ng build` command with your existing `production` configuration.
|
||||
In this case, the CLI builds all locales defined under i18n in the project configuration.
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng build --prod --localize
|
||||
</code-example>
|
||||
|
||||
To apply specific build options to only one locale, you can create a custom locale-specific configuration. In this case, the localize option specifies the single locale, as shown here.
|
||||
|
||||
<code-example language="json" header="angular.json">
|
||||
"build": {
|
||||
...
|
||||
"configurations": {
|
||||
...
|
||||
"fr": {
|
||||
"aot": true,
|
||||
"outputPath": "dist/my-project-fr/",
|
||||
"i18nFile": "src/locale/messages.fr.xlf",
|
||||
"i18nFormat": "xlf",
|
||||
"i18nLocale": "fr",
|
||||
"localize": ["fr"],
|
||||
"main": "src/main.fr.ts",
|
||||
...
|
||||
}
|
||||
}
|
||||
|
|
@ -677,7 +702,7 @@ You should also direct the output to a locale-specific folder to keep it separat
|
|||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
</code-example>
|
||||
|
||||
You can then pass this configuration to the `ng serve` or `ng build` commands.
|
||||
The example below shows how to serve the French language file created in previous
|
||||
|
|
@ -687,13 +712,19 @@ sections of this guide:
|
|||
ng serve --configuration=fr
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
The CLI development server (`ng serve`) can only be used with a single locale.
|
||||
|
||||
</div>
|
||||
|
||||
For production builds, you can use configuration composition to execute both configurations:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng build --configuration=production,fr
|
||||
</code-example>
|
||||
|
||||
```
|
||||
<code-example language="json" header="angular.json">
|
||||
...
|
||||
"architect": {
|
||||
"build": {
|
||||
|
|
@ -701,12 +732,7 @@ For production builds, you can use configuration composition to execute both con
|
|||
"options": { ... },
|
||||
"configurations": {
|
||||
"fr": {
|
||||
"aot": true,
|
||||
"outputPath": "dist/my-project-fr/",
|
||||
"i18nFile": "src/locale/messages.fr.xlf",
|
||||
"i18nFormat": "xlf",
|
||||
"i18nLocale": "fr",
|
||||
"i18nMissingTranslation": "error",
|
||||
"localize": ["fr"],
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -726,12 +752,6 @@ For production builds, you can use configuration composition to execute both con
|
|||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The same configuration options can also be provided through the CLI with your existing `production` configuration.
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng build --prod --i18n-file src/locale/messages.fr.xlf --i18n-format xlf --i18n-locale fr
|
||||
</code-example>
|
||||
|
||||
{@a missing-translation}
|
||||
|
|
@ -746,36 +766,15 @@ compilation, the app will fail to load.
|
|||
* Warning (default): show a 'Missing translation' warning in the console or shell.
|
||||
* Ignore: do nothing.
|
||||
|
||||
You specify the warning level in the `configurations` section of your Angular CLI configuration file, `angular.json`. The example below shows how to set the warning level to error.
|
||||
You specify the warning level in the `options` section for the `build` target of your Angular CLI configuration file, `angular.json`. The example below shows how to set the warning level to error.
|
||||
|
||||
```
|
||||
"configurations": {
|
||||
<code-example language="json" header="angular.json">
|
||||
"options": {
|
||||
...
|
||||
"fr": {
|
||||
...
|
||||
"i18nMissingTranslation": "error"
|
||||
}
|
||||
"i18nMissingTranslation": "error"
|
||||
}
|
||||
```
|
||||
</code-example>
|
||||
|
||||
### Build for multiple locales
|
||||
|
||||
When you use the CLI `build` or `serve` command to build your application for different locales, change the output path using the `--outputPath` command option (along with the i18n-specific command options), so that the translation files are saved to different locations.
|
||||
When you are serving a locale-specific version from a subdirectory, you can also change the base URL used by your app by specifying the `--baseHref` option.
|
||||
|
||||
For example, if the French version of your application is served from https://example.com/fr/, configure the build for the French version as follows.
|
||||
|
||||
```
|
||||
"configurations": {
|
||||
"fr": {
|
||||
"aot": true,
|
||||
"outputPath": "dist/my-project-fr/",
|
||||
"baseHref": "/fr/",
|
||||
"i18nFile": "src/locale/messages.fr.xlf",
|
||||
"i18nFormat": "xlf",
|
||||
"i18nLocale": "fr",
|
||||
"i18nMissingTranslation": "error",
|
||||
}
|
||||
```
|
||||
### Deployment for multiple locales
|
||||
|
||||
For more details about how to create scripts to generate an app in multiple languages and how to set up Apache 2 and NGINX to serve them from different subdirectories, read [this tutorial by Philippe Martin](https://dev.to/angular/deploying-an-i18n-angular-app-with-angular-cli-2fb9).
|
||||
|
|
|
|||
Loading…
Reference in New Issue