docs(i18n): add new features #2740

Foxandxss · 2016-11-02T21:29:30Z

@vicb please review that everything I said about ICU and CLDR are correct.

I ignored the plural/select with markup until angular/angular#12636 is resolved.

There is an alert that starts with "repeat the extraction process ..." I don't know where to put it :/

And there are a few links that would be nice to add, somewhere:

http://formatjs.io/guides/message-syntax/
http://cldr.unicode.org/index/cldr-spec/plural-rules
http://www.unicode.org/cldr/charts/29/supplemental/language_plural_rules.html (This one could be good into "Plurals" too)
http://userguide.icu-project.org/formatparse/messages

vicb · 2016-11-02T21:30:39Z

I ignored the plural/select with markup until angular/angular#12636 is resolved.

Could you please have a PR ready ?

vicb · 2016-11-02T21:31:31Z

public/docs/ts/latest/cookbook/i18n.jade

    * [Merge the completed translation file into the app](#merge)
      * [JiT configuration](#jit)
      * [AoT configuration](#aot)

 :marked
-  **Try this** <live-example name="cb-i18n">live example</live-example> of a JiT-compiled app, translated into French.
+  **Try this** <live-example name="cb-i18n">live example</live-example> of a JiT-compiled app, translated into Spanish.


Sorry, I know no French :(

vicb · 2016-11-02T21:33:42Z

public/docs/ts/latest/cookbook/i18n.jade

@@ -92,6 +95,79 @@ a#i18n-attribute
  The Angular extraction tool preserves both the _meaning_ and the _description_ in the translation source file
  to facilitiate contextually-specific translations.

+  As an alternative, if you want to translate some content without having to create a new element, you can use a `<ng-container>`


"As an alternative" to what ?

alternative to use a tag that generates an element. But it can be confusing, agreed.

vicb · 2016-11-02T21:35:37Z

public/docs/ts/latest/cookbook/i18n.jade

@@ -92,6 +95,79 @@ a#i18n-attribute
  The Angular extraction tool preserves both the _meaning_ and the _description_ in the translation source file
  to facilitiate contextually-specific translations.

+  As an alternative, if you want to translate some content without having to create a new element, you can use a `<ng-container>`


l 93
"While all appearance of a message with the same meaning should have the same"
should have -> have

" The Angular extraction tool preserves both the meaning and the description in the translation source file to facilitiate contextually-specific translations."

-> that might not be true depending on the serialization format

As in "xliff not outputting ICU"?

vicb · 2016-11-02T21:36:00Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-ng-container', 'app/app.component.html')(format=".")
+
+:marked
+  You can also use a comment to get the same result:


a comment -> a pair of comments

vicb · 2016-11-02T21:36:22Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-alt', 'app/app.component.html')(format=".")
+
+:marked
+  Such attribute needs to be translated as well, and `Angular` provides you another attribute: `i18n-x` where you replace


where x is the name of ...

vicb · 2016-11-02T21:37:23Z

public/docs/ts/latest/cookbook/i18n.jade

+
+:marked
+  Such attribute needs to be translated as well, and `Angular` provides you another attribute: `i18n-x` where you replace
+  the `x` with the name of the attribute to translate. So the previous example would end like:


" So the previous example would end like" -> in order to translate the xxx on the yyyy tag from the previous ex, you would write:

vicb · 2016-11-02T21:38:30Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-alt-translate', 'app/app.component.html')(format=".")
+
+:marked
+  This attribute also supports defining a meaning and description like `i18n`.


To define a m and d for an attribute use the notationb i18n-x="m|d"

vicb · 2016-11-02T21:39:12Z

public/docs/ts/latest/cookbook/i18n.jade

+a#plural
+:marked
+  ## Plurals
+  You have an application that counts animals. You need to keep in mind that it is `one wolf` but also `two wolves`.


Also different languages could have different number of plural forms

vicb · 2016-11-02T21:40:03Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-plural', 'app/app.component.html')(format=".")
+
+:marked
+  * The first parameter is the key, which is a variable in your component that counts how many wolves we have.


The first parameter is a variable that counts how many wolves we have ?

Is this a question of why I put that or a suggested change for the sentence?

Leave this to Ward. See response below.

vicb · 2016-11-02T21:40:17Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-plural', 'app/app.component.html')(format=".")
+
+:marked
+  * The first parameter is the key, which is a variable in your component that counts how many wolves we have.


mention that this is ICU syntax ?

I do in a box a bit below.

vicb · 2016-11-02T21:40:49Z

public/docs/ts/latest/cookbook/i18n.jade

+:marked
+  * The first parameter is the key, which is a variable in your component that counts how many wolves we have.
+  * The second parameter indicates that you are using the `plural form`.
+  * The third parameter is the matches, in other words, how you define your plurals.


"The remaining parameters are the plural cases" ???

Leave this to Ward. See response below.

vicb · 2016-11-02T21:42:29Z

public/docs/ts/latest/cookbook/i18n.jade

+
+  CLDR uses some tags to define plural categories, here is a few of them:
+
+  * zero / =0


one and =1 are NOT the same (one def varies across languages, see your link above).
categories (zero, one, ...) and values (=...) are distinct.
This should be explained clearly (ie taking two langs as example ?)

vicb · 2016-11-02T21:44:01Z

public/docs/ts/latest/cookbook/i18n.jade

+  You can use either a word like `zero` or `=0`.
+
+  Along the category, you add the default _English_ translation, so for 2 wolves you can say `two {two wolves}` or `=2 {two wolves}`.
+  If you use `other`, any non matched number will use the `other` translation.


Note for later: # will be replaced by the count value as speced in ICU (not supported yet)

Explain that value match first (=...) then categories whatever the order in the src

vicb · 2016-11-02T21:44:30Z

public/docs/ts/latest/cookbook/i18n.jade

+a#select
+:marked
+  ## Select
+  A select is pretty much like a plural, but instead of giving a different value based on a number, you give


"is pretty much like a plural but different" isn't really valuable

vicb · 2016-11-02T21:53:31Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-select', 'app/app.component.html')(format=".")
+
+:marked
+  It has the same syntax as plural. First we define our variable, then the `select form` and last how we define our select.


" It has the same syntax as plural." I would say ICU syntax (Saying it's the same but different as little value IMO)

vicb · 2016-11-02T21:54:12Z

public/docs/ts/latest/cookbook/i18n.jade


  Follow the same convention for each target language.

-  ### Translate
-  In the real world, you send the `messages.fr.xlf` file to a French translator who would fill in the translations
+  ### Translate text nodes


+ text nodes ????

I explain how to translate different things and stuff like <div i18n>what gets in here</div> are called text nodes . So I can't leave only "Translate" because there are more translate sections next to it.

vicb · 2016-11-02T21:54:52Z

public/docs/ts/latest/cookbook/i18n.jade

 :marked
  Note that the `id` is generated by the tool. Don't touch it.
  Its value depends on the content of the message and its assigned meaning.
  Change either factor and the `id` changes as well.
+
+  Translating the text nodes within the `<ng-container>`, `<!--i18n-->` and also the attributes with `i18n-x` are done in the same way:


removw this no added value here IMO

Thought 3 times about that, but I like to give the user everything and I don't want them wondering how to translate those 3 sentences to spanish, so I give them the result and we are happy with that.

That being said, you can see the whole translation at the end. Will give Ward the last word.

vicb · 2016-11-02T21:55:18Z

public/docs/ts/latest/cookbook/i18n.jade

+
+:marked
+  ### Translate plural and select
+  To translate a `plural` or a `select`, you provide the same ICU string but changing the matches:


once again same but different is not the same, drop this part

Sorry, is this the right comment for that sentence? I am not saying "same but different" in here.

I could say "To translate an ICU, provide...." but I prefer to say "plural" or a "select". same thing, yes, but I think people will understand it better if I use those words.

vicb · 2016-11-02T21:55:56Z

public/docs/ts/latest/cookbook/i18n.jade

+makeExample('cb-i18n/ts/locale/trans-unit.html', 'translate-select-node', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
+
+:marked
+  So, what is that `<x id="ICU">`? That tag is like a _placeholder_ that represents the ICU. Translate the text


"That tag is like a placeholder" -> "That tag a placeholder"

vicb · 2016-11-02T21:57:03Z

public/docs/ts/latest/cookbook/i18n.jade

+.alert.is-helpful
+  :marked
+    Notice that for plural and select, there is nothing in the `<source>` tag.
+    As today, ICU are not supported yet with xliff, but they are with xmb.


As of today, then remove yet

vicb · 2016-11-02T21:57:22Z

public/docs/ts/latest/cookbook/i18n.jade

+
+.l-main-content
+:marked
+  The application is completely translated. Let's make use of it.


Foxandxss · 2016-11-02T23:00:33Z

For @wardbell:

There is a section that says:

* The first parameter is the key, which is a variable in your component that counts how many wolves we have.
* The second parameter indicates that you are using the `plural form`.
* The third parameter is the matches, in other words, how you define your plurals.

Reason is that verbose is because this page defines the syntax like {key, plural, matches} so I tried to map that syntax there. If you decide to leave that, you could add the link as well as context.

When I do the translate, I show everything (that is our way at the end), but the part of the ng-container / comment / i18n-alt doesn't show too much new. We say "You don't need to know spanish" so I didn't want to let people imagine how to translate those things to spanish so I show that anyway.

We show the entire file a bit ahead, so up to you.

vicb · 2016-11-11T22:01:56Z

What is the status of this PR ?
Would love to see doc updated soon.
/cc @wardbell

wardbell · 2016-12-01T05:25:47Z

I squashed the original 3 commits and added a 4th with my touches.

I researched and improved the links to CLDR and ICU. Replaced alt (which doesn't work) with title (which does).

@vicb should give it a quick look before we merge.

I'm concerned that a few things do NOT work as advertised:

I couldn't get any of the spelled out plural categories to work (zero, one, two). Fortunately, "other" works.
The elements that aren't supposed to show (<ng-container> and the i18n in a comment) DO show

I don't know if these are bugs in i18n or in our effort to document it. Either way, I'd like to know before I approve for merge into master.

vicb · 2016-12-01T06:00:49Z

Replaced alt (which doesn't work) with title (which does).

It it is the case it's a bug. Do you have a repro ?

en locale has only one and other (category and their ~range is defined per locale)
show where ?

vicb · 2016-12-01T06:09:36Z

public/docs/_examples/cb-i18n/ts/app/app.component.1.html

@@ -9,3 +9,7 @@ <h1 i18n>Hello i18n!</h1>
 <!--#docregion i18n-attribute-desc-->
 <h1 i18n="An introduction header for this sample">Hello i18n!</h1>
 <!--#enddocregion i18n-attribute-desc-->
+
+<!--#docregion i18n-title-->
+<img [src]="logo" title="Angular 2 logo">


what is this, there should be an i18n-title attribute if the title needs to be translated

This file is a precursor to the final app.component.html. The title step hasn't occurred yet. It's ok

vicb · 2016-12-01T06:10:10Z

public/docs/_examples/cb-i18n/ts/app/app.component.html

+
+<!--#docregion i18n-ng-container-->
+<ng-container i18n>I don't output any element</ng-container>


you just don't output the ng-container tag sir

"I don't output any element"
do we want to keep this ? same for comments

vicb · 2016-12-01T06:10:48Z

public/docs/_examples/cb-i18n/ts/app/app.component.html

+<!--#docregion i18n-with-comment-->
+<!--i18n: optional meaning|optional description -->
+I don't output any element either


why ?
comments are only markers for content to be translated

Ok so this is another way to translate something w/o putting a DOM element in. Who cares?

It was in place before ng-container exists.
If you remember we decided (I discussed) that ng-container should be the preferred way to do things (over template and other stuff).
+1 to remove this from the docs if you want to do so,

vicb · 2016-12-01T06:11:41Z

public/docs/_examples/cb-i18n/ts/app/app.component.html

+<button (click)="inc(1)">+</button> <button (click)="inc(-1)">-</button>
+<!--#docregion i18n-plural-->
+<span i18n>{wolves, plural, zero {no wolves} =1 {one wolf} two {two wolves} other {a wolf pack}}</span>


zero / two are undefined in english. should be =0 / =2

I think we should just skip the "zero" "one" "two" thing.

vicb · 2016-12-01T06:12:58Z

public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf

+      </trans-unit>
+      <trans-unit id="38658218c31a8342093978c7e1b2de2e63fd55c6" datatype="html">
+        <source/>
+        <target>{wolves, plural, =0 {ningún lobo} =1 {un lobo} =2 {dos lobos} other {una horda de lobos}}</target>


this one is correct here

vicb · 2016-12-01T06:14:20Z

public/docs/ts/latest/cookbook/i18n.jade

  a message with *different meanings* could have different translations.
  The Angular extraction tool preserves both the _meaning_ and the _description_ in the translation source file
  to facilitiate contextually-specific translations.

+  Also, if you want to translate some content without having to create a new element, you can use a `<ng-container>`
+  which doesn't get renderered in the DOM:


this might not be very clear but it means that the tag is not rendered, the content is

Wasn't clear to me at all. I think I can fix that. But why care if the tag is rendered or not? Why not just use a span?

I'll clarify the prose ... in case someone really does care.

yep extra markup can mess with your css, ...

vicb · 2016-12-01T06:16:01Z

public/docs/ts/latest/cookbook/i18n.jade

+  * The third parameter defines a pluralization pattern consisting of pluralization categories and their matching values.
+
+  Pluralization categories include:
+  * =0 / zero


"=0 / zero" is wrong. Category and discrete values are different things

"five" is not a valid category name

"zero" did not work

once again en locale as only one and other

I deleted this. Just have =n now.

vicb · 2016-12-01T06:18:09Z

public/docs/ts/latest/cookbook/i18n.jade

+    <a href="http://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules" target="_blank" title="Pluralization Rules">pluralization rules</a>.
+
+    The category `=1` matches the count of `1` exactly. 
+    The category `one` matches any count with a `1` digit in it such as `1` or `21`, 


this is only true in Belarusian - I don't think the docs express that clearly

Do we really need this in the docs? The pluralization rules just get weirder and weirder the more you read about them. Our docs don't seem like the right place for this.

vicb · 2016-12-01T06:18:56Z

public/docs/ts/latest/cookbook/i18n.jade

+    The category `=1` matches the count of `1` exactly. 
+    The category `one` matches any count with a `1` digit in it such as `1` or `21`, 
+    something you'd need to do if counting wolves in Belarusian.
+    Categories like `=1` take precedence over categories like `one`.


this is true in english, not necessarily in other langs.

Let's just cut this section.

Deleted this passage.

vicb · 2016-12-01T06:20:04Z

public/docs/ts/latest/cookbook/i18n.jade

+  by adding the `--i18nFormat=xmb` flag.
+
+code-example(language="sh" class="code-shell").
+  ./node_modules/.bin/ng-xi18n  --i18nFormat=xmb


why do we have 2 ws before --i18nFormat, I guess it's a placeholder for -p path/to/tsconfig ?

seen this documented later on, thanks

vicb · 2016-12-01T06:21:16Z

public/docs/ts/latest/cookbook/i18n.jade

+  Now you can issue command variations such as these:
+code-example(language="sh" class="code-shell").
+  npm run i18n
+  npm run i18n -- -p path/to/tsconfig.json


I guess that if you add an npm scripts, you want to add options there.

You MUST have -- before the flags or ne marche pas

I mean you never want to write npm run i18n -- -p path/to/tsconfig.json but npm run i18n and put the flag in your package.json

Yup. That's the way you have to do it.

wardbell · 2016-12-01T07:00:15Z

@vicb Looks like with my last updates all pending concerns have been addressed. Ready to merge.

vicb · 2016-12-01T07:05:19Z

public/docs/ts/latest/cookbook/i18n.jade

  a message with *different meanings* could have different translations.
  The Angular extraction tool preserves both the _meaning_ and the _description_ in the translation source file
  to facilitiate contextually-specific translations.

+  ### Translate text without creating an element
+
+  Suppose there is a stretch of text that you'd like to translate.


could also be siblings nodes

Yes. I think we don't have to explain all the reasons you'd do this. The CSS one was compelling enough.

googlebot added the CLA: yes label Nov 2, 2016

vicb reviewed Nov 2, 2016

View reviewed changes

vicb mentioned this pull request Nov 11, 2016

i18n of interpolated strings angular/angular#12819

Closed

vicb mentioned this pull request Nov 28, 2016

[i18n] future 2.x plan angular/angular#9104

Closed

21 tasks

This was referenced Dec 1, 2016

ng-xi18n -p is not documented #2909

Closed

[Discussion] angular-cli and i18n (ng-xi18n + ngc) angular/angular-cli#2201

Closed

wardbell force-pushed the i18n-new-features branch from 68d9c94 to 7a4da88 Compare December 1, 2016 05:22

googlebot added the CLA: no label Dec 1, 2016

wardbell force-pushed the i18n-new-features branch 2 times, most recently from d7626cf to 1b4ca2f Compare December 1, 2016 05:59

wardbell force-pushed the i18n-new-features branch from 1b4ca2f to d793e76 Compare December 1, 2016 06:02

vicb reviewed Dec 1, 2016

View reviewed changes

wardbell force-pushed the i18n-new-features branch from d793e76 to 1a104a7 Compare December 1, 2016 06:58

wardbell added the pr_state: LGTM label Dec 1, 2016

vicb reviewed Dec 1, 2016

View reviewed changes

wardbell force-pushed the i18n-new-features branch 2 times, most recently from 396181c to f47020f Compare December 1, 2016 10:09

docs(i18n): add new features

30f7c9f

wardbell force-pushed the i18n-new-features branch 2 times, most recently from 46c6f03 to bf7abad Compare December 2, 2016 07:22

docs(i18n): add new features - Ward's touches

bdf1f63

wardbell force-pushed the i18n-new-features branch from bf7abad to bdf1f63 Compare December 2, 2016 07:36

wardbell merged commit 9fd3fa0 into angular:master Dec 3, 2016

wardbell deleted the i18n-new-features branch December 3, 2016 01:25


		CLDR uses some tags to define plural categories, here is a few of them:

		* zero / =0


		<!--#docregion i18n-ng-container-->
		<ng-container i18n>I don't output any element</ng-container>

docs(i18n): add new features #2740

docs(i18n): add new features #2740

Uh oh!

Conversation

Foxandxss commented Nov 2, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vicb commented Nov 2, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Foxandxss commented Nov 2, 2016

Uh oh!

vicb commented Nov 11, 2016

Uh oh!

wardbell commented Dec 1, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Foxandxss commented Nov 2, 2016 •

edited

Loading

wardbell commented Dec 1, 2016 •

edited

Loading