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

docs(core): update the i18n design doc (#31609) 

PR Close #31609
This commit is contained in:
Pete Bacon Darwin 2019-08-07 10:53:29 +01:00 committed by Misko Hevery
parent a7f61e63fa
commit fe5caca884
1 changed files with 230 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
packages/core/src/render3/i18n.md
View File

@ -1,8 +1,15 @@
# I18N # I18N translation support
Templates can be marked as requiring translation support via `i18n` and `i18n-...` attributes on elements.
Translation support involves mapping component template contents to **i18n messages**, which may contain interpolations, DOM elements and sub-templates.
This document describes how this support is implemented in Angular templates.
## Example of i18n message ## Example of i18n message
Given an i18n component: The following component definition illustrates how i18n works in Angular:
```typescript ```typescript
@Component({ @Component({
template: ` template: `
@ -21,26 +28,30 @@ Given an i18n component:
class MyComponent { class MyComponent {
} }
``` ```
NOTE:
- There really is only two kinds of i18n text.
1. In attribute as in `title` (with `i18n-title` present).
2. In element body marked as as `<div i18n>`.
- The element body i18n can have internal DOM structure which may consist of sub-templates.
## I18n Requirements NOTE:
The translation: - There are only two kinds of i18n messages:
- Must preserve DOM structure in i18n blocks because those DOM structures may have components and directives. 1. In the text of an attribute (e.g. `title` of `<div i18n-title title="Hello {{name}}!">`, indicated by the presence of the `i18n-title` attribute).
- The parsed instructions must stay in `TView.data`. 2. In the body of an element (e.g. `<div i18n>` indicated by the presence of the `i18n` attribute).
This is because in case of SSR we need to be able to execute multiple locales in the same VM. - The body of an element marked with `i18n` can contain internal DOM structure (e.g. other DOM elements).
(If instructions would be at a top level we could not have more than one parsed instruction.) - The internal structure of such an element may even contain Angular sub-templates (e.g. `ng-container` or `*ngFor` directives).
## Implementation overview
- i18n messages must preserve the DOM structure in elements marked with `i18n` because those DOM structures may have components and directives.
- **Parsed i18n messages** must live in `TView.data`. This is because in case of SSR we need to be able to execute multiple locales in the same VM.
(If parsed i18n messages are only at the top level we could not have more than one locale.)
The plan is to cache `TView.data` per locale, hence different instructions would get cached into different `TView.data` associated with a given locale. The plan is to cache `TView.data` per locale, hence different instructions would get cached into different `TView.data` associated with a given locale.
- NOTE: in SSR `goog.getMsg` will return an object literal of all of the locale translations. - NOTE: in SSR `goog.getMsg` will return an object literal of all of the locale translations.
### Generated code
Given the example component above, the Angular template compiler generates the following Ivy rendering instructions.
The compiler generates:
```typescript ```typescript
// These messages need to be retrieved from some localization service described later // These i18n messages need to be retrieved from a "localization service", described later.
const MSG_title = 'Hello <20>0<EFBFBD>!'; const MSG_title = 'Hello <20>0<EFBFBD>!';
const MSG_div_attr = ['title', MSG_title]; const MSG_div_attr = ['title', MSG_title];
const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural, const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural,
@ -74,50 +85,82 @@ class MyComponent {
elementEnd(); elementEnd();
} }
if (rf & RenderFlags.Update) { if (rf & RenderFlags.Update) {
i18nExp(bind(ctx.count)); // referenced by `<60>0<EFBFBD>` i18nExp(bind(ctx.name)); // referenced by `<60>0<EFBFBD>` in `MSG_title`
i18nApply(1); // Updates the `i18n-title` binding i18nApply(1); // Updates the `i18n-title` binding
i18nExp(bind(ctx.count)); // referenced by `<60>0<EFBFBD>` i18nExp(bind(ctx.count)); // referenced by `<60>0<EFBFBD>` in `MSG_div`
i18nApply(2); // Updates the `<div i18n>...</div>` i18nApply(2); // Updates the `<div i18n>...</div>`
} }
} }
}); });
} }
``` ```
The translated message can contain i18n placeholders (denoted by `<60>...<2E>`) which tell the translation how to interpolate the text.
The [<EFBFBD>](https://www.fileformat.info/info/unicode/char/fffd/index.htm) character was chosen because it is extremely unlikely to collide with existing text, and because it is generated, the developer should never encounter it.
Each i18n placeholder contains a number (and sub-template index) which provide binding information for the placeholder.
The i18n placeholders are:
- `<60>{index}(:{block})<29>`: *Binding Place Holder*:
Marks a location where an expression will be interpolated into.
The place holder `index` points to the expression binding index.
On optional `block` that matches the sub-template in which it was declared.
- `<60>#{index}(:{block})<29>`/`<60>/#{index}(:{block})<29>`: *Element Place Holder*:
Marks the beginning and end of DOM element that were embedded in the original translation block.
The place holder `index` points to the element index in the template instructions set.
On optional `block` that matches the sub-template in which it was declared.
- `<60>*{index}:{block}<7D>`/`<60>/*{index}:{block}<7D>`: *Sub-template Place Holder*:
Sub-templates must be split up and translated separately in each angular template function.
The `index` points to the `template` instruction index.
A `block` that matches the sub-template in which it was declared.
No other place holder format is supported. ### i18n markers (<28>...<2E>)
Each i18n message contains **i18n markers** (denoted by `<60>...<2E>`) which tell the renderer how to map the translated text onto the renderer instructions.
The [<EFBFBD>](https://www.fileformat.info/info/unicode/char/fffd/index.htm) character was chosen because it is extremely unlikely to collide with existing text, and because it is generated, the developer should never encounter it.
Each i18n marker contains an `index` (and optionally a `block`) which provide binding information for the marker.
The i18n markers are:
- `<60>{index}(:{block})<29>`: *Binding placeholder*: Marks a location where an interpolated expression will be rendered.
- `index`: the index of the binding within this i18n message block.
- `block` (*optional*): the index of the sub-template block, in which this placeholder was declared.
- `<60>#{index}(:{block})<29> ... <20>/#{index}(:{block})<29>`: *Element block*: Marks the beginning and end of a DOM element that is embedded in the original translation string.
- `index`: the index of the element, as defined in the template instructions (e.g. `elementStart(index, ...)`).
- `block` (*optional*): the index of the sub-template block, in which this element was declared.
- `<60>*{index}:{block}<7D>`/`<60>/*{index}:{block}<7D>`: *Sub-template block*: Marks a sub-template block that is translated separately in its own angular template function.
- `index`: the index of the `template` instruction, as defined in the template instructions (e.g. `template(index, ...)`).
- `block`: the index of the parent sub-template block, in which this child sub-template block was declared.
- `<60>!{index}:{block}<7D>/<2F>/!{index}:{block}<7D>`: *Projection block*: Marks the beginning and end of <ng-content> that was embedded in the original translation block.
- `index`: the index of the projection, as defined in the template instructions (e.g. `projection(index, ...)`).
- `block` (*optional*): the index of the parent sub-template block, in which this child sub-template block was declared.
No other i18n marker format is supported.
The i18n markers in the example above can be interpreted as follows:
```typescript
const MSG_title = 'Hello <20>0<EFBFBD>!';
const MSG_div_attr = ['title', MSG_title];
const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural,
=0 {no <b title="none">emails</b>!}
=1 {one <i>email</i>}
other {<7B>0:1<> <span title="<22>0:1<>">emails</span>}
}<7D>/#1:1<><31>/*3:1<>.`;
```
- `<60>0<EFBFBD>`: the `{{name}}` interpolated expression with index 0.
- `<60>*3:1<>`: the start of the `*ngIf` template with index 3, effectively defining sub-template block 1.
- `<60>/*3:1<>`: the end of the `*ngIf` template with index 3 (sub-template block 1).
- `<60>#1:1<>`: the start of the `<b>` element with index 1, found inside sub-template block 1.
- `<60>/#1:1<>`: the end of the `</b>` element with index 1, found inside sub-template block 1.
- `<60>0:1<>`: the binding expression `count` (both as the parameter `count` for the `plural` ICU and as the `{{count}}` interpolation) with index 0, found inside sub-template block 1.
NOTE: NOTE:
- Notice that the closing placeholder has the same information as the opening placeholder.
This is so that the parser can verify that opening and closing placeholders are properly nested.
Failure to properly nest the placeholders implies that the translator change the order of translation incorrectly and should be a runtime error.
- Note that the `block` id may be added to non-root templates.
Block must be properly nested.
It is an error for the translator to move a placeholder outside of its block, and will result in runtime error.
- Notice that all placeholders are globally unique within the translation string.
## Accumulator - Each closing i18n marker has the same information as its opening i18n marker.
This is so that the parser can verify that opening and closing i18n markers are properly nested.
Failure to properly nest the i18n markers implies that the translator changed the order of translation incorrectly and should be a runtime error.
- The optional `block` index is added to i18n markers contained within sub-template blocks.
This is because blocks must be properly nested and it is an error for the translator to move an i18n marker outside of its block. This will result in runtime error.
- i18n markers are unique within the translation string in which they are found.
For concatenating strings we use an accumulator.
### Rendering i18n messages
i18n messages are rendered by concatenating each piece of the string using an accumulator.
The pieces to be concatenated may be a substring from the i18n message or an index to a binding.
This is best explained through pseudo code: This is best explained through pseudo code:
```typescript ```typescript
function render18nString(i18nStringParts: string|number) {
const accumulator:string[] = []; const accumulator:string[] = [];
i18nStringParts.forEach(part => accumulate(part));
return accumulatorFlush(sanitizer);
/** /**
* Collect intermediate interpolation values. * Collect intermediate interpolation values.
@ -141,28 +184,32 @@ function accumulatorFlush(sanitizer: null|((text: string)=>string) = null): stri
accumulator.length = 0; accumulator.length = 0;
return interpolation; return interpolation;
} }
}
``` ```
## i18n Attributes ## i18n Attributes
Let's look at the simpler case of i18n and attribute interpolation. Rendering i18n attributes is straightforward:
```typescript ```html
// These messages need to be retrieved from some localization service described later <div i18n-title title="Hello {{name}}!">
const MSG_title = 'Hello <20>0<EFBFBD>!';
``` ```
Next notice the `i18nAttributes` instruction inside the `RenderFlags.Create` block.
The template compiler will generate the following statements inside the `RenderFlags.Create` block.
```typescript ```typescript
const MSG_title = 'Hello <20>0<EFBFBD>!'; const MSG_title = 'Hello <20>0<EFBFBD>!';
const MSG_div_attr = ['title', MSG_title]; const MSG_div_attr = ['title', MSG_title];
elementStart(0, 'div');
i18nAttributes(1, MSG_div_attr); i18nAttributes(1, MSG_div_attr);
``` ```
The above instruction checks the `TView.data` cache at position `1` and if empty will create `I18nUpdateOpCodes` like so:
The `i18nAttributes()` instruction checks the `TView.data` cache at position `1` and if empty will create `I18nUpdateOpCodes` like so:
```typescript ```typescript
const i18nUpdateOpCodes = <I18nUpdateOpCodes>[ const i18nUpdateOpCodes = <I18nUpdateOpCodes>[
// The following OpCodes represent: `<div i18n-title title="Hello <20>0<EFBFBD>!">` // The following OpCodes represent: `<div i18n-title title="Hello <20>0<EFBFBD>!">`
// If `changeMask & 0b11` // If `changeMask & 0b1`
// has changed then execute update OpCodes. // has changed then execute update OpCodes.
// has NOT changed then skip `7` values and start processing next OpCodes. // has NOT changed then skip `7` values and start processing next OpCodes.
0b1, 7, 0b1, 7,
@ -175,19 +222,34 @@ const i18nUpdateOpCodes = <I18nUpdateOpCodes>[
0 << SHIFT_REF | Attr, 'title', null, 0 << SHIFT_REF | Attr, 'title', null,
] ]
``` ```
NOTE: NOTE:
- `i18nAttributes` updates the attributes of the previous element. - The `i18nAttributes()` instruction updates the attributes of the "previous" element.
- If there is more than one attribute which needs to be internationalized it is added to the array as `[attributeName, translation]` tuple. - Each attribute to be translated is provided as a pair of elements in the array passed to the `i18nAttributes()` instruction (e.g. `['title', MSG_title, 'src', MSG_src, ...]`).
- Even attributes which don't have bindings must go through `i18nAttributes` so that they correctly work with i18n in server environment. - Even attributes that don't have bindings must go through `i18nAttributes()` so that they correctly work with i18n in a server environment.
## i18n Elements ## i18n Elements
Generating text inside existing elements is a bit more complicated but follows the same philosophy as attributes. Rendering i18n elements is more complicated but follows the same philosophy as attributes, with additional i18n markers.
First we define the message and mapping (which placeholders map to which expressions) as so: ```html
<div i18n>
{{count}} is rendered as:
<b *ngIf="exp">
{ count, plural,
=0 {no <b title="none">emails</b>!}
=1 {one <i>email</i>}
other {{{count}} <span title="{{count}}">emails</span>}
}
</b>.
</div>
```
The template compiler generates the following i18n message:
```typescript ```typescript
// These messages need to be retrieved from some localization service described later // This message is retrieved from a "localization service" described later
const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural, const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural,
=0 {no <b title="none">emails</b>!} =0 {no <b title="none">emails</b>!}
=1 {one <i>email</i>} =1 {one <i>email</i>}
@ -195,13 +257,13 @@ const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural,
}<7D>/#1:1<><31>/*3:1<>.`; }<7D>/#1:1<><31>/*3:1<>.`;
``` ```
### Exclusion Zones / Sub-Templates ### Sub-template blocks
Most i18n translations do not have sub-templates. Most i18n translated elements do not have sub-templates (e.g. `*ngIf`), but where they do the i18n message describes a **sub-template block** defined by `<60>*{index}:{block}<7D>` and `<60>/*{index}:{block}<7D>` markers.
For the rare case where a translation has a sub-template the sub-array describes an exclusion zone defined by `<60>*{index}:{block}<7D>` and `<60>/*{index}:{block}<7D>` marker. The sub-template block is extracted from the translation so it is as if there are two separate translated strings for parent and sub-template.
The exclusion zone is removed from the translation so in our case it is as if we had two separate translations for parent and sub-template.
Consider the following nested template:
Given nested template:
```html ```html
<div i18n> <div i18n>
List: List:
@ -213,9 +275,10 @@ Given nested template:
</div> </div>
``` ```
will generate The template compiler will generate the following translated string and instructions:
```typescript ```typescript
// Text broken down to allow addition of comments (Generated code will not have comments) // The string split across lines to allow addition of comments. The generated code does not have comments.
const MSG_div = const MSG_div =
'List: ' + 'List: ' +
'<27>*2:1<>' + // template(2, MyComponent_NgIf_Template_0, ...); '<27>*2:1<>' + // template(2, MyComponent_NgIf_Template_0, ...);
@ -226,13 +289,14 @@ const MSG_div =
'<27>/#1:2<>' + '<27>/#1:2<>' +
'<27>/*2:2<>' + '<27>/*2:2<>' +
'<27>/#1:1<>' + '<27>/#1:1<>' +
'<27>*2:1<>' + '<27>/*2:1<>' +
'Summary: ' + 'Summary: ' +
'<27>*3:3<>' + // template(3, MyComponent_NgIf_Template_2, ...); '<27>*3:3<>' + // template(3, MyComponent_NgIf_Template_2, ...);
'<27>#1:3<>' + // element(1, 'span'); '<27>#1:3<>' + // element(1, 'span');
'<27>#1:3<>' + '<27>/#1:3<>' +
'<27>*3:3<>'; '<27>/*3:3<>';
// <20>*2:2<> ... <20>/*2:2<> (`*ngFor` template, instruction index 2, inside the `*ngIf` template, sub-template block 1)
function MyComponent_NgIf_NgFor_Template_1(rf: RenderFlags, ctx: any) { function MyComponent_NgIf_NgFor_Template_1(rf: RenderFlags, ctx: any) {
if (rf & RenderFlags.Create) { if (rf & RenderFlags.Create) {
i18nStart(0, MSG_div, 2); // 2nd `*` content: `<60>#1:2<>item<65>/#1:2<>` i18nStart(0, MSG_div, 2); // 2nd `*` content: `<60>#1:2<>item<65>/#1:2<>`
@ -242,6 +306,7 @@ function MyComponent_NgIf_NgFor_Template_1(rf: RenderFlags, ctx: any) {
... ...
} }
// <20>*2:1<> ... <20>/*2:1<>
function MyComponent_NgIf_Template_0(rf: RenderFlags, ctx: any) { function MyComponent_NgIf_Template_0(rf: RenderFlags, ctx: any) {
if (rf & RenderFlags.Create) { if (rf & RenderFlags.Create) {
i18nStart(0, MSG_div, 1); // 1st `*` content: `<60>#1:1<><31>*2:2<><32>/*2:2<><32>/#1:1<>` i18nStart(0, MSG_div, 1); // 1st `*` content: `<60>#1:1<><31>*2:2<><32>/*2:2<><32>/#1:1<>`
@ -253,6 +318,7 @@ function MyComponent_NgIf_Template_0(rf: RenderFlags, ctx: any) {
... ...
} }
// <20>*3:3<> ... <20>/*3:3<>
function MyComponent_NgIf_Template_2(rf: RenderFlags, ctx: any) { function MyComponent_NgIf_Template_2(rf: RenderFlags, ctx: any) {
if (rf & RenderFlags.Create) { if (rf & RenderFlags.Create) {
i18nStart(0, MSG_div, 3); // 3rd `*` content: `<60>#1:3<><33>/#1:3<>` i18nStart(0, MSG_div, 3); // 3rd `*` content: `<60>#1:3<><33>/#1:3<>`
@ -282,14 +348,16 @@ class MyComponent {
### `i18nStart` ### `i18nStart`
It is the job of the instruction `i18nStart` to parse the messages and to fill in the translation blocks with text. It is the job of the instruction `i18nStart` to parse the i18n message and to provide the appropriate text to each of the following instructions.
(Notice that in i18n-block the DOM element instructions are retained, but the text instructions have been stripped.)
Note:
- Inside a block that is marked with `i18n` the DOM element instructions are retained, but the text instructions have been stripped.
```typescript ```typescript
i18nStart( i18nStart(
2, // storage of the parsed message instructions 2, // storage of the parsed message instructions
MSG_div, // The message to parse which has been translated MSG_div, // The i18n message to parse which has been translated
// Optional sub-template index. Empty implies `0` (most common) // Optional sub-template block index. Empty implies `0` (most common)
); );
... ...
i18nEnd(); // The instruction which is responsible for inserting text nodes into i18nEnd(); // The instruction which is responsible for inserting text nodes into
@ -332,7 +400,7 @@ const tI18n = <TI18n>{
NOTE: NOTE:
- position `2` has `i18nStart` and so it is not a real DOM element, but it should act as if it was a DOM element. - position `2` has `i18nStart` and so it is not a real DOM element, but it should act as if it was a DOM element.
### `i18nStart` in sub-template ### `i18nStart` in sub-template blocks
```typescript ```typescript
i18nStart( i18nStart(
@ -347,7 +415,6 @@ This means that the instruction has to extract out 1st sub-block from the root-t
Starting with Starting with
```typescript ```typescript
// These messages need to be retrieved from some localization service described later
const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural, const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural,
=0 {no <b title="none">emails</b>!} =0 {no <b title="none">emails</b>!}
=1 {one <i>email</i>} =1 {one <i>email</i>}
@ -355,7 +422,7 @@ const MSG_div = `<60>0<EFBFBD> is rendered as: <20>*3:1<><31>#1:1<>{<7B>0:1<>, plural,
}<7D>/#1:1<><31>/*3:1<>.`; }<7D>/#1:1<><31>/*3:1<>.`;
``` ```
The `i18nStart` instruction traverses `MSG_div` and looks for 1st sub-template marked with `<60>*3:1<>`. The `i18nStart` instruction traverses `MSG_div` and looks for 1st sub-template block marked with `<60>*3:1<>`.
Notice that the `<60>*3:1<>` contains index to the DOM element `3`. Notice that the `<60>*3:1<>` contains index to the DOM element `3`.
The rest of the code should work same as described above. The rest of the code should work same as described above.
@ -523,7 +590,7 @@ Assume we have translation like so: `<div i18n>Hello {{name}}!</div>`.
The above calls generates the following template instruction code: The above calls generates the following template instruction code:
```typescript ```typescript
// These messages need to be retrieved from some localization service described later // This message will be retrieved from some localization service described later
const MSG_div = 'Hello <20>0<EFBFBD>!'; const MSG_div = 'Hello <20>0<EFBFBD>!';
template: function(rf: RenderFlags, ctx: MyComponent) { template: function(rf: RenderFlags, ctx: MyComponent) {
@ -975,9 +1042,6 @@ const tI18n = <TI18n>{
} }
``` ```
# Translation Message Retrieval # Translation Message Retrieval
The generated code needs work with: The generated code needs work with:
@ -985,9 +1049,10 @@ The generated code needs work with:
- Non-closure: This requires the use of Angular service to retrieve the translation string. - Non-closure: This requires the use of Angular service to retrieve the translation string.
- Server Side: All translations need to be retrieved so that one server VM can respond to all locales. - Server Side: All translations need to be retrieved so that one server VM can respond to all locales.
The solution is to take advantage of compile time constants like so: The solution is to take advantage of compile time constants (e.g. `CLOSURE`) like so:
```typescript ```typescript
import {localize} from '@angular/core'; import '@angular/localize';
let MSG_hello; let MSG_hello;
if (CLOSURE) { if (CLOSURE) {
@ -998,7 +1063,7 @@ if (CLOSURE) {
MSG_hello = MSG_hello_; MSG_hello = MSG_hello_;
} else { } else {
// This would work in non-closure mode, and can work for both browser and SSR use case. // This would work in non-closure mode, and can work for both browser and SSR use case.
MSG_hello = localize('31451231531' /** representing 'Hello World!' message id*/); MSG_hello = $localize`Hello World!`;
} }
const MSG_div_attr = ['title', MSG_hello]; const MSG_div_attr = ['title', MSG_hello];
@ -1016,7 +1081,7 @@ class MyComponent {
``` ```
NOTE: NOTE:
- The compile time constant is important because when the generated code is shipped to NPM it must contain all formats, because at the time of packaging it is not known how the final application will be bundled. - The compile time constant (`CLOSURE`) is important because when the generated code is shipped to NPM it must contain all formats, because at the time of packaging it is not known how the final application will be bundled.
- Alternatively because we already ship different source code for closure we could generated different code for closure folder. - Alternatively because we already ship different source code for closure we could generated different code for closure folder.