cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update i18n doc regarding aot compilation (#24875)

Browse Source 
Add missing lines to code example to allow using ng serve with custom i18n configurations.

PR Close #24875
This commit is contained in:
Marius Lichtblau 2018-07-13 20:30:23 +02:00 committed by Victor Berchet
parent 1c533c913d
commit 7ebd8e59a8
1 changed files with 39 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -54,10 +54,10 @@ If you use JIT, you also need to define the `LOCALE_ID` provider in your main mo
</code-example> </code-example>
For more information about Unicode locale identifiers, see the For more information about Unicode locale identifiers, see the
[CLDR core spec](http://cldr.unicode.org/core-spec#Unicode_Language_and_Locale_Identifiers). [CLDR core spec](http://cldr.unicode.org/core-spec#Unicode_Language_and_Locale_Identifiers).
For a complete list of locales supported by Angular, see For a complete list of locales supported by Angular, see
[the Angular repository](https://github.com/angular/angular/tree/master/packages/common/locales). [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). The locale identifiers used by CLDR and Angular are based on [BCP47](http://www.rfc-editor.org/rfc/bcp/bcp47.txt).
@ -101,10 +101,10 @@ specify a custom locale id. For example, Angular's locale data defines the local
"fr". You can use the second parameter to associate the imported French locale data with the custom "fr". You can use the second parameter to associate the imported French locale data with the custom
locale id "fr-FR" instead of "fr". locale id "fr-FR" instead of "fr".
The files in `@angular/common/locales` contain most of the locale data that you 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 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. import from `@angular/common/locales/extra`. An error message informs you when this is the case.
<code-example path="i18n/doc-files/app.locale_data_extra.ts" region="import-locale-extra" title="src/app/app.module.ts" linenums="false"> <code-example path="i18n/doc-files/app.locale_data_extra.ts" region="import-locale-extra" title="src/app/app.module.ts" linenums="false">
</code-example> </code-example>
@ -113,15 +113,15 @@ import from `@angular/common/locales/extra`. An error message informs you when t
All locale data used by Angular are extracted from the Unicode Consortium's All locale data used by Angular are extracted from the Unicode Consortium's
<a href="http://cldr.unicode.org/" title="CLDR">Common Locale Data Repository (CLDR)</a>. <a href="http://cldr.unicode.org/" title="CLDR">Common Locale Data Repository (CLDR)</a>.
</div> </div>
## Template translations ## Template translations
<div class="l-sub-section"> <div class="l-sub-section">
This document refers to a unit of translatable text as "text," a "message", or a This document refers to a unit of translatable text as "text," a "message", or a
"text message." "text message."
</div> </div>
@ -168,7 +168,7 @@ To mark the greeting for translation, add the `i18n` attribute to the `<h1>` tag
{@a help-translator} {@a help-translator}
### Help the translator with a description and meaning ### Help the translator with a description and meaning
To translate a text message accurately, the translator may need additional information or context. To translate a text message accurately, the translator may need additional information or context.
You can add a description of the text message as the value of the `i18n` attribute, as shown in the You can add a description of the text message as the value of the `i18n` attribute, as shown in the
example below: example below:
@ -176,7 +176,7 @@ example below:
<code-example path="i18n/doc-files/app.component.html" region="i18n-attribute-desc" title="src/app/app.component.html" linenums="false"> <code-example path="i18n/doc-files/app.component.html" region="i18n-attribute-desc" title="src/app/app.component.html" linenums="false">
</code-example> </code-example>
The translator may also need to know the meaning or intent of the text message within this particular The translator may also need to know the meaning or intent of the text message within this particular
app context. app context.
You add context by beginning the `i18n` attribute value with the _meaning_ and You add context by beginning the `i18n` attribute value with the _meaning_ and
@ -192,7 +192,7 @@ The Angular extraction tool preserves both the meaning and the description in th
source file to facilitate contextually-specific translations, but only the combination of meaning source file to facilitate contextually-specific translations, but only the combination of meaning
and text message are used to generate the specific id of a translation. If you have two and text message are used to generate the specific id of a translation. If you have two
similar text messages with different meanings, they are extracted separately. If you have two similar similar text messages with different meanings, they are extracted separately. If you have two similar
text messages with different descriptions (not different meanings), then they are extracted only once. text messages with different descriptions (not different meanings), then they are extracted only once.
{@a custom-id} {@a custom-id}
@ -208,7 +208,7 @@ When you change the translatable text, the extractor tool generates a new id for
You must then update the translation file with the new id. You must then update the translation file with the new id.
Alternatively, you can specify a custom id in the `i18n` attribute by using the prefix `@@`. Alternatively, you can specify a custom id in the `i18n` attribute by using the prefix `@@`.
The example below defines the custom id `introductionHeader`: The example below defines the custom id `introductionHeader`:
<code-example path='i18n/doc-files/app.component.html' region='i18n-attribute-solo-id' title='app/app.component.html' linenums="false"> <code-example path='i18n/doc-files/app.component.html' region='i18n-attribute-solo-id' title='app/app.component.html' linenums="false">
</code-example> </code-example>
@ -220,7 +220,7 @@ custom id.
</code-example> </code-example>
The custom id is persistent. The extractor tool does not change it when the translatable text changes. The custom id is persistent. The extractor tool does not change it when the translatable text changes.
Therefore, you do not need to update the translation. This approach makes maintenance easier. Therefore, you do not need to update the translation. This approach makes maintenance easier.
#### Use a custom id with a description #### Use a custom id with a description
@ -266,7 +266,7 @@ the same text, `Bonjour`:
<!-- ... --> <!-- ... -->
<p>Bonjour</p> <p>Bonjour</p>
``` ```
{@a no-element} {@a no-element}
@ -474,7 +474,7 @@ file. This information is not used by Angular, but external translation tools ma
## Translate text messages ## Translate text messages
The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src` The `ng xi18n` command generates a translation source file named `messages.xlf` in the project `src`
folder. folder.
The next step is to translate this source file into the specific language The next step is to translate this source file into the specific language
translation files. The example in this guide creates a French translation file. translation files. The example in this guide creates a French translation file.
@ -526,7 +526,7 @@ This sample file is easy to translate without a special editor or knowledge of F
</code-example> </code-example>
> This XML element represents the translation of the `<h1>` greeting tag that you marked with the > This XML element represents the translation of the `<h1>` greeting tag that you marked with the
`i18n` attribute earlier in this guide. `i18n` attribute earlier in this guide.
> Note that the translation unit `id=introductionHeader` is derived from the > Note that the translation unit `id=introductionHeader` is derived from the
[custom `id`](#custom-id "Set a custom id") that you set earlier, but [custom `id`](#custom-id "Set a custom id") that you set earlier, but
@ -573,7 +573,7 @@ To translate a `plural`, translate its ICU format match values:
<code-example path="i18n/doc-files/messages.fr.xlf.html" region="translated-plural" title="src/locale/messages.fr.xlf (&lt;trans-unit&gt;)" linenums="false"> <code-example path="i18n/doc-files/messages.fr.xlf.html" region="translated-plural" title="src/locale/messages.fr.xlf (&lt;trans-unit&gt;)" linenums="false">
</code-example> </code-example>
You can add or remove plural cases, with each language having its own cardinality. (See You can add or remove plural cases, with each language having its own cardinality. (See
[CLDR plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html).) [CLDR plural rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html).)
{@a translate-select} {@a translate-select}
@ -609,7 +609,7 @@ Here they are together, after translation:
{@a translate-nested} {@a translate-nested}
### Translate a nested expression ### Translate a nested expression
A nested expression is similar to the previous examples. As in the previous example, there are A nested expression is similar to the previous examples. As in the previous example, there are
two translation units. The first one contains the text outside of the nested expression: two translation units. The first one contains the text outside of the nested expression:
<code-example path="i18n/doc-files/messages.fr.xlf.html" region="translate-nested-1" title="src/locale/messages.fr.xlf (&lt;trans-unit&gt;)" linenums="false"> <code-example path="i18n/doc-files/messages.fr.xlf.html" region="translate-nested-1" title="src/locale/messages.fr.xlf (&lt;trans-unit&gt;)" linenums="false">
@ -683,28 +683,40 @@ You also need to instruct the AOT compiler to use your translation configuration
* `i18nLocale`: the locale id. * `i18nLocale`: the locale id.
``` ```
"configurations": { "build": {
... ...
"fr": { "configurations": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
... ...
"fr": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
...
}
}
},
"serve": {
...
"configurations": {
...
"fr": {
"browserTarget": "angular.io-example:build:fr"
}
} }
} }
``` ```
You then pass the configuration with the `ng serve` or `ng build` commands. You then pass the configuration with the `ng serve` or `ng build` commands.
The example below shows how to serve the French language file created in previous The example below shows how to serve the French language file created in previous
sections of this guide: sections of this guide:
<code-example language="sh" class="code-shell"> <code-example language="sh" class="code-shell">
ng serve --configuration=fr ng serve --configuration=fr
</code-example> </code-example>
For production builds, you define a separate `production-fr` build configuration in For production builds, you define a separate `production-fr` build configuration in
your `angular.json`. your `angular.json`.
``` ```