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