Judy Bogart
Kara Erickson
parent
927323f24e
commit
f37cf52b4c
|
|
@ -10,14 +10,21 @@ an AOT-compiled app, translated into French.
|
|||
{@a angular-i18n}
|
||||
## Angular and i18n
|
||||
|
||||
*Internationalization* is the process of designing and preparing your app to be usable in different languages.
|
||||
*Localization* is the process of translating your internationalized app into specific languages for particular locales.
|
||||
|
||||
Angular simplifies the following aspects of internationalization:
|
||||
* Displaying dates, number, percentages, and currencies in a local format.
|
||||
* Translating text in component templates.
|
||||
* Preparing text in component templates for translation.
|
||||
* Handling plural forms of words.
|
||||
* Handling alternative text.
|
||||
|
||||
This document focuses on [**Angular CLI**](https://cli.angular.io/) projects, in which the Angular
|
||||
CLI generates most of the boilerplate necessary to write your app in multiple languages.
|
||||
For localization, you can use the [**Angular CLI**](https://cli.angular.io/) to generate most of the boilerplate necessary to create files for translators, and to publish it in multiple languages.
|
||||
After you have set up your app to use i18n, the CLI can help you with the following steps:
|
||||
* Extracting localizable text into a file that you can send out to be translated.
|
||||
* Building and serving the app for a given locale, using the translated text.
|
||||
* Creating multiple language versions of your app.
|
||||
|
||||
|
||||
{@a setting-up-locale}
|
||||
## Setting up the locale of your app
|
||||
|
|
@ -129,13 +136,13 @@ The i18n template translation process has four phases:
|
|||
|
||||
1. Mark static text messages in your component templates for translation.
|
||||
|
||||
2. An Angular i18n tool extracts the marked text into an industry standard translation source file.
|
||||
2. Create translation files: use the Angular CLI `i18n` tool to extract the marked text into an industry-standard translation source file.
|
||||
|
||||
3. A translator edits that file, translating the extracted text into the target language,
|
||||
and returns the file to you.
|
||||
3. Edit the translation files to translate the extracted text into the target language.
|
||||
|
||||
4. The Angular compiler imports the completed translation files,
|
||||
replaces the original messages with translated text, and generates a new version of the app
|
||||
4. Merge the completed translation file into the app.
|
||||
Use the Angular CLI `build` tool to compile the app, choosing compiler options to import the completed translation files,
|
||||
replace the original messages with translated text, and generate 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.
|
||||
|
|
@ -281,16 +288,14 @@ The `<ng-container>` is transformed into an html comment:
|
|||
</code-example>
|
||||
|
||||
{@a translate-attributes}
|
||||
## Add i18n translation attributes
|
||||
### Translate attributes
|
||||
|
||||
You also can translate attributes.
|
||||
For example, assume that your template has an image with a `title` attribute:
|
||||
Displayed text is sometimes supplied as the value of an attribute, rather than the content of tag.
|
||||
For example, if your template has an image with a `title` attribute, the text value of the `title` attribute needs to be translated.
|
||||
|
||||
<code-example path="i18n/doc-files/app.component.html" region="i18n-title" title="src/app/app.component.html" linenums="false">
|
||||
</code-example>
|
||||
|
||||
This `title` attribute needs to be translated.
|
||||
|
||||
To mark an attribute for translation, add an attribute in the form of `i18n-x`,
|
||||
where `x` is the name of the attribute to translate. The following example shows how to mark the
|
||||
`title` attribute for translation by adding the `i18n-title` attribute on the `img` tag:
|
||||
|
|
@ -303,10 +308,14 @@ This technique works for any attribute of any element.
|
|||
You also can assign a meaning, description, and id with the `i18n-x="<meaning>|<description>@@<id>"`
|
||||
syntax.
|
||||
|
||||
{@a plural-ICU}
|
||||
## Translate singular and plural
|
||||
## Regular expressions for plurals and selections
|
||||
|
||||
Different languages have different pluralization rules.
|
||||
Different languages have different pluralization rules and grammatical constructions that add
|
||||
complexity to the translation task.
|
||||
You can use regular expressions with the `plural` and `select` clauses to provide patterns that aid translation in these cases.
|
||||
|
||||
{@a plural-ICU}
|
||||
### Pluralization
|
||||
|
||||
Suppose that you want to say that something was "updated x minutes ago".
|
||||
In English, depending upon the number of minutes, you could display "just now", "one minute ago",
|
||||
|
|
@ -359,12 +368,12 @@ for two, three, or any other number if the pluralization rules were different. F
|
|||
</div>
|
||||
|
||||
{@a select-ICU}
|
||||
## Select among alternative text messages
|
||||
### Select among alternative text messages
|
||||
|
||||
If your template needs to display different text messages depending on the value of a variable, you
|
||||
need to translate all of those alternative text messages.
|
||||
|
||||
You can handle this with a `select` ICU expression. It is similar to the `plural` ICU expressions
|
||||
You can handle this with a `select` ICU expression. It is similar to the `plural` expressions
|
||||
except that you choose among alternative translations based on a string value instead of a number,
|
||||
and you define those string values.
|
||||
|
||||
|
|
@ -376,7 +385,7 @@ The message maps those values to the appropriate translations:
|
|||
</code-example>
|
||||
|
||||
{@a nesting-ICUS}
|
||||
## Nesting plural and select ICU expressions
|
||||
### Nesting plural and select ICU expressions
|
||||
|
||||
You can also nest different ICU expressions together, as shown in this example:
|
||||
|
||||
|
|
@ -384,20 +393,18 @@ You can also nest different ICU expressions together, as shown in this example:
|
|||
</code-example>
|
||||
|
||||
{@a ng-xi18n}
|
||||
## Create a translation source file with _ng xi18n_
|
||||
{@a ng-xi18n-options}
|
||||
|
||||
Use the `ng xi18n` command provided by the CLI to extract the text messages marked with `i18n` into
|
||||
a translation source file.
|
||||
## Create a translation source file
|
||||
|
||||
When your app is ready, you can use the Angular CLI to extract the text messages marked with `i18n` into a translation source file.
|
||||
Open a terminal window at the root of the app project and enter the `ng xi18n` command:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng xi18n
|
||||
</code-example>
|
||||
|
||||
By default, the tool generates a translation file named `messages.xlf` in the
|
||||
<a href="https://en.wikipedia.org/wiki/XLIFF">XML Localization Interchange File Format
|
||||
(XLIFF, version 1.2)</a>.
|
||||
By default, the `ng xi18n` command creates a file named `messages.xlf` in your `src/` folder.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
|
|
@ -411,9 +418,20 @@ For more information, see the [Angular Ahead-of-Time Webpack Plugin documentatio
|
|||
</div>
|
||||
|
||||
{@a other-formats}
|
||||
### Other translation formats
|
||||
### Output options
|
||||
|
||||
Angular i18n tooling supports three translation formats:
|
||||
You can supply command options 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, specify the output path:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng xi18n --output-path src/locale
|
||||
</code-example>
|
||||
|
||||
By default, the Angular i18n tool generates a translation file named `messages.xlf` in the
|
||||
<a href="https://en.wikipedia.org/wiki/XLIFF">XML Localization Interchange File Format
|
||||
(XLIFF, version 1.2)</a>.
|
||||
|
||||
The tool supports three translation formats:
|
||||
* XLIFF 1.2 (default)
|
||||
* XLIFF 2
|
||||
* <a href="http://cldr.unicode.org/development/development-process/design-proposals/xmb" >XML Message
|
||||
|
|
@ -437,20 +455,8 @@ The sample in this guide uses the default XLIFF 1.2 format.
|
|||
|
||||
</div>
|
||||
|
||||
{@a ng-xi18n-options}
|
||||
### Other options
|
||||
|
||||
You can specify the output path used by the CLI to extract your translation source file with
|
||||
the parameter `--output-path`:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
|
||||
ng xi18n --output-path locale
|
||||
|
||||
</code-example>
|
||||
|
||||
You can change the name of the translation source file that is generated by the extraction tool with
|
||||
the parameter `--outFile`:
|
||||
the `--outFile` command option:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
|
||||
|
|
@ -458,7 +464,7 @@ the parameter `--outFile`:
|
|||
|
||||
</code-example>
|
||||
|
||||
You can specify the base locale of your app with the parameter `--i18n-locale`:
|
||||
You can specify the base locale of your app with the`--i18n-locale` command option:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
|
||||
|
|
@ -471,12 +477,11 @@ file. This information is not used by Angular, but external translation tools ma
|
|||
|
||||
|
||||
{@a translate}
|
||||
## Translate text messages
|
||||
## Translate the source text
|
||||
|
||||
The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src`
|
||||
folder.
|
||||
|
||||
The next step is to translate this source file into the specific language
|
||||
The next step is to translate the display strings in this source file into language-specific
|
||||
translation files. The example in this guide creates a French translation file.
|
||||
|
||||
{@a localization-folder}
|
||||
|
|
@ -556,9 +561,9 @@ This sample file is easy to translate without a special editor or knowledge of F
|
|||
</div>
|
||||
|
||||
{@a translate-plural-select}
|
||||
## Translate plural and select expressions
|
||||
## Translating plural and select expressions
|
||||
|
||||
_Plural_ and _select_ ICU expressions are extracted separately, so they require special attention
|
||||
The _plural_ and _select_ ICU expressions are extracted separately, so they require special attention
|
||||
when preparing for translation.
|
||||
|
||||
Look for these expressions in relation to other translation units that you recognize from
|
||||
|
|
@ -650,7 +655,9 @@ 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:
|
||||
translation file.
|
||||
|
||||
Provide the Angular compiler with three translation-specific pieces of information:
|
||||
|
||||
* The translation file.
|
||||
* The translation file format.
|
||||
|
|
@ -669,8 +676,8 @@ the JIT compiler or the AOT compiler.
|
|||
{@a merge-aot}
|
||||
### Merge with the AOT compiler
|
||||
|
||||
The AOT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast,
|
||||
ready-to-run application package.
|
||||
The [AOT compiler](guide/glossary#aot) is part of a build process that produces a small, fast,
|
||||
ready-to-run application package, typically for production.
|
||||
|
||||
When you internationalize with the AOT compiler, you must pre-build a separate application
|
||||
package for each language and serve the appropriate package based on either server-side language
|
||||
|
|
@ -717,35 +724,39 @@ sections of this guide:
|
|||
</code-example>
|
||||
|
||||
For production builds, you define a separate `production-fr` build configuration in
|
||||
your `angular.json`.
|
||||
the CLI configuration file, `angular.json`.
|
||||
|
||||
```
|
||||
"configurations": {
|
||||
...
|
||||
"production-fr": {
|
||||
"fileReplacements": [
|
||||
{
|
||||
"replace": "src/environments/environment.ts",
|
||||
"with": "src/environments/environment.prod.ts"
|
||||
...
|
||||
"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",
|
||||
}
|
||||
],
|
||||
"optimization": true,
|
||||
"outputHashing": "all",
|
||||
"sourceMap": false,
|
||||
"extractCss": true,
|
||||
"namedChunks": false,
|
||||
"aot": true,
|
||||
"extractLicenses": true,
|
||||
"vendorChunk": false,
|
||||
"buildOptimizer": 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": "my-project:build"
|
||||
},
|
||||
...
|
||||
}
|
||||
"configurations": {
|
||||
"production": {
|
||||
"browserTarget": "my-project:build:production"
|
||||
},
|
||||
"fr": {
|
||||
"browserTarget": "my-project:build:fr"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
```
|
||||
|
||||
The same configuration options can also be provided through the CLI with your existing `production` configuration.
|
||||
|
|
@ -757,12 +768,12 @@ The same configuration options can also be provided through the CLI with your ex
|
|||
{@a merge-jit}
|
||||
### Merge with the JIT compiler
|
||||
|
||||
The JIT compiler compiles the app in the browser as the app loads.
|
||||
Translation with the JIT compiler is a dynamic process of:
|
||||
The [JITcompiler](guide/glossary#jit) compiles your app in the browser as the app loads.
|
||||
To support translation with the JIT compiler, you must do the following:
|
||||
|
||||
1. Importing the appropriate language translation file as a string constant.
|
||||
2. Creating corresponding translation providers for the JIT compiler.
|
||||
3. Bootstrapping the app with those providers.
|
||||
1. Import the appropriate language translation file as a string constant.
|
||||
2. Create corresponding translation providers for the JIT compiler.
|
||||
3. Bootstrap the app with those providers.
|
||||
|
||||
Three providers tell the JIT compiler how to translate the template texts for a particular language
|
||||
while compiling the app:
|
||||
|
|
@ -772,7 +783,7 @@ while compiling the app:
|
|||
* `LOCALE_ID` is the locale of the target language.
|
||||
|
||||
The Angular `bootstrapModule` method has a second `compilerOptions` parameter that can influence the
|
||||
behavior of the compiler. You can use it to provide the translation providers:
|
||||
behavior of the compiler. You can use it to specify the translation providers:
|
||||
|
||||
<code-example path="i18n/doc-files/main.2.ts" title="src/main.ts">
|
||||
</code-example>
|
||||
|
|
@ -812,3 +823,25 @@ error:
|
|||
|
||||
<code-example path="i18n/doc-files/main.3.ts" title="src/main.ts">
|
||||
</code-example>
|
||||
|
||||
### Build for multiple locales
|
||||
|
||||
When you build your application for different locales, change the output path along with the i18n options using the `--outputPath` option, 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://myapp.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",
|
||||
}
|
||||
```
|
||||
|
||||
For more details about how to create scripts to generate an app in multiple languages and how to set up Apache 2 to serve them from different subdirectories, read [this tutorial by Philippe Martin](https://medium.com/@feloy/deploying-an-i18n-angular-app-with-angular-cli-fc788f17e358#.1xq4iy6fp).
|
||||
|
|
|
|||
Loading…
Reference in New Issue