diff --git a/aio/content/guide/i18n.md b/aio/content/guide/i18n.md index 8424171fe33..572ce6f545c 100644 --- a/aio/content/guide/i18n.md +++ b/aio/content/guide/i18n.md @@ -3,88 +3,94 @@ {@searchKeywords i18n} {@a angular-i18n} -*Internationalization* (i18n) is the process of designing and preparing your app to be usable in different locales around the world. -*Localization* is the process of building versions of your app for different locales, including extracting text for translation into different languages, and formatting data for particular locales. +*Internationalization* (i18n) is the process of designing and preparing your application to be usable in different locales around the world. +*Localization* is the process of building versions of your application for different locales, including extracting text for translation into different languages, and formatting data for particular locales. -A *locale* identifies a region (such as a country) in which people speak a particular language or language variant. The locale determines the formatting and parsing of dates, times, numbers, and currencies as well as measurement units and the translated names for time zones, languages, and countries. +A *locale* identifies a region (such as a country) in which people speak a particular language or language variant. +The locale determines the formatting and parsing of dates, times, numbers, and currencies as well as measurement units and the translated names for time zones, languages, and countries.
-Create an adaptable user interface for all of your target locales that takes into consideration the differences in spacing for different languages. For details, see [How to approach internationalization](https://marketfinder.thinkwithgoogle.com/intl/en_us/guide/how-to-approach-i18n/#overview "How to approach internationalization"). +Create an adaptable user interface for all of your target locales that takes into consideration the differences in spacing for different languages. +For details, see [How to approach internationalization][ThinkwithgoogleMarketfinderIntlEnUsGuideHowToApproachI18nOverview].
Use Angular to internationalize your app: -* Use built-in pipes to display dates, numbers, percentages, and currencies in a local format. -* Mark text in component templates for translation. -* Mark plural forms of expressions for translation. -* Mark alternate text for translation. +* Use built-in pipes to display dates, numbers, percentages, and currencies in a local format. +* Mark text in component templates for translation. +* Mark plural forms of expressions for translation. +* Mark alternate text for translation. -After preparing your app for an international audience, use the [Angular CLI](cli) to localize your app by performing the following tasks: +After you prepare your application for an international audience, use the [Angular CLI][AioCliMain] to localize your application. +Complete the following tasks to localize your application. -* Use the CLI to extract marked text to a _source language_ file. -* Make a copy of this file for each language, and send these _translation files_ to a translator or service. -* Use the CLI to merge the finished translation files when building your app for one or more locales. +* Use the CLI to extract marked text to a *source language* file. +* Make a copy of this file for each language, and send these *translation files* to a translator or service. +* Use the CLI to merge the finished translation files when building your application for one or more locales.
- To explore the sample app with French translations used in this guide, see the . +To explore the sample application with French translations used in this guide, see .
## Prerequisites -To prepare your app for translations, you should have a basic understanding of the following: +To prepare your application for translations, you should have a basic understanding of the following subjects. -* [Templates](guide/glossary#template "Definition of a template") -* [Components](guide/glossary#component "Definition of a component") -* [Angular CLI](guide/glossary#command-line-interface-cli "Definition of CLI") command-line tool for managing the Angular development cycle -* [Extensible Markup Language (XML)](https://www.w3.org/XML/ "W3C: Extensible Markup Language (XML)") used for translation files +* [Templates][AioGuideGlossaryTemplate] +* [Components][AioGuideGlossaryComponent] +* [Angular CLI][AioGuideGlossaryCommandLineInterfaceCli] command-line tool for managing the Angular development cycle +* [Extensible Markup Language (XML)][W3Xml] used for translation files ## Steps to localize your app -To localize your app, follow these general steps: +To localize your application, complete the following general actions. -1. [Add the localize package](#setting-up-cli). -2. [Refer to locales by ID](#setting-up-locale). -3. [Format data based on locale](#i18n-pipes). -4. [Prepare templates for translations](#Template-translations). -5. [Work with translation files](#ng-xi18n). -6. [Merge translations into the app](#merge). -7. [Deploy multiple locales](#deploy-locales). +1. [Add the localize package][AioGuideI18nSettingUpCli]. +2. [Refer to locales by ID][AioGuideI18nSettingUpLocale]. +3. [Format data based on locale][AioGuideI18nPipes]. +4. [Prepare templates for translations][AioGuideI18nTemplatetranslations]. +5. [Work with translation files][AioGuideI18nNgXi18n]. +6. [Merge translations into the app][AioGuideI18nMerge]. +7. [Deploy multiple locales][AioGuideI18nDeployLocales]. -While following these steps, you can [explore the translated example app](#app-pre-translation). +While you follow the actions, [explore the translated example app][AioGuideI18nAppPreTranslation]. -The following are optional practices that may be required in special cases: +In special cases, the following actions are required. -* [Set the source locale manually](#set-source-manually) if you need to set the [LOCALE_ID](api/core/LOCALE_ID "API reference for LOCALE_ID") token. -* [Import global variants of the locale data](#import-locale) for extra locale data. -* [Manage marked text with custom IDs](#custom-id) if you require more control over matching translations. +* [Set the source locale manually][AioGuideI18nSetSourceManually], if you need to set the [LOCALE_ID][AioApiCoreLocaleId] token. +* [Import global variants of the locale data][AioGuideI18nImportLocale] for extra locale data. +* [Manage marked text with custom IDs][AioGuideI18nCustomId], if you require more control over matching translations. + + {@a setting-up-cli} {@a add-localize} ## Add the localize package -To take advantage of Angular's localization features, use the Angular CLI to add the `@angular/localize` package to your project: +To take advantage of the localization features of Angular, use the Angular CLI to add the `@angular/localize` package to your project. - ng add @angular/localize +ng add @angular/localize -This command updates your project's `package.json` and `polyfills.ts` files to import the `@angular/localize` package. +This command updates the `package.json` and `polyfills.ts` files of your project to import the `@angular/localize` package.
-For more information about `package.json` and polyfill packages, see [Workspace npm dependencies](guide/npm-packages). +For more information about `package.json` and polyfill packages, see [Workspace npm dependencies][AioGuideNpmPackages].
-If `@angular/localize` is not installed, the Angular CLI may generate an error when you try to build a localized version of your app. +If `@angular/localize` is not installed, the Angular CLI may generate an error when you try to build a localized version of your application. + + {@a setting-up-locale} - {@a setting-up-the-locale-of-your-app} ## Refer to locales by ID @@ -94,10 +100,10 @@ Refer to a locale using the Unicode *locale identifier* (ID), which specifies th
Unicode locale identifiers
-* For a list of language codes, see [ISO 639-2](https://www.loc.gov/standards/iso639-2/ "ISO 639-2 Registration Authority"). -* IDs conform to the Unicode Common Locale Data Repository (CLDR). -For more information about Unicode locale identifiers, see the [CLDR core specification](http://cldr.unicode.org/core-spec#Unicode_Language_and_Locale_Identifiers "CLDR - Unicode Common Locale Data Repository"). -* CLDR and Angular base their identifiers on [BCP47 tags](https://tools.ietf.org/html/bcp47 "BCP47 Tags for Identifying Languages"). +* For a list of language codes, see [ISO 639-2][LocStandardsIso6392]. +* IDs conform to the Unicode Common Locale Data Repository (CLDR). + For more information about Unicode locale identifiers, see [CLDR core specification][UnicodeCldrCoreSpecUnicodeLanguageAndLocaleIdentifiers]. +* CLDR and Angular base their identifiers on [BCP47 tags][RfcEditorInfoBcp47].
@@ -108,44 +114,50 @@ Angular uses this ID to find the correct corresponding locale data.
Many countries, such as France and Canada, use the same language (French, identified as `fr`) but differ in grammar, punctuation, and formats for currency, decimal numbers, and dates. -Use a more specific locale ID, such as French for Canada (`fr-CA`), when localizing your app. +Use a more specific locale ID, such as French for Canada (`fr-CA`), when localizing your application.
-Angular by default uses `en-US` (English in the United States) as your app's source locale. +Angular by default uses `en-US` (English in the United States) as the source locale of your application. -The [Angular repository](https://github.com/angular/angular/tree/master/packages/common/locales "Common locales in the Angular repository") includes common locales. -You can change your app's source locale for the build by setting the source locale in the `sourceLocale` field of your app's [workspace configuration](guide/workspace-config "Angular workspace configuration") file (`angular.json`). -The build process (described in [Merge translations into the app](#merge) in this guide) uses your app's `angular.json` file to automatically set the [`LOCALE_ID`](api/core/LOCALE_ID "API reference for LOCALE_ID") token and load the locale data. +The [Angular repository][GithubAngularAngularTreeMasterPackagesCommonLocales] includes common locales. +To change the source locale of your application for the build, set the source locale in the `sourceLocale` field in the [workspace configuration][AioGuideWorkspaceConfig] file (`angular.json`) of your application. +The build process (described in [Merge translations into the app][AioGuideI18nMerge] in this guide) uses the `angular.json` file of your application to automatically set the [`LOCALE_ID`][AioApiCoreLocaleId] token and load the locale data. + + {@a i18n-pipes} ## Format data based on locale -Angular provides the following built-in data transformation [pipes](guide/glossary#pipe "Definition of a pipe") that use the [`LOCALE_ID`](api/core/LOCALE_ID "API reference for LOCALE_ID") token to format data according to the locale's rules: +Angular provides the following built-in data transformation [pipes][AioGuideGlossaryPipe]. The data transformation pipes use the [`LOCALE_ID`][AioApiCoreLocaleId] token to format data based on rules of each locale. -* [`DatePipe`](api/common/DatePipe): Formats a date value. -* [`CurrencyPipe`](api/common/CurrencyPipe): Transforms a number to a currency string. -* [`DecimalPipe`](/api/common/DecimalPipe): Transforms a number into a decimal number string. -* [`PercentPipe`](api/common/PercentPipe): Transforms a number to a percentage string. +* [`DatePipe`][AioApiCommonDatepipe]: Formats a date value. +* [`CurrencyPipe`][AioApiCommonCurrencypipe]: Transforms a number to a currency string. +* [`DecimalPipe`][AioApiCommonDecimalpipe]: Transforms a number into a decimal number string. +* [`PercentPipe`][AioApiCommonPercentpipe]: Transforms a number to a percentage string. For example, `{{today | date}}` uses `DatePipe` to display the current date in the format for the locale in `LOCALE_ID`. To override the value of `LOCALE_ID`, add the `locale` parameter. For example, to force the currency to use `en-US` no matter which language-locale you set for `LOCALE_ID`, use this form: `{{amount | currency : 'en-US'}}`. -{@a Template-translations} + + +{@a template-translations} ## Prepare templates for translations -To translate your app's templates, you need to prepare the text for a translator or translation service by marking text, attributes, and other elements with the Angular `i18n` attribute. -Follow these general steps: +To translate the templates of your application, prepare the text for a translator or translation service by marking text, attributes, and other elements with the Angular `i18n` attribute. +Complete the following actions to mark text, attributes, and other elements with the Angular `i18n` attribute. -1. [Mark text for translations](#i18n-attribute). -2. [Add helpful descriptions and meanings](#help-translator) to help the translator with additional information or context. -3. [Translate text not for display](#no-element). -4. [Mark element attributes for translations](#translate-attributes), such as an image's `title` attribute. -5. [Mark plurals and alternates for translation](#plurals-alternates) in order to comply with the pluralization rules and grammatical constructions of different languages. +1. [Mark text for translations][AioGuideI18nI18nAttribute]. +2. [Add helpful descriptions and meanings][AioGuideI18nHelpTranslator] to help the translator with additional information or context. +3. [Translate text not for display][AioGuideI18nNoElement]. +4. [Mark element attributes for translations][AioGuideI18nTranslateAttributes], such as the `title` attribute of an image. +5. [Mark plurals and alternates for translation][AioGuideI18nPluralsAlternates] in order to comply with the pluralization rules and grammatical constructions of different languages. + + {@a i18n-attribute} @@ -154,7 +166,7 @@ Follow these general steps: Mark the static text messages in your component templates for translation using the `i18n` attribute. Place it on every element tag with fixed text to be translated. -For example, the following `

` tag displays a simple English language greeting, "Hello i18n!" +For example, the following `

` tag displays a simple English language greeting, "Hello i18n!". @@ -165,131 +177,152 @@ To mark the greeting for translation, add the `i18n` attribute to the `

` tag
`i18n` is a custom attribute, recognized by Angular tools and compilers. -After translation, the compiler removes it. It is not an Angular directive. +After translation, the compiler removes it. +It is not an Angular directive.
+ + {@a help-translator} ### Add helpful descriptions and meanings To translate a text message accurately, the translator may need additional information or context. -Add a _description_ of the text message as the value of the `i18n` attribute, as shown in the following example: +Add a *description* of the text message as the value of the `i18n` attribute. +The following example displays the value of the `i18n` attribute. -The translator may also need to know the meaning or intent of the text message within this particular app context, in order to translate it the same way as other text with the same meaning. -Start the `i18n` attribute value with the _meaning_ and -separate it from the _description_ with the `|` character: `|`. +The translator may also need to know the meaning or intent of the text message within this particular application context, in order to translate it the same way as other text with the same meaning. +Start the `i18n` attribute value with the *meaning* and separate it from the *description* with the `|` character: `|`. -For example, you can add the meaning that this `

` tag is a site header that needs to be translated the same way not only when used as a header, but also when referred to from another section of text: +For example, you may want to indicate that the `

` tag is a site header that needs to be translated the same way whether it used as a header or referenced in another section of text. +The following example displays how to indicate that the `

` tag needs to be translated as a header or referenced elsewhere. -As a result, any text marked with `site header` as the _meaning_ is translated exactly the same way. +The result is any text marked with `site header` as the *meaning* is translated exactly the same way. + + {@a transaction-unit-ids}
How meanings control text extraction and merging
-The Angular extraction tool (described in [Work with translation files](#ng-xi18n) in this guide) generates a translation unit entry for each `i18n` -attribute in a template. -It assigns each translation unit a unique ID based on the _meaning_ and _description_. +The Angular extraction tool generates a translation unit entry for each `i18n` attribute in a template. +The Angular extraction tool assigns each translation unit a unique ID based on the *meaning* and *description*. +For more information about the Angular extraction tool, see [Work with translation files][AioGuideI18nNgXi18n] in this guide. -The same text elements with different _meanings_ are extracted with separate IDs. -For example, if the word "right" appears with the meaning `correct` (as in "You are right") in one place, and with the meaning `direction` (as in "Turn right") in another place, the word is translated differently and merged back into the app as different translation entries. +The same text elements with different *meanings* are extracted with different IDs. +For example, if the word "right" uses the following two definitions in two different locations, the word is translated differently and merged back into the application as different translation entries. -If the same text elements have different _descriptions_ but the same _meaning_, they are extracted only once, with only one ID. That one translation entry is merged back into the app wherever the same text elements appear. +* `correct` as in you are "right" +* `direction` as in turn "right" + +If the same text elements meet the following conditions, the text elements are extracted only once and use the same ID. + +* Same meaning or definition +* Different descriptions + +That one translation entry is merged back into the application wherever the same text elements appear.
+ + {@a no-element} ### Translate text not for display -While you can translate non-displayed text using a `` tag, you are creating a new DOM element. To avoid doing so, wrap the text in an `` element, which is transformed into a non-displayed HTML comment as shown in this example: +If you translate non-displayed text using the `` tag, you create a new DOM element. +To avoid doing a new DOM element, wrap the text in an `` element. +The following example displays the `` element transformed into a non-displayed HTML comment. + + {@a translate-attributes} ### Mark element attributes for translations HTML attributes such as `title` include text that should be translated along with the rest of the displayed text in the template. -The following example shows an image with a `title` attribute: +The following example displays an image with a `title` attribute. To mark an attribute for translation, add `i18n-`*attribute* in which *attribute* is the attribute to translate. -The following example shows how to mark the -`title` attribute on the `img` tag by adding `i18n-title`: +The following example displays how to mark the `title` attribute on the `img` tag by adding `i18n-title`. -You can use `i18n-`*attribute* with any attribute of any element. -You also can assign a meaning, description, and custom ID with the `i18n-`*attribute*`="|@@"` syntax. +Use `i18n-`*attribute* with any attribute of any element. +Also, to assign a meaning, description, and custom ID, use the `i18n-`*attribute*`="|@@"` syntax. + + {@a plurals-alternates} ### Mark plurals and alternates for translation -Different languages have different pluralization rules and grammatical constructions that can make translation difficult. +Different languages have different pluralization rules and grammatical constructions that increase the difficulty of translation. To simplify translation, use International Components for Unicode (ICU) clauses with regular expressions, such as `plural` to mark the uses of plural numbers, and `select` to mark alternate text choices.
-The ICU clauses adhere to the [ICU Message Format](http://userguide.icu-project.org/formatparse/messages "ICU Message Format") specified in the [CLDR pluralization rules](http://cldr.unicode.org/index/cldr-spec/plural-rules "Pluralization Rules"). +The ICU clauses adhere to the [ICU Message Format][GithubUnicodeOrgIcuUserguideFormatParseMessages] specified in the [CLDR pluralization rules][UnicodeCldrIndexCldrSpecPluralRules].
+ + {@a plural-ICU} #### Mark plurals Use the `plural` clause to mark expressions that may not be meaningful if translated word-for-word. -For example, if you want to display "updated x minutes ago" in English, you may want to display "just now", "one minute ago", or "_x_ minutes ago" (with _x_ as the actual number). +For example, if you want to display "updated x minutes ago" in English, you may want to display "just now", "one minute ago", or "*x* minutes ago" (with *x* as the actual number). Other languages might express this cardinality differently. -The following example shows how to use a `plural` clause to express these three options: +The following example displays how to use a `plural` clause to express each of the three situations. -In the above example: +Review the following details in the above example. -* The first parameter, `minutes`, is bound to the component property (`minutes`), which determines the number of minutes. - -* The second parameter identifies this as a `plural` translation type. - -* The third parameter defines a pattern of pluralization categories and their matching values: - * For zero minutes, use `=0 {just now}`. - * For one minute, use `=1 {one minute}`. - * For any unmatched cardinality, use `other {{{minutes}} minutes ago}`. - You can use HTML markup and [interpolations](guide/glossary#interpolation "Definition of interpolation") such as `{{{minutes}}` with the `plural` clause in expressions. - * After the pluralization category, put the default text (English) within braces (`{}`). +* The first parameter, `minutes`, is bound to the component property (`minutes`), which determines the number of minutes. +* The second parameter identifies this as a `plural` translation type. +* The third parameter defines a pattern of pluralization categories and the matching values: + * For zero minutes, use `=0 {just now}`. + * For one minute, use `=1 {one minute}`. + * For any unmatched cardinality, use `other {{{minutes}} minutes ago}`. + Use HTML markup and [interpolations][AioGuideGlossaryInterpolation], such as `{{{minutes}}` with the `plural` clause in expressions. + * After the pluralization category, put the default text (English) within braces (`{}`). Pluralization categories include (depending on the language): -* `=0` (or any other number) -* `zero` -* `one` -* `two` -* `few` -* `many` -* `other` +* `=0` (or any other number) +* `zero` +* `one` +* `two` +* `few` +* `many` +* `other`
Locales may not support some pluralization categories
Many locales don't support some of the pluralization categories. For example, the default locale (`en-US`) and other locales (such as `es`) have very simple `plural()` functions that don't support the `few` category. -The following shows the [en-US](https://github.com/angular/angular/blob/ecffc3557fe1bff9718c01277498e877ca44588d/packages/core/src/i18n/locale_en.ts#L15-L18) `plural()` function: +The following code example displays the [en-US][GithubAngularAngularBlobEcffc3557fe1bff9718c01277498e877ca44588dPackagesCoreSrcI18nLocaleEnTsL15L18] `plural()` function. -``` +```typescript function plural(n: number): number { - let i = Math.floor(Math.abs(n)), v = n.toString().replace(/^[^.]*\.?/, '').length; - if (i === 1 && v === 0) return 1; - return 5; + let i = Math.floor(Math.abs(n)), v = n.toString().replace(/^[^.]*\.?/, '').length; + if (i === 1 && v === 0) return 1; + return 5; } ``` @@ -298,10 +331,12 @@ The `few` category will never match. If none of the pluralization categories match, Angular will try to match `other`. Use `other` as the standard fallback for a missing category. -For more information about pluralization categories, see [Choosing plural category names](http://cldr.unicode.org/index/cldr-spec/plural-rules#TOC-Choosing-Plural-Category-Names) in the CLDR - Unicode Common Locale Data Repository. +For more information about pluralization categories, see [Choosing plural category names][UnicodeCldrIndexCldrSpecPluralRulesTocChoosingPluralCategoryNames] in the CLDR - Unicode Common Locale Data Repository.
+ + {@a select-ICU} {@a nesting-ICUS} @@ -311,15 +346,17 @@ If you need to display alternate text depending on the value of a variable, you need to translate all of the alternates. The `select` clause, similar to the `plural` clause, marks choices for alternate text based on your defined string values. -For example, the following clause in the component template binds to the component's `gender` property, which outputs one of the following string values: "male", "female" or "other". -The clause maps those values to the appropriate translations: +For example, the following clause in the component template binds to the `gender` property of the component, which outputs one of the following string values: `"male"`, `"female"`, or `"other"`. +The clause maps the values to the appropriate translations. -You can also nest different clauses together, such as the `plural` and `select` clauses in the following example: +Also, nest different clauses together, such as the `plural` and `select` clauses. +The following example displays nested clauses. - - + + + {@a ng-xi18n} {@a ng-xi18n-options} @@ -327,71 +364,82 @@ You can also nest different clauses together, such as the `plural` and `select` ## Work with translation files -After preparing a template for translation, use the Angular CLI [`extract-i18n`](cli/extract-i18n) command to extract the marked text in the template into a _source language_ file. +After preparing a template for translation, use the [`extract-i18n`][AioCliExtractI18n] Angular CLI command to extract the marked text in the template into a *source language* file. + The marked text includes text marked with `i18n` and attributes marked with `i18n-`*attribute* as described in the previous section. Follow these steps: -1. [Extract the source language file](#create-source). -You can optionally change the location, format, and name. -2. [Create a translation file for each language](#localization-folder) by copying the source language file. -3. [Translate each translation file](#translate-text-nodes). -4. [Translate plurals and alternate expressions](#translate-plural-select) separately. +1. [Extract the source language file][AioGuideI18nCreateSource]. + Optionally, change the location, format, and name. +2. [Create a translation file for each language][AioGuideI18nLocalizationFolder] by copying the source language file. +3. [Translate each translation file][AioGuideI18nTranslateTextNodes]. +4. [Translate plurals and alternate expressions][AioGuideI18nTranslatePluralSelect] separately. + + {@a create-source} ### Extract the source language file -To extract the source language file, open a terminal window, change to the root directory of your app project, and run the following CLI command: +To extract the source language file, open a terminal window, change to the root directory of your application project, and run the following CLI command: - ng extract-i18n +ng extract-i18n -The `extract-i18n` command creates a source language file named `messages.xlf` in your project's root directory using the [XML Localization Interchange File Format (XLIFF, version 1.2)](https://en.wikipedia.org/wiki/XLIFF "Wikipedia page about XLIFF"). +The `extract-i18n` command creates a source language file named `messages.xlf` in the root directory of your project using the [XML Localization Interchange File Format (XLIFF, version 1.2)][WikipediaWikiXliff]. -Use the following [`extract-i18n` command options](cli/extract-i18n) to change the source language file location, format, and file name: +Use the following [`extract-i18n` command options][AioCliExtractI18n] to change the source language file location, format, and file name: -* `--output-path`: Change the location. -* `--format`: Change the format. -* `--outFile`: Change the file name. +* `--output-path`: Change the location. +* `--format`: Change the format. +* `--outFile`: Change the file name. -Note: The `--i18n-locale` option is deprecated. -Angular 9 uses the source locale configured in your app's [workspace configuration](guide/workspace-config "Angular workspace configuration") file (`angular.json`). +
+ +**Note**: The `--i18n-locale` option is deprecated. +Angular 9 uses the source locale configured in the [workspace configuration][AioGuideWorkspaceConfig] file (`angular.json`) of your application. + +
#### Change the source language file location -To create a file in the `src/locale` directory, specify the output path as an option, as shown in the following example: +To create a file in the `src/locale` directory, specify the output path as an option. +The following example specifies the output path as an option. - ng extract-i18n --output-path src/locale +ng extract-i18n --output-path src/locale + + {@a other-formats} #### Change the source language file format -The `extract-i18n` command can read and write files in three translation formats: +The `extract-i18n` command writes files in the following translation formats. -* XLIFF 1.2 (default) -* XLIFF 2 -* [XML Message Bundle (XMB)](http://cldr.unicode.org/development/development-process/design-proposals/xmb) -* JSON -* [ARB](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification) +* XLIFF 1.2 (default) +* XLIFF 2 +* [XML Message Bundle (XMB)][UnicodeCldrDevelopmentDevelopmentProcessDesignProposalsXmb] +* JSON +* [ARB][GithubGoogleAppResourceBundleWikiApplicationresourcebundlespecification] -Specify the translation format explicitly with the `--format` command option, as shown in the following examples: +Specify the translation format explicitly with the `--format` command option. +The following example demonstrates several translation formats. -ng extract-i18n --format=xlf -ng extract-i18n --format=xlf2 -ng extract-i18n --format=xmb -ng extract-i18n --format=json -ng extract-i18n --format=arb +ng extract-i18n --format=xlf +ng extract-i18n --format=xlf2 +ng extract-i18n --format=xmb +ng extract-i18n --format=json +ng extract-i18n --format=arb
- XLIFF files use the extension `.xlf`. - The XMB format generates `.xmb` source language files but uses`.xtb` (XML Translation Bundle: XTB) translation files. +XLIFF files use the extension `.xlf`. +The XMB format generates `.xmb` source language files but uses`.xtb` (XML Translation Bundle: XTB) translation files.
@@ -401,9 +449,11 @@ To change the name of the source language file generated by the extraction tool, the `--outFile` command option: - ng extract-i18n --out-file source.xlf +ng extract-i18n --out-file source.xlf + + {@a localization-folder} ### Create a translation file for each language @@ -415,12 +465,14 @@ Use a filename extension that matches the associated locale, such as `messages.f For example, to create a French translation file, follow these steps: -1. Make a copy of the `messages.xlf` source language file. -2. Put the copy in the `src/locale` folder. -3. Rename the copy to `messages.fr.xlf` for the French language (`fr`) translation. -Send this translation file to the translator. +1. Make a copy of the `messages.xlf` source language file. +2. Put the copy in the `src/locale` folder. +3. Rename the copy to `messages.fr.xlf` for the French language (`fr`) translation. + Send this translation file to the translator. -Repeat the above steps for each language you want to add to your app. +Repeat the above steps for each language you want to add to your application. + + {@a translate-text-nodes} @@ -428,123 +480,140 @@ Repeat the above steps for each language you want to add to your app. Unless you are fluent in the language and have the time to edit translations, you would likely send each translation file to a translator, who would then use an XLIFF file editor to create and edit the translation. -To demonstrate this process, see the `messages.fr.xlf` file in the , which includes a French translation you can edit without a special XLIFF editor or knowledge of French. -Follow these steps: +To demonstrate this process, review the `messages.fr.xlf` file in the . The live example includes a French translation for you to edit without a special XLIFF editor or knowledge of French. +Complete the following actions. -1. Open `messages.fr.xlf` and find the first `` element. This is a *translation unit*, also known as a *text node*, representing the translation of the `

` greeting tag that was previously marked with the `i18n` attribute: +1. Open `messages.fr.xlf` and find the first `` element. + This is a *translation unit*, also known as a *text node*, representing the translation of the `

` greeting tag that was previously marked with the `i18n` attribute: + + > + + > The `id="introductionHeader"` is a [custom ID][AioGuideI18nCustomId], but without the `@@` prefix required in the source HTML. + +2. Duplicate the `...` element in the text node, rename it to `target`, and then replace its content with the French text: + + > + + > In a more complex translation, the information and context in the [description and meaning elements][AioGuideI18nHelpTranslator] described previously would help you choose the right words for translation. + +3. Translate the other text nodes. + The following example displays the way to translate. + + > + +
+ + Don't change the IDs for translation units. + Each `id` is generated by Angular and depends on the content of the template text and its assigned meaning. + If you change either the text or the meaning, then the `id` changes. + For more about managing text updates and IDs, see [custom IDs][AioGuideI18nCustomId]. + +
-> - -> The `id="introductionHeader"` is a [custom ID](#custom-id "Manage marked text with custom IDs"), but without the `@@` prefix required in the source HTML. - -2. Duplicate the `...` element in the text node, rename it to `target`, and then replace its content with the French text: - -> - -> In a more complex translation, the information and context in the [description and meaning elements](#help-translator "Add helpful descriptions and meanings") described previously would help you choose the right words for translation. - -3. Translate the other text nodes the same way as shown in the following example: - -> - -
- - Don't change the IDs for translation units. - Each `id` is generated by Angular and depends on the content of the template text and its assigned meaning. - If you change either the text or the meaning, then the `id` changes. - For more about managing text updates and IDs, see the section on [custom IDs](#custom-id "Manage marked text with custom IDs"). - -
+ {@a translate-plural-select} ### Translate plurals and alternate expressions -The [`plural` and `select` ICU expressions](#plurals-alternates "Mark plurals and alternates for translation") are extracted as additional messages, so you must translate them separately. +The [`plural` and `select` ICU expressions][AioGuideI18nPluralsAlternates] are extracted as additional messages, so you must translate them separately. + + {@a translate-plural} #### Translate plurals -To translate a `plural`, translate its ICU format match values as shown in the following example: +To translate a `plural`, translate the ICU format match values. -* `just now` -* `one minute ago` -* ` minutes ago` +* `just now` +* `one minute ago` +* ` minutes ago` + + +The following example displays the way to translate. -You can add or remove plural cases as needed for each language. +Add or remove plural cases as needed for each language.
-For language plural rules, see -[CLDR plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html "CLDR Charts to view the Common Locale Data Repository data"). +For language plural rules, see [CLDR plural rules][GithubUnicodeOrgCldrStagingChartsLatestSupplementalLanguagePluralRulesHtml].
+ + {@a translate-select} #### Translate alternate expressions Angular also extracts alternate `select` ICU expressions as separate translation units. -The following shows a `select` ICU expression in the component template: +The following example displays a `select` ICU expression in the component template. -In this example, Angular extracts the expression into two translation units. The first contains the text outside of the `select` clause, and uses a placeholder for `select` (``): +In this example, Angular extracts the expression into two translation units. +The first contains the text outside of the `select` clause, and uses a placeholder for `select` (``):
-When translating the text, you can move the placeholder if necessary, but don't remove it. -If you remove the placeholder, the ICU expression will not appear in your translated app. +When you translate the text, move the placeholder if necessary, but don't remove it. +If you remove the placeholder, the ICU expression is removed from your translated application.
-The second translation unit contains the `select` clause: +The following example displays the second translation unit that contains the `select` clause. -The following example shows both translation units after translating: +The following example displays both translation units after translation is complete. + + {@a translate-nested} #### Translate nested expressions -Angular treats a nested expression in the same manner as an alternate expression, extracting it into two translation units. The first contains the text outside of the nested expression: +Angular treats a nested expression in the same manner as an alternate expression. Angular extracts the expression into two translation units. +The following example displays the first translation unit that contains the text outside of the nested expression. -The second translation unit contains the complete nested expression: +The following example displays the second translation unit that contains the complete nested expression. -The following example shows both translation units after translating: +The following example displays both translation units after translating. + + {@a merge} {@a merge-aot} ## Merge translations into the app -To merge the completed translations into the app, use the [Angular CLI](guide/glossary#command-line-interface-cli "Definition of CLI") to build a copy of the app's distributable files for each locale. -The build process replaces the original text with translated text, and sets the `LOCALE_ID` token for each distributable copy of the app. +To merge the completed translations into your application, use the [Angular CLI][AioGuideGlossaryCommandLineInterfaceCli] to build a copy of the distributable files of your application for each locale. + +The build process replaces the original text with translated text, and sets the `LOCALE_ID` token for each distributable copy of your application. It also loads and registers the locale data. -After merging, you can serve each distributable copy of the app using server-side language detection or different subdirectories, as described in the next section about [deploying multiple locales](#deploy-locales). +After you merge the translations, serve each distributable copy of the application using server-side language detection or different subdirectories. +For more information about how to serve each distributable copy of the application, see [deploying multiple locales][AioGuideI18nDeployLocales]. -The build process uses [ahead-of-time (AOT) compilation](guide/glossary#ahead-of-time-aot-compilation) to produce a small, fast, -ready-to-run app. With Ivy in Angular version 9, AOT is used by default for both -development and production builds, and AOT is required to localize component templates. +The build process uses [ahead-of-time (AOT) compilation][AioGuideGlossaryAheadOfTimeAotCompilation] to produce a small, fast, ready-to-run application. +With Ivy in Angular version 9, AOT is used by default for both development and production builds, and AOT is required to localize component templates.
-For a detailed explanation of the build process, see [Building and serving Angular apps](guide/build "Building and serving Angular apps"). +For a detailed explanation of the build process, see [Building and serving Angular apps][AioGuideBuild]. This build process works for translation files in the `.xlf` format or in another format that Angular understands, such as `.xtb`.
@@ -552,146 +621,168 @@ This build process works for translation files in the `.xlf` format or in anothe
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, see [merging with the JIT compiler](https://v8.angular.io/guide/i18n#merge-with-the-jit-compiler "Merge with the JIT compiler"). +If you [disable Ivy][AioGuideIvyOptingOutOfIvyInVersion9] and are using JIT mode, navigate [merging with the JIT compiler][AngularV8GuideI18nMergeWithTheJitCompiler].
-To build a separate distributable copy of the app for each locale, [define the locales in the build configuration](#localize-config) in your project's workspace configuration file [`angular.json`](guide/workspace-config "Angular workspace configuration"). -This method shortens the build process by removing the requirement to perform a full app build for each locale. +To build a separate distributable copy of the application for each locale, [define the locales in the build configuration][AioGuideI18nLocalizeConfig] in the workspace configuration file [`angular.json`][AioGuideWorkspaceConfig] of your project. -You can then [generate app versions for each locale](#localize-generate) using the `"localize"` option in `angular.json`. You can also [build from the command line](#localize-build-command) using the Angular CLI [`build`](/cli/build "CLI reference for ng build") command with the `--localize` option. +This method shortens the build process by removing the requirement to perform a full application build for each locale. + +Then, to [generate application versions for each locale][AioGuideI18nLocalizeGenerate], use the `"localize"` option in `angular.json`. +Also, to [build from the command line][AioGuideI18nLocalizeBuildCommand], use the [`build`][AioCliBuild] Angular CLI command with the `--localize` option.
-You can optionally [apply specific build options for just one locale](#localize-build-one-locale) for a custom locale configuration. +Optionally, [apply specific build options for just one locale][AioGuideI18nLocalizeBuildOneLocale] for a custom locale configuration.
+ + {@a localize-config} ### Define locales in the build configuration -Use the `i18n` project option in your app's build configuration file ([`angular.json`](guide/workspace-config "Angular workspace configuration")) to define locales for a project. +Use the `i18n` project option in the build configuration file ([`angular.json`][AioGuideWorkspaceConfig]) of your application to define locales for a project. + The following sub-options identify the source language and tell the compiler where to find supported translations for the project: -* `sourceLocale`: The locale you use within the app source code (`en-US` by default) -* `locales`: A map of locale identifiers to translation files +* `sourceLocale`: The locale you use within the application source code (`en-US` by default) +* `locales`: A map of locale identifiers to translation files For example, the following excerpt of an `angular.json` file sets the source locale to `en-US` and provides the path to the `fr` (French) locale translation file: ... "projects": { - "my-project": { - ... - "i18n": { - "sourceLocale": "en-US", - "locales": { - "fr": "src/locale/messages.fr.xlf" - } - }, - "architect": { - ... + "my-project": { + ... + "i18n": { + "sourceLocale": "en-US", + "locales": { + "fr": "src/locale/messages.fr.xlf" + } + }, + "architect": { + ... + }, + ... } } + + {@a localize-generate} -### Generate app versions for each locale +### Generate application versions for each locale To use your locale definition in the build configuration, use the `"localize"` option in `angular.json` to tell the CLI which locales to generate for the build configuration: -* Set `"localize"` to `true` for *all* the locales previously defined in the build configuration. -* Set `"localize"` to an array of a subset of the previously-defined locale identifiers to build only those locale versions. -* Set `"localize"` to `false` to disable localization and not generate any locale-specific versions. +* Set `"localize"` to `true` for *all* the locales previously defined in the build configuration. +* Set `"localize"` to an array of a subset of the previously defined locale identifiers to build only those locale versions. +* Set `"localize"` to `false` to disable localization and not generate any locale-specific versions.
-Note: [Ahead-of-time (AOT) compilation](guide/glossary#ahead-of-time-aot-compilation) is required to localize component templates. +**NOTE**: [Ahead-of-time (AOT) compilation][AioGuideGlossaryAheadOfTimeAotCompilation] is required to localize component templates. + If you changed this setting, set `"aot"` to `true` in order to use AOT.
-The following example shows the `"localize"` option set to `true` in `angular.json` so that all locales defined in the build configuration are built: +The following example displays the `"localize"` option set to `true` in `angular.json`, so that all locales defined in the build configuration are built. "build": { - "builder": "@angular-devkit/build-angular:browser", - "options": { - "localize": true, - "aot": true, + "builder": "@angular-devkit/build-angular:browser", + "options": { + "localize": true, + "aot": true, + ... + } ... +}
Due to the deployment complexities of i18n and the need to minimize rebuild time, the development server only supports localizing a single locale at a time. -Setting the `"localize"` option to `true` will cause an error when using `ng serve` if more than one locale is defined. -Setting the option to a specific locale, such as `"localize": ["fr"]`, can work if you want to develop against a specific locale (such as `fr`). +If you set the `"localize"` option to `true`, define more than one locale, and use `ng serve`; then an error occurs. +If you want to develop against a specific locale, set the `"localize"` option to a specific locale. +For example, for French (`fr`), specify `"localize": ["fr"]`.
The CLI loads and registers the locale data, places each generated version in a locale-specific directory to keep it separate from other locale versions, and puts the directories within the configured `outputPath` for the project. For each application variant the `lang` attribute of the `html` element is set to the locale. -The CLI also adjusts the HTML base HREF for each version of the app by adding the locale to the configured `baseHref`. +The CLI also adjusts the HTML base HREF for each version of the application by adding the locale to the configured `baseHref`. -You can set the `"localize"` property as a shared configuration that all the configurations effectively inherit (or can override). +Set the `"localize"` property as a shared configuration to effectively inherit for all the configurations. +Also, set the property to override other configurations. + + {@a localize-build-command} ### Build from the command line -You can also use the `--localize` option with the [`ng build`](/cli/build "CLI reference for ng build") command and your existing `production` configuration. -The CLI builds all locales defined in the build configuration, which is similar to setting the `"localize"` option to `true` as described in the previous section. +Also, use the `--localize` option with the [`ng build`][AioCliBuild] command and your existing `production` configuration. +The CLI builds all locales defined in the build configuration. +If you set the locales in build configuration, it is similar to when you set the `"localize"` option to `true`. +For more information about how to set the locales, see [Generate application versions for each locale][AioGuideI18nLocalizeGenerate]. - ng build --localize +ng build --localize + + {@a localize-build-one-locale} ### Apply specific build options for just one locale -To apply specific build options to only one locale, you can create a custom locale-specific configuration by specifying a single locale as shown in the following example: +To apply specific build options to only one locale, specify a single locale to create a custom locale-specific configuration. +The following example displays a custom locale-specific configuration using a single locale. "build": { - ... - "configurations": { ... - "fr": { - "localize": ["fr"], - "main": "src/main.fr.ts", - ... + "configurations": { + ... + "fr": { + "localize": ["fr"], + "main": "src/main.fr.ts", + ... + } } - } }, "serve": { - ... - "configurations": { ... - "fr": { - "browserTarget": "*project-name*:build:fr" + "configurations": { + ... + "fr": { + "browserTarget": "*project-name*:build:fr" + } } - } } -You can then pass this configuration to the `ng serve` or `ng build` commands. -The following shows how to serve the French language file created in the example for this guide: +Pass this configuration to the `ng serve` or `ng build` commands. +The following code example displays how to serve the French language file. - ng serve --configuration=fr +ng serve --configuration=fr
-You can use the CLI development server (`ng serve`), but only with a single locale. +Use the CLI development server (`ng serve`) with only a single locale.
-For production builds, you can use configuration composition to execute both configurations: +For production builds, use configuration composition to run both configurations. ng build --configuration=production,fr @@ -700,104 +791,115 @@ For production builds, you can use configuration composition to execute both con ... "architect": { - "build": { - "builder": "@angular-devkit/build-angular:browser", - "options": { ... }, - "configurations": { - "fr": { - "localize": ["fr"], - } - } - }, - ... - "serve": { - "builder": "@angular-devkit/build-angular:dev-server", - "configurations": { - "production": { - "browserTarget": "my-project:build:production" - }, - "development": { - "browserTarget": "my-project:build:development" - }, - "fr": { - "browserTarget": "my-project:build:fr" - } + "build": { + "builder": "@angular-devkit/build-angular:browser", + "options": { ... }, + "configurations": { + "fr": { + "localize": ["fr"], + } + } }, - "defaultConfiguration": "development" - }, + ... + "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" + } + } + } } + + {@a missing-translation} ### Report missing translations -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: +When a translation is missing, the build succeeds but generates a warning such as `Missing translation for message "foo"`. +To configure the level of warning that is generated by the Angular compiler, specify one of the following levels. -* `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. +* `error`: Throw an error. + If you are using AOT compilation, the build will fail. + If you are using JIT compilation, the application will fail to load. +* `warning` (default): Displays a `Missing translation` warning in the console or shell. +* `ignore`: Do nothing. -Specify the warning level in the `options` section for the `build` target of your Angular CLI configuration file (`angular.json`). The following example shows how to set the warning level to `error`: +Specify the warning level in the `options` section for the `build` target of your Angular CLI configuration file (`angular.json`). +The following example displays how to set the warning level to `error`. "options": { - ... - "i18nMissingTranslation": "error" + ... + "i18nMissingTranslation": "error" } + + {@a deploy-locales} ## Deploy multiple locales -If `myapp` is the directory containing your app's distributable files, you would typically make available different versions for different locales in locale directories such as `myapp/fr` for the French version and `myapp/es` for the Spanish version. +If `myapp` is the directory containing the distributable files of your application, you would typically make available different versions for different locales in locale directories such as `myapp/fr` for the French version and `myapp/es` for the Spanish version. -The HTML `base` tag with the `href` attribute specifies the base URI, or URL, for relative links. If you set the `"localize"` option in `angular.json` to `true` or to an array of locale IDs, the CLI adjusts the base `href` for each version of the app by adding the locale to the configured `"baseHref"`. You can specify the `"baseHref"` for each locale in your workspace configuration file (`angular.json`), as shown in the following example, which sets `"baseHref"` to an empty string: +The HTML `base` tag with the `href` attribute specifies the base URI, or URL, for relative links. +If you set the `"localize"` option in `angular.json` to `true` or to an array of locale IDs, the CLI adjusts the base `href` for each version of the application. +To adjust the base `href` for each version of the application, the CLI adds the locale to the configured `"baseHref"`. +Specify the `"baseHref"` for each locale in your workspace configuration file (`angular.json`). +The following example displays `"baseHref"` set to an empty string. ... "projects": { - "my-project": { - ... - "i18n": { - "sourceLocale": "en-US", - "locales": { - "fr": { - "translation": "src/locale/messages.fr.xlf", - "baseHref": "" + "angular.io-example": { + ... + "i18n": { + "sourceLocale": "en-US", + "locales": { + "fr": { + "translation": "src/locale/messages.fr.xlf", + "baseHref": "" + } + } + }, + "architect": { + ... } - } - }, - "architect": { ... } } -You can also use the CLI `--baseHref` option with [`ng build`](cli/build "CLI reference for ng build") to declare the base `href` at compile time. +Also, to declare the base `href` at compile time, use the CLI `--baseHref` option with [`ng build`][AioCliBuild]. ### Configuring servers Typical deployment of multiple languages serve each language from a different subdirectory. -Users are redirected to the preferred language defined in the browser using the -`Accept-Language` HTTP header. If the user has not defined a preferred language, -or if the preferred language is not available, then the server falls back to the default language. -Users can change the language by navigating to other subdirectories, which often occurs using a -menu implemented in the application. +Users are redirected to the preferred language defined in the browser using the `Accept-Language` HTTP header. +If the user has not defined a preferred language, or if the preferred language is not available, then the server falls back to the default language. +To change the language, see another subdirectory. +The change of subdirectory often occurs using a menu implemented in the application. -For more information on how to deploy apps to a remote server, see [Deployment](guide/deployment "Deployment guide"). +For more information on how to deploy apps to a remote server, see [Deployment][AioGuideDeployment]. #### Nginx -The following is an example of an Nginx configuration. +The following example displays an Nginx configuration. -``` +```nginx http { - # Browser preferred language detection (does NOT require AcceptLanguageModule) + # Browser preferred language detection (does NOT require + # AcceptLanguageModule) map $http_accept_language $accept_language { ~*^de de; ~*^fr fr; @@ -816,10 +918,11 @@ server { set $accept_language "fr"; } - # Redirect "/" to Angular app in browser's preferred language + # Redirect "/" to Angular application in the preferred language of the browser rewrite ^/$ /$accept_language permanent; - # Everything under the Angular app is always redirected to Angular in the correct language + # Everything under the Angular application is always redirected to Angular in the + # correct language location ~ ^/(fr|de|en) { try_files $uri /$1/index.html?$args; } @@ -829,9 +932,9 @@ server { #### Apache -The following is an example of an Apache configuration. +The following example displays an Apache configuration. -``` +```apache ServerName localhost DocumentRoot /www/data @@ -857,69 +960,80 @@ The following is an example of an Apache configuration. ``` + + {@a app-pre-translation} ## Explore the translated example app -The following tabs show the example app and its translation files: +The following tabs display the example application and the associated translation files. - - - - - - - - - - + + + + + + + + + + ## Optional practices -The following are optional practices that may be required in special cases: +In special cases, the following practices are required. -* [Set the source locale manually](#set-source-manually) by setting the [LOCALE_ID](api/core/LOCALE_ID "API reference for LOCALE_ID") token. -* [Import global variants of the locale data](#import-locale) for extra locale data. -* [Manage marked text with custom IDs](#custom-id) if you require more control over matching translations. +* [Set the source locale manually][AioGuideI18nSetSourceManually] by setting the [`LOCALE_ID`][AioApiCoreLocaleId] token. +* [Import global variants of the locale data][AioGuideI18nImportLocale] for extra locale data. +* [Manage marked text with custom IDs][AioGuideI18nCustomId] if you require more control over matching translations. + + {@a set-source-manually} ### Set the source locale manually Angular already contains locale data for `en-US`. -The Angular CLI automatically includes the locale data and sets the `LOCALE_ID` value when you use the `--localize` option with [`ng build`](cli/build "ng build description"). +The Angular CLI automatically includes the locale data and sets the `LOCALE_ID` value when you use the `--localize` option with [`ng build`][AioCliBuild]. -To manually set an app's source locale to one other than the automatic value, follow these steps: +To manually set the source locale of an application to one other than the automatic value, complete the following actions. -1. Look up the ID for the language-locale combination in [the Angular repository](https://github.com/angular/angular/tree/master/packages/common/locales "Common locales in the Angular repository"). -2. Set the [`LOCALE_ID`](api/core/LOCALE_ID "API reference for LOCALE_ID") token. -The following example sets the value of `LOCALE_ID` to `fr` (French): +1. Search for the ID in the language-locale combination in [the Angular repository][GithubAngularAngularTreeMasterPackagesCommonLocales]. +2. Set the [`LOCALE_ID`][AioApiCoreLocaleId] token. + +The following example sets the value of `LOCALE_ID` to `fr` for French. + + {@a import-locale} ### Import global variants of the locale data -Angular will automatically include locale data if you configure the locale using the `--localize` option with [`ng build`](cli/build "ng build description") CLI command. +Angular will automatically include locale data if you configure the locale using the `--localize` option with [`ng build`][AioCliBuild] CLI command. -The [Angular repository](https://github.com/angular/angular/tree/master/packages/common/locales "Common locales in the Angular repository") files (`@angular/common/locales`) contain most of the locale data that you need, but some advanced formatting options require additional locale data. -Global variants of the locale data are available in [`@angular/common/locales/global`](https://github.com/angular/angular/tree/master/packages/common/locales/global "Global locale variants in the Angular repository"). -The following example imports the global variants for French (`fr`): +The [Angular repository][GithubAngularAngularTreeMasterPackagesCommonLocales] files (`@angular/common/locales`) contain most of the locale data that you need, but some advanced formatting options require additional locale data. + +Global variants of the locale data are available in [`@angular/common/locales/global`][GithubAngularAngularTreeMasterPackagesCommonLocalesGlobal]. + +The following example imports the global variants for French (`fr`) import '@angular/common/locales/global/fr'; + + {@a custom-id} ### Manage marked text with custom IDs -The Angular extractor generates a file with a translation unit entry for each `i18n` -attribute in a template. -As described previously (in [How meanings control text extraction and merging](#transaction-unit-ids)), Angular assigns each translation unit a unique ID such as the following: +The Angular extractor generates a file with a translation unit entry for each `i18n` attribute in a template. +As described in [How meanings control text extraction and merging][AioGuideI18nTransactionUnitIds], Angular assigns each translation unit a unique ID. +The following example displays translation units with unique IDs. @@ -928,15 +1042,15 @@ In most cases a text change would also require a change to the translation. Therefore, using a new ID keeps the text change in sync with translations. However, some translation systems require a specific form or syntax for the ID. -To address this requirement, you can mark text with _custom_ IDs. -While most developers don't need to use custom IDs, some may want to use IDs that have a unique syntax to convey additional metadata (such as the library, component, or area of the app in which the text appears). +To address this requirement, mark text with custom IDs. +While most developers don't need to use custom IDs, some may want to use IDs that have a unique syntax to convey additional metadata (such as the library, component, or area of the application in which the text appears). -Specify a custom ID in the `i18n` attribute by using the prefix `@@`. -The following example defines the custom ID `introductionHeader`: +Specify a custom ID in the `i18n` attribute by using the `@@` prefix. +The following example defines the `introductionHeader` custom ID. -When you specify a custom ID, the extractor generates a translation unit with the custom ID: +When you specify a custom ID, the extractor generates a translation unit with the custom ID. @@ -947,11 +1061,11 @@ The drawback of using custom IDs is that if you change the text, your translatio #### Use a custom ID with a description Use a custom ID in combination with a description and a meaning to further help the translator. -The following example includes a description, followed by the custom `id`: +The following example includes a description, followed by the custom ID. -The following example adds a meaning: +The following example adds a meaning. @@ -960,29 +1074,116 @@ The following example adds a meaning: Be sure to define custom IDs that are unique. If you use the same ID for two different text elements, the extraction tool extracts only the first one, and Angular uses its translation in place of both original text elements. -For example, in the following code the same custom ID `myId` is defined for two different text elements: +For example, in the following code snippet the same `myId` custom ID is defined for two different text elements. - ```html -

Hello

- -

Good bye

- ``` +```html +

Hello

+ +

Good bye

+``` -The following shows the translation to French: +The following displays the translation in French. - ```xml - - Hello - Bonjour - - ``` +```xml + + Hello + Bonjour + +``` -Both elements now use the same translation (`Bonjour`) because they were defined with the same custom ID: +Both elements now use the same translation (`Bonjour`), because both were defined with the same custom ID. - ```html -

Bonjour

- -

Bonjour

- ``` +```html +

Bonjour

+ +

Bonjour

+``` -@reviewed 2020-04-10 + + +[AioGuideI18nAppPreTranslation]: #app-pre-translation "Explore the translated example application - Localizing your application | Angular" +[AioGuideI18nCreateSource]: #create-source "Extract the source language file - Localizing your application | Angular" +[AioGuideI18nCustomId]: #custom-id "Manage marked text with custom IDs - Localizing your application | Angular" +[AioGuideI18nDeployLocales]: #deploy-locales "Deploy multiple locales - Localizing your application | Angular" +[AioGuideI18nHelpTranslator]: #help-translator "Add helpful descriptions and meanings - Localizing your application | Angular" +[AioGuideI18nI18nAttribute]: #i18n-attribute "Mark text for translations - Localizing your application | Angular" +[AioGuideI18nPipes]: #i18n-pipes "Format data based on locale - Localizing your application | Angular" +[AioGuideI18nImportLocale]: #import-locale "Import global variants of the locale data - Localizing your application | Angular" +[AioGuideI18nLocalizationFolder]: #localization-folder "Create a translation file for each language - Localizing your application | Angular" +[AioGuideI18nLocalizeBuildCommand]: #localize-build-command "Build from the command line - Localizing your application | Angular" +[AioGuideI18nLocalizeBuildOneLocale]: #localize-build-one-locale "Apply specific build options for just one locale - Localizing your application | Angular" +[AioGuideI18nLocalizeConfig]: #localize-config "Define locales in the build configuration - Localizing your application | Angular" +[AioGuideI18nLocalizeGenerate]: #localize-generate "Generate application versions for each locale - Localizing your application | Angular" +[AioGuideI18nMerge]: #merge "Merge translations into the application - Localizing your application | Angular" +[AioGuideI18nNgXi18n]: #ng-xi18n "Work with translation files - Localizing your application | Angular" +[AioGuideI18nNoElement]: #no-element "Translate text not for display - Localizing your application | Angular" +[AioGuideI18nPluralsAlternates]: #plurals-alternates "Mark plurals and alternates for translation - Localizing your application | Angular" +[AioGuideI18nSetSourceManually]: #set-source-manually "Set the source locale manually - Localizing your application | Angular" +[AioGuideI18nSettingUpCli]: #setting-up-cli "Add the localize package - Localizing your application | Angular" +[AioGuideI18nSettingUpLocale]: #setting-up-locale "Refer to locales by ID - Localizing your application | Angular" +[AioGuideI18nTemplatetranslations]: #template-translations "Prepare templates for translations - Localizing your application | Angular" +[AioGuideI18nTransactionUnitIds]: #transaction-unit-ids "How meanings control text extraction and merging - Localizing your application | Angular" +[AioGuideI18nTranslateAttributes]: #translate-attributes "Mark element attributes for translations - Localizing your application | Angular" +[AioGuideI18nTranslatePluralSelect]: #translate-plural-select "Translate plurals and alternate expressions - Localizing your application | Angular" +[AioGuideI18nTranslateTextNodes]: #translate-text-nodes "Translate each translation file - Localizing your application | Angular" + +[AioApiCommonCurrencypipe]: api/common/CurrencyPipe "CurrencyPipe | Common - API | Angular" +[AioApiCommonDatepipe]: api/common/DatePipe "DatePipe | Common - API | Angular" +[AioApiCommonDecimalpipe]: api/common/DecimalPipe "DecimalPipe | Common - API | Angular" +[AioApiCommonPercentpipe]: api/common/PercentPipe "PercentPipe | Common - API | Angular" +[AioApiCoreLocaleId]: api/core/LOCALE_ID "LOCALE_ID | Core - API | Angular" + +[AioCliMain]: cli "CLI Overview and Command Reference | Angular" +[AioCliBuild]: cli/build "ng build | CLI | Angular" +[AioCliExtractI18n]: cli/extract-i18n "ng extract-i18n | CLI | Angular" + +[AioGuideBuild]: guide/build "Building and serving Angular apps | Angular" + +[AioGuideDeployment]: guide/deployment "Deployment | Angular" + +[AioGuideGlossaryAheadOfTimeAotCompilation]: guide/glossary#ahead-of-time-aot-compilation "ahead-of-time (AOT) compilation - Glossary | Angular" +[AioGuideGlossaryCommandLineInterfaceCli]: guide/glossary#command-line-interface-cli "command-line interface (CLI) - Glossary | Angular" +[AioGuideGlossaryComponent]: guide/glossary#component "component - Glossary | Angular" +[AioGuideGlossaryInterpolation]: guide/glossary#interpolation "interpolation - Glossary | Angular" +[AioGuideGlossaryPipe]: guide/glossary#pipe "pipe - Glossary | Angular" +[AioGuideGlossaryTemplate]: guide/glossary#template "template - Glossary | Angular" + +[AioGuideIvyOptingOutOfIvyInVersion9]: guide/ivy#opting-out-of-ivy-in-version-9 "Opting out of Ivy in version 9 - Angular Ivy | Angular" + +[AioGuideNpmPackages]: guide/npm-packages "Workspace npm dependencies | Angular" + +[AioGuideWorkspaceConfig]: guide/workspace-config "Angular workspace configuration | Angular" + + + +[AngularV8GuideI18nMergeWithTheJitCompiler]: https://v8.angular.io/guide/i18n#merge-with-the-jit-compiler "Merge with the JIT compiler - Internationalization (i18n) | Angular v8" + +[GithubAngularAngularBlobEcffc3557fe1bff9718c01277498e877ca44588dPackagesCoreSrcI18nLocaleEnTsL15L18]: https://github.com/angular/angular/blob/ecffc3557fe1bff9718c01277498e877ca44588d/packages/core/src/i18n/locale_en.ts#L15-L18 "Line 15 to 18 - angular/packages/core/src/i18n/locale_en.ts | angular/angular | GitHub" +[GithubAngularAngularTreeMasterPackagesCommonLocales]: https://github.com/angular/angular/tree/master/packages/common/locales "angular/packages/common/locales | angular/angular | GitHub" +[GithubAngularAngularTreeMasterPackagesCommonLocalesGlobal]: https://github.com/angular/angular/tree/master/packages/common/locales/global "angular/packages/common/locales/global | angular/angular | GitHub" + +[GithubGoogleAppResourceBundleWikiApplicationresourcebundlespecification]: https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification "ApplicationResourceBundleSpecification | google/app-resource-bundle | GitHub" + +[GithubUnicodeOrgCldrStagingChartsLatestSupplementalLanguagePluralRulesHtml]: https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html "Language Plural Rules - CLDR Charts | Unicode | GitHub" +[GithubUnicodeOrgIcuUserguideFormatParseMessages]: https://unicode-org.github.io/icu/userguide/format_parse/messages "ICU Message Format - ICU Documentation | Unicode | GitHub" + +[LocStandardsIso6392]: https://www.loc.gov/standards/iso639-2 "ISO 639-2 Registration Authority | Library of Congress" + +[RfcEditorInfoBcp47]: https://www.rfc-editor.org/info/bcp47 "BCP 47 | RFC Editor" + +[ThinkwithgoogleMarketfinderIntlEnUsGuideHowToApproachI18nOverview]: https://marketfinder.thinkwithgoogle.com/intl/en_us/guide/how-to-approach-i18n#overview "Overview - How to approach internationalization | Market Finder | Think with Google" + +[UnicodeCldrCoreSpecUnicodeLanguageAndLocaleIdentifiers]: http://cldr.unicode.org/core-spec#Unicode_Language_and_Locale_Identifiers "Unicode Language and Locale Identifiers - Core Specification | CLDR - Unicode Common Locale Data Repository | Unicode" + +[UnicodeCldrDevelopmentDevelopmentProcessDesignProposalsXmb]: http://cldr.unicode.org/development/development-process/design-proposals/xmb "XMB | CLDR - Unicode Common Locale Data Repository | Unicode" + +[UnicodeCldrIndexCldrSpecPluralRules]: http://cldr.unicode.org/index/cldr-spec/plural-rules "Plural Rules | CLDR - Unicode Common Locale Data Repository | Unicode" +[UnicodeCldrIndexCldrSpecPluralRulesTocChoosingPluralCategoryNames]: http://cldr.unicode.org/index/cldr-spec/plural-rules#TOC-Choosing-Plural-Category-Names "Choosing Plural Category Names - Plural Rules | CLDR - Unicode Common Locale Data Repository | Unicode" + +[W3Xml]: https://www.w3.org/XML "Extensible Markup Language (XML) | W3C" + +[WikipediaWikiXliff]: https://en.wikipedia.org/wiki/XLIFF "XLIFF | Wikipedia" + + + +@reviewed 2021-08-17