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

docs: initial Ivy i18n guide updates (#33762) 

PR Close #33762
This commit is contained in:
Charles Lyding 2019-11-12 12:06:00 -05:00 committed by Matias Niemelä
parent 31e2bdffa8
commit 56f33bc266
3 changed files with 52 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
aio/content/examples/i18n/doc-files/app.locale_data.ts
View File

@ -2,6 +2,6 @@
import { registerLocaleData } from '@angular/common';
import localeFr from '@angular/common/locales/fr';
// the second parameter 'fr' is optional
registerLocaleData(localeFr, 'fr');
// the second parameter 'fr-FR' is optional
registerLocaleData(localeFr, 'fr-FR');
// #enddocregion import-locale

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

@ -25,6 +25,16 @@ After you have set up your app to use i18n, the CLI can help you with the follow
* Building and serving the app for a given locale, using the translated text.
* Creating multiple language versions of your app.
{@a setting-up-cli}
## Setting up localization with the Angular CLI
The first step to setting up localization when using the Angular CLI is to add the `@angular/localize` package to the project. This will install the package within your project as well as
initialize the project to take advantage of Angular's localization features.
<code-example language="sh" class="code-shell">
ng add @angular/localize
</code-example>
{@a setting-up-locale}
## Setting up the locale of your app
@ -76,12 +86,12 @@ time of writing:
## i18n pipes
Angular pipes can help you with internationalization: the `DatePipe`, `CurrencyPipe`, `DecimalPipe`
and `PercentPipe` use locale data to format data based on the `LOCALE_ID`.
and `PercentPipe` use locale data to format data based on the `LOCALE_ID` dependency injection token.
By default, Angular only contains locale data for `en-US`. If you set the value of
`LOCALE_ID` to another locale, you must import locale data for that new locale.
The CLI imports the locale data for you when you use the parameter `--configuration` with `ng serve` and
`ng build`.
By default, Angular only contains locale data for `en-US`.
The CLI automatically includes the locale data and sets the `LOCALE_ID` value for you when you use the
parameter `--i18nLocale` or option `i18nLocale` with `ng serve` and `ng build`.
However, if you manually set the value of `LOCALE_ID` to another locale, you must import locale data for that new locale.
If you want to import locale data for other languages, you can do it manually:
@ -98,6 +108,7 @@ locale id "fr-FR" instead of "fr".
The files in `@angular/common/locales` contain most of the locale data that you
need, but some advanced formatting options might only be available in the extra dataset that you can
import from `@angular/common/locales/extra`. An error message informs you when this is the case.
Ivy will automatically include the extra locale data if the locale was configured via `i18nLocale`.
<code-example path="i18n/doc-files/app.locale_data_extra.ts" region="import-locale-extra" header="src/app/app.module.ts"></code-example>
@ -126,10 +137,10 @@ 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-aot), or specifying the following command options.
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.
* `--i18nFile`=*path to the translation file*
* `--i18nFormat`=*format of 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.
@ -381,17 +392,6 @@ Open a terminal window at the root of the app project and run the CLI command `x
By default, the command creates a file named `messages.xlf` in your project's root directory.
<div class="alert is-helpful">
If you don't use the CLI, you have two options:
* You can use the `ng-xi18n` tool directly from the `@angular/compiler-cli` package.
For more information, see the [`ng xi18n` command documentation](cli/xi18n).
* You can use the CLI Webpack plugin `AngularCompilerPlugin` from the `@ngtools/webpack` package.
Set the parameters `i18nOutFile` and `i18nOutFormat` to trigger the extraction.
For more information, see the [Angular Ahead-of-Time Webpack Plugin documentation](https://github.com/angular/angular-cli/tree/master/packages/ngtools/webpack).
</div>
{@a other-formats}
### Output options
@ -412,13 +412,13 @@ The command can read and write files in three translation formats:
* <a href="http://cldr.unicode.org/development/development-process/design-proposals/xmb" >XML Message
Bundle (XMB)</a>
You can specify the translation format explicitly with the `--i18nFormat` command option, as illustrated in
You can specify the translation format explicitly with the `--format` command option, as illustrated in
these example commands:
<code-example language="sh" class="code-shell">
ng xi18n --i18n-format=xlf
ng xi18n --i18n-format=xlf2
ng xi18n --i18n-format=xmb
ng xi18n --format=xlf
ng xi18n --format=xlf2
ng xi18n --format=xmb
</code-example>
The sample in this guide uses the default XLIFF 1.2 format.
@ -454,8 +454,7 @@ file. This information is not used by Angular, but external translation tools ma
{@a translate}
## Translate the source text
The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src`
folder.
By default, the `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src` folder.
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.
@ -630,18 +629,17 @@ translation 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`.
How you provide this information depends upon whether you compile with
the JIT compiler or the AOT compiler.
* With [AOT](guide/i18n#merge-aot), you pass the information as configuration settings.
* With [JIT](guide/i18n#merge-jit), you provide the information at bootstrap time.
{@a merge-aot}
### Merge with the AOT compiler
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.
ready-to-run application package, with Ivy it is now used for both production and development.
<div class="alert is-important">
Ivy does not support merging i18n translations when using JIT mode.
If you [disable Ivy](guide/ivy#opting-out-of-ivy-in-version-9) and are using JIT mode,
additional information regarding translation merging can be found [here](https://v8.angular.io/guide/i18n#merge-with-the-jit-compiler).
</div>
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
@ -650,7 +648,7 @@ detection or URL parameters.
To instruct the AOT compiler to use your translation configuration, set the three "i18n" build configuration options in your CLI configuration file, `angular.json`.
* `i18nFile`: the path to the translation file.
* `i18nFormat`: the format of 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.
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.
@ -689,8 +687,11 @@ sections of this guide:
ng serve --configuration=fr
</code-example>
For production builds, you define a separate `production-fr` build configuration in
the CLI configuration file, `angular.json`.
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>
```
...
@ -733,34 +734,6 @@ The same configuration options can also be provided through the CLI with your ex
ng build --prod --i18n-file src/locale/messages.fr.xlf --i18n-format xlf --i18n-locale fr
</code-example>
{@a merge-jit}
### Merge with the JIT compiler
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. 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:
* `TRANSLATIONS` is a string containing the content of the translation file.
* `TRANSLATIONS_FORMAT` is the format of the file: `xlf`, `xlf2`, or `xtb`.
* `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 specify the translation providers:
<code-example path="i18n/doc-files/main.2.ts" header="src/main.ts">
</code-example>
Then provide the `LOCALE_ID` in the main module:
<code-example path="i18n/doc-files/app.module.ts" header="src/app/app.module.ts"></code-example>
{@a missing-translation}
### Report missing translations
@ -785,13 +758,6 @@ You specify the warning level in the `configurations` section of your Angular CL
}
```
If you use the JIT compiler, specify the warning level in the compiler config at bootstrap by adding
the 'MissingTranslationStrategy' property. The example below shows how to set the warning level to
error.
<code-example path="i18n/doc-files/main.3.ts" header="src/main.ts">
</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.

12
aio/content/guide/ivy.md
View File

@ -15,6 +15,7 @@ Learn more about the [Compiler](https://www.youtube.com/watch?v=anphffaCZrQ) and
AOT compilation with Ivy is faster and should be used by default.
In the `angular.json` workspace configuration file, set the default build options for your project to always use AOT compilation.
When using application internationalization (i18n) with Ivy, [translation merging](guide/i18n#merge) also requires the use of AOT compilation.
<code-example language="json" header="angular.json">
@ -118,6 +119,17 @@ To revert the compiler default, set the build option `aot: false` in the `angula
</div>
If you disable Ivy and the project uses internationalization, you can also remove the `@angular/localize` runtime component from the project's polyfills file located be default at `src/polyfills.ts`.
To remove, delete the `import '@angular/localize/init';` line from the polyfills file.
<code-example language="typescript" header="polyfills.ts">
/***************************************************************************************************
* Load `$localize` onto the global scope - used if i18n tags appear in Angular templates.
*/
import '@angular/localize/init';
</code-example>
{@a using-ssr-without-angular-ivy}
### Using SSR without Ivy