honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: integrate material from cli wiki (#25732) 

PR Close #25732
This commit is contained in:
Judy Bogart 2018-08-29 13:56:23 -07:00 committed by Kara Erickson
parent 927323f24e
commit f37cf52b4c
1 changed files with 113 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
aio/content/guide/i18n.md
View File

@ -10,14 +10,21 @@ an AOT-compiled app, translated into French.
{@a angular-i18n} {@a angular-i18n}
## Angular and 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: Angular simplifies the following aspects of internationalization:
* Displaying dates, number, percentages, and currencies in a local format. * 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 plural forms of words.
* Handling alternative text. * Handling alternative text.
This document focuses on [**Angular CLI**](https://cli.angular.io/) projects, in which the Angular 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.
CLI generates most of the boilerplate necessary to write your app 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} {@a setting-up-locale}
## Setting up the locale of your app ## 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. 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, 3. Edit the translation files to translate the extracted text into the target language.
and returns the file to you.
4. The Angular compiler imports the completed translation files, 4. Merge the completed translation file into the app.
replaces the original messages with translated text, and generates a new version of 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. in the target language.
You need to build and deploy a separate version of the app for each supported 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> </code-example>
{@a translate-attributes} {@a translate-attributes}
## Add i18n translation attributes ### Translate attributes
You also can translate attributes. Displayed text is sometimes supplied as the value of an attribute, rather than the content of tag.
For example, assume that your template has an image with a `title` attribute: 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 path="i18n/doc-files/app.component.html" region="i18n-title" title="src/app/app.component.html" linenums="false">
</code-example> </code-example>
This `title` attribute needs to be translated.
To mark an attribute for translation, add an attribute in the form of `i18n-x`, 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 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: `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>"` You also can assign a meaning, description, and id with the `i18n-x="<meaning>|<description>@@<id>"`
syntax. syntax.
{@a plural-ICU} ## Regular expressions for plurals and selections
## Translate singular and plural
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". 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", 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> </div>
{@a select-ICU} {@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 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. 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, except that you choose among alternative translations based on a string value instead of a number,
and you define those string values. and you define those string values.
@ -376,7 +385,7 @@ The message maps those values to the appropriate translations:
</code-example> </code-example>
{@a nesting-ICUS} {@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: 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> </code-example>
{@a ng-xi18n} {@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 ## Create a translation source file
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: Open a terminal window at the root of the app project and enter the `ng xi18n` command:
<code-example language="sh" class="code-shell"> <code-example language="sh" class="code-shell">
ng xi18n ng xi18n
</code-example> </code-example>
By default, the tool generates a translation file named `messages.xlf` in the By default, the `ng xi18n` command creates a file named `messages.xlf` in your `src/` folder.
<a href="https://en.wikipedia.org/wiki/XLIFF">XML Localization Interchange File Format
(XLIFF, version 1.2)</a>.
<div class="alert is-helpful"> <div class="alert is-helpful">
@ -411,9 +418,20 @@ For more information, see the [Angular Ahead-of-Time Webpack Plugin documentatio
</div> </div>
{@a other-formats} {@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 1.2 (default)
* XLIFF 2 * XLIFF 2
* <a href="http://cldr.unicode.org/development/development-process/design-proposals/xmb" >XML Message * <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> </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 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"> <code-example language="sh" class="code-shell">
@ -458,7 +464,7 @@ the parameter `--outFile`:
</code-example> </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"> <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} {@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` The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src`
folder. folder.
The next step is to translate the display strings in this source file into language-specific
The next step is to translate this source file into the specific language
translation files. The example in this guide creates a French translation file. translation files. The example in this guide creates a French translation file.
{@a localization-folder} {@a localization-folder}
@ -556,9 +561,9 @@ This sample file is easy to translate without a special editor or knowledge of F
</div> </div>
{@a translate-plural-select} {@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. when preparing for translation.
Look for these expressions in relation to other translation units that you recognize from 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 ## Merge the completed translation file into the app
To merge the translated text into component templates, compile the app with the completed 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.
* The translation file format. * The translation file format.
@ -669,8 +676,8 @@ the JIT compiler or the AOT compiler.
{@a merge-aot} {@a merge-aot}
### Merge with the AOT compiler ### Merge with the AOT compiler
The AOT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast, The [AOT compiler](guide/glossary#aot) is part of a build process that produces a small, fast,
ready-to-run application package. ready-to-run application package, typically for production.
When you internationalize with the AOT compiler, you must pre-build a separate application 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 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> </code-example>
For production builds, you define a separate `production-fr` build configuration in For production builds, you define a separate `production-fr` build configuration in
your `angular.json`. the CLI configuration file, `angular.json`.
``` ```
"configurations": { ...
... "architect": {
"production-fr": { "build": {
"fileReplacements": [ "builder": "@angular-devkit/build-angular:browser",
{ "options": { ... },
"replace": "src/environments/environment.ts", "configurations": {
"with": "src/environments/environment.prod.ts" "fr": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
"i18nMissingTranslation": "error",
} }
], // ...
"optimization": true, "serve": {
"outputHashing": "all", "builder": "@angular-devkit/build-angular:dev-server",
"sourceMap": false, "options": {
"extractCss": true, "browserTarget": "my-project:build"
"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"
}, },
... "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. 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} {@a merge-jit}
### Merge with the JIT compiler ### Merge with the JIT compiler
The JIT compiler compiles the app in the browser as the app loads. The [JITcompiler](guide/glossary#jit) compiles your app in the browser as the app loads.
Translation with the JIT compiler is a dynamic process of: To support translation with the JIT compiler, you must do the following:
1. Importing the appropriate language translation file as a string constant. 1. Import the appropriate language translation file as a string constant.
2. Creating corresponding translation providers for the JIT compiler. 2. Create corresponding translation providers for the JIT compiler.
3. Bootstrapping the app with those providers. 3. Bootstrap the app with those providers.
Three providers tell the JIT compiler how to translate the template texts for a particular language Three providers tell the JIT compiler how to translate the template texts for a particular language
while compiling the app: while compiling the app:
@ -772,7 +783,7 @@ while compiling the app:
* `LOCALE_ID` is the locale of the target language. * `LOCALE_ID` is the locale of the target language.
The Angular `bootstrapModule` method has a second `compilerOptions` parameter that can influence the 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 path="i18n/doc-files/main.2.ts" title="src/main.ts">
</code-example> </code-example>
@ -812,3 +823,25 @@ error:
<code-example path="i18n/doc-files/main.3.ts" title="src/main.ts"> <code-example path="i18n/doc-files/main.3.ts" title="src/main.ts">
</code-example> </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).