Olivier Combe
Igor Minar
parent
77ef527993
commit
be994496cd
|
|
@ -2,5 +2,6 @@
|
|||
import { registerLocaleData } from '@angular/common';
|
||||
import localeFr from '@angular/common/locales/fr';
|
||||
|
||||
registerLocaleData(localeFr);
|
||||
// the second parameter 'fr' is optional
|
||||
registerLocaleData(localeFr, 'fr');
|
||||
// #enddocregion import-locale
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
// #docregion import-locale-extra
|
||||
import { registerLocaleData } from '@angular/common';
|
||||
import localeFrCa from '@angular/common/locales/fr-CA';
|
||||
import localeFrCaExtra from '@angular/common/locales/extra/fr-CA';
|
||||
import localeFr from '@angular/common/locales/fr';
|
||||
import localeFrExtra from '@angular/common/locales/extra/fr';
|
||||
|
||||
registerLocaleData(localeFrCa, localeFrCaExtra);
|
||||
registerLocaleData(localeFr, 'fr-FR', localeFrExtra);
|
||||
// #enddocregion import-locale-extra
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@ See the <live-example downloadOnly name="i18n">i18n Example</live-example> for a
|
|||
an AOT-compiled app, translated into French.
|
||||
|
||||
{@a angular-i18n}
|
||||
|
||||
## Angular and i18n
|
||||
|
||||
Angular simplifies the following aspects of internationalization:
|
||||
|
|
@ -62,6 +61,23 @@ For more information about Unicode locale identifiers, see the
|
|||
For a complete list of locales supported by Angular, see
|
||||
[the Angular repository](https://github.com/angular/angular/tree/master/packages/common/locales).
|
||||
|
||||
The locale identifiers used by CLDR and Angular are based on [BCP47](http://www.rfc-editor.org/rfc/bcp/bcp47.txt).
|
||||
These specifications change over time; the following table maps previous identifiers to current ones at
|
||||
time of writing:
|
||||
|
||||
| Locale name | Old locale id | New locale id |
|
||||
|-------------------------------|-------------------|---------------|
|
||||
| Indonesian | in | id |
|
||||
| Hebrew | iw | he |
|
||||
| Romanian Moldova | mo | ro-MD |
|
||||
| Norwegian Bokmål | no, no-NO | nb |
|
||||
| Serbian Latin | sh | sr-Latn |
|
||||
| Filipino | tl | fil |
|
||||
| Portuguese Brazil | pt-BR | pt |
|
||||
| Chinese Simplified | zh-cn, zh-Hans-CN | zh-Hans |
|
||||
| Chinese Traditional | zh-tw, zh-Hant-TW | zh-Hant |
|
||||
| Chinese Traditional Hong Kong | zh-hk | zh-Hant-HK |
|
||||
|
||||
|
||||
## i18n pipes
|
||||
|
||||
|
|
@ -78,6 +94,14 @@ If you want to import locale data for other languages, you can do it manually:
|
|||
<code-example path="i18n/doc-files/app.locale_data.ts" region="import-locale" title="src/app/app.module.ts" linenums="false">
|
||||
</code-example>
|
||||
|
||||
The first parameter is an object containing the locale data imported from `@angular/common/locales`.
|
||||
By default, the imported locale data is registered with the locale id that is defined in the Angular
|
||||
locale data itself.
|
||||
If you want to register the imported locale data with another locale id, use the second parameter to
|
||||
specify a custom locale id. For example, Angular's locale data defines the locale id for French as
|
||||
"fr". You can use the second parameter to associate the imported French locale data with the custom
|
||||
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.
|
||||
|
|
@ -118,7 +142,6 @@ in the target language.
|
|||
You need to build and deploy a separate version of the app for each supported language.
|
||||
|
||||
{@a i18n-attribute}
|
||||
|
||||
### Mark text with the i18n attribute
|
||||
|
||||
The Angular `i18n` attribute marks translatable content. Place it on every element tag whose fixed
|
||||
|
|
@ -144,7 +167,6 @@ To mark the greeting for translation, add the `i18n` attribute to the `<h1>` tag
|
|||
|
||||
|
||||
{@a help-translator}
|
||||
|
||||
### Help the translator with a description and meaning
|
||||
|
||||
To translate a text message accurately, the translator may need additional information or context.
|
||||
|
|
@ -175,7 +197,6 @@ text messages with different descriptions (not different meanings), then they ar
|
|||
|
||||
|
||||
{@a custom-id}
|
||||
|
||||
### Set a custom id for persistence and maintenance
|
||||
|
||||
The angular i18n extractor tool generates a file with a translation unit entry for each `i18n`
|
||||
|
|
@ -250,7 +271,6 @@ the same text, `Bonjour`:
|
|||
|
||||
|
||||
{@a no-element}
|
||||
|
||||
### Translate text without creating an element
|
||||
|
||||
If there is a section of text that you would like to translate, you can wrap it in a `<span>` tag.
|
||||
|
|
@ -262,7 +282,6 @@ The `<ng-container>` is transformed into an html comment:
|
|||
</code-example>
|
||||
|
||||
{@a translate-attributes}
|
||||
|
||||
## Add i18n translation attributes
|
||||
|
||||
You also can translate attributes.
|
||||
|
|
@ -286,7 +305,6 @@ You also can assign a meaning, description, and id with the `i18n-x="<meaning>|<
|
|||
syntax.
|
||||
|
||||
{@a plural-ICU}
|
||||
|
||||
## Translate singular and plural
|
||||
|
||||
Different languages have different pluralization rules.
|
||||
|
|
@ -342,7 +360,6 @@ for two, three, or any other number if the pluralization rules were different. F
|
|||
</div>
|
||||
|
||||
{@a select-ICU}
|
||||
|
||||
## Select among alternative text messages
|
||||
|
||||
If your template needs to display different text messages depending on the value of a variable, you
|
||||
|
|
@ -360,7 +377,6 @@ The message maps those values to the appropriate translations:
|
|||
</code-example>
|
||||
|
||||
{@a nesting-ICUS}
|
||||
|
||||
## Nesting plural and select ICU expressions
|
||||
|
||||
You can also nest different ICU expressions together, as shown in this example:
|
||||
|
|
@ -369,7 +385,6 @@ 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_
|
||||
|
||||
Use the `ng xi18n` command provided by the CLI to extract the text messages marked with `i18n` into
|
||||
|
|
@ -394,7 +409,6 @@ package, or you can manually use the CLI Webpack plugin `ExtractI18nPlugin` from
|
|||
</div>
|
||||
|
||||
{@a other-formats}
|
||||
|
||||
### Other translation formats
|
||||
|
||||
Angular i18n tooling supports three translation formats:
|
||||
|
|
@ -422,7 +436,6 @@ 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
|
||||
|
|
@ -456,7 +469,6 @@ file. This information is not used by Angular, but external translation tools ma
|
|||
|
||||
|
||||
{@a translate}
|
||||
|
||||
## Translate text messages
|
||||
|
||||
The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src`
|
||||
|
|
@ -466,7 +478,6 @@ 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.
|
||||
|
||||
{@a localization-folder}
|
||||
|
||||
### Create a localization folder
|
||||
|
||||
Most apps are translated into more than one other language. For this reason, it is standard practice
|
||||
|
|
@ -500,7 +511,6 @@ For this example:
|
|||
If you were translating to other languages, you would repeat these steps for each target language.
|
||||
|
||||
{@a translate-text-nodes}
|
||||
|
||||
### Translate text nodes
|
||||
|
||||
In a large translation project, you would send the `messages.fr.xlf` file to a French translator who
|
||||
|
|
@ -544,7 +554,6 @@ 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
|
||||
|
||||
_Plural_ and _select_ ICU expressions are extracted separately, so they require special attention
|
||||
|
|
@ -555,7 +564,6 @@ elsewhere in the source template. In this example, you know the translation unit
|
|||
must be just below the translation unit for the logo.
|
||||
|
||||
{@a translate-plural}
|
||||
|
||||
### Translate _plural_
|
||||
|
||||
To translate a `plural`, translate its ICU format match values:
|
||||
|
|
@ -567,7 +575,6 @@ You can add or remove plural cases, with each language having its own cardinalit
|
|||
[CLDR plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html).)
|
||||
|
||||
{@a translate-select}
|
||||
|
||||
### Translate _select_
|
||||
|
||||
Below is the content of our example `select` ICU expression in the component template:
|
||||
|
|
@ -598,7 +605,6 @@ Here they are together, after translation:
|
|||
</code-example>
|
||||
|
||||
{@a translate-nested}
|
||||
|
||||
### Translate a nested expression
|
||||
|
||||
A nested expression is similar to the previous examples. As in the previous example, there are
|
||||
|
|
@ -621,7 +627,6 @@ The entire template translation is complete. The next section describes how to l
|
|||
into the app.
|
||||
|
||||
{@a app-pre-translation}
|
||||
|
||||
### The app and its translation file
|
||||
|
||||
The sample app and its translation file are now as follows:
|
||||
|
|
@ -640,7 +645,6 @@ The sample app and its translation file are now as follows:
|
|||
</code-tabs>
|
||||
|
||||
{@a merge}
|
||||
|
||||
## Merge the completed translation file into the app
|
||||
|
||||
To merge the translated text into component templates, compile the app with the completed
|
||||
|
|
@ -656,12 +660,11 @@ 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#aot), you pass the information as a CLI parameter.
|
||||
* With [JIT](guide/i18n#jit), you provide the information at bootstrap time.
|
||||
* With [AOT](guide/i18n#merge-aot), you pass the information as a CLI parameter.
|
||||
* With [JIT](guide/i18n#merge-jit), you provide the information at bootstrap time.
|
||||
|
||||
|
||||
{@a aot}
|
||||
|
||||
{@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,
|
||||
|
|
@ -685,8 +688,7 @@ guide:
|
|||
ng serve --aot --i18nFile=src/locale/messages.fr.xlf --i18nFormat=xlf --locale=fr
|
||||
</code-example>
|
||||
|
||||
{@a jit}
|
||||
|
||||
{@a merge-jit}
|
||||
### Merge with the JIT compiler
|
||||
|
||||
The JIT compiler compiles the app in the browser as the app loads.
|
||||
|
|
@ -713,3 +715,29 @@ Then provide the `LOCALE_ID` in the main module:
|
|||
|
||||
<code-example path="i18n/doc-files/app.module.ts" title="src/app/app.module.ts" linenums="false">
|
||||
</code-example>
|
||||
|
||||
|
||||
{@a missing-translation}
|
||||
### Report missing translations
|
||||
By default, when a translation is missing, the build succeeds but generates a warning such as
|
||||
`Missing translation for message "foo"`. You can configure the level of warning that is generated by
|
||||
the Angular compiler:
|
||||
|
||||
* Error: throw an error. If you are using AOT compilation, the build will fail. If you are using JIT
|
||||
compilation, the app will fail to load.
|
||||
* Warning (default): show a 'Missing translation' warning in the console or shell.
|
||||
* Ignore: do nothing.
|
||||
|
||||
If you use the AOT compiler, specify the warning level by using the CLI parameter
|
||||
`--missingTranslation`. The example below shows how to set the warning level to error:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng serve --aot --missingTranslation=error
|
||||
</code-example>
|
||||
|
||||
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" title="src/main.ts">
|
||||
</code-example>
|
||||
|
|
|
|||
|
|
@ -9,21 +9,95 @@
|
|||
import {InjectionToken} from '../di/injection_token';
|
||||
|
||||
/**
|
||||
* Provide this token to set the locale of your application.
|
||||
* It is used for i18n extraction, by i18n pipes (DatePipe, I18nPluralPipe, CurrencyPipe,
|
||||
* DecimalPipe and PercentPipe) and by ICU expressions.
|
||||
*
|
||||
* See the {@linkDocs guide/i18n#setting-up-locale i18n guide} for more information.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```typescript
|
||||
* import { LOCALE_ID } from '@angular/core';
|
||||
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
|
||||
* import { AppModule } from './app/app.module';
|
||||
*
|
||||
* platformBrowserDynamic().bootstrapModule(AppModule, {
|
||||
* providers: [{provide: LOCALE_ID, useValue: 'en-US' }]
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @experimental i18n support is experimental.
|
||||
*/
|
||||
export const LOCALE_ID = new InjectionToken<string>('LocaleId');
|
||||
|
||||
/**
|
||||
* Use this token at bootstrap to provide the content of your translation file (`xtb`,
|
||||
* `xlf` or `xlf2`) when you want to translate your application in another language.
|
||||
*
|
||||
* See the {@linkDocs guide/i18n#merge i18n guide} for more information.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```typescript
|
||||
* import { TRANSLATIONS } from '@angular/core';
|
||||
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
|
||||
* import { AppModule } from './app/app.module';
|
||||
*
|
||||
* // content of your translation file
|
||||
* const translations = '....';
|
||||
*
|
||||
* platformBrowserDynamic().bootstrapModule(AppModule, {
|
||||
* providers: [{provide: TRANSLATIONS, useValue: translations }]
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @experimental i18n support is experimental.
|
||||
*/
|
||||
export const TRANSLATIONS = new InjectionToken<string>('Translations');
|
||||
|
||||
/**
|
||||
* Provide this token at bootstrap to set the format of your {@link TRANSLATIONS}: `xtb`,
|
||||
* `xlf` or `xlf2`.
|
||||
*
|
||||
* See the {@linkDocs guide/i18n#merge i18n guide} for more information.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```typescript
|
||||
* import { TRANSLATIONS_FORMAT } from '@angular/core';
|
||||
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
|
||||
* import { AppModule } from './app/app.module';
|
||||
*
|
||||
* platformBrowserDynamic().bootstrapModule(AppModule, {
|
||||
* providers: [{provide: TRANSLATIONS_FORMAT, useValue: 'xlf' }]
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @experimental i18n support is experimental.
|
||||
*/
|
||||
export const TRANSLATIONS_FORMAT = new InjectionToken<string>('TranslationsFormat');
|
||||
|
||||
/**
|
||||
* Use this enum at bootstrap as an option of `bootstrapModule` to define the strategy
|
||||
* that the compiler should use in case of missing translations:
|
||||
* - Error: throw if you have missing translations.
|
||||
* - Warning (default): show a warning in the console and/or shell.
|
||||
* - Ignore: do nothing.
|
||||
*
|
||||
* See the {@linkDocs guide/i18n#missing-translation i18n guide} for more information.
|
||||
*
|
||||
* ### Example
|
||||
* ```typescript
|
||||
* import { MissingTranslationStrategy } from '@angular/core';
|
||||
* import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
|
||||
* import { AppModule } from './app/app.module';
|
||||
*
|
||||
* platformBrowserDynamic().bootstrapModule(AppModule, {
|
||||
* missingTranslation: MissingTranslationStrategy.Error
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @experimental i18n support is experimental.
|
||||
*/
|
||||
export enum MissingTranslationStrategy {
|
||||
|
|
|
|||
Loading…
Reference in New Issue