From 9fd3fa037d24b46da6b67bb061ce8c856932aa94 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Rodr=C3=ADguez?= <Foxandxss@gmail.com>
Date: Sat, 3 Dec 2016 02:25:31 +0100
Subject: [PATCH] docs(i18n): add new features (#2740)

---
 public/docs/_examples/cb-i18n/e2e-spec.ts     |  24 +-
 public/docs/_examples/cb-i18n/ts/.gitignore   |   3 +-
 .../cb-i18n/ts/app/app.component.1.html       |   4 +
 .../cb-i18n/ts/app/app.component.html         |  32 +-
 .../_examples/cb-i18n/ts/app/app.component.ts |  12 +-
 .../cb-i18n/ts/app/i18n-providers.ts          |   2 +-
 public/docs/_examples/cb-i18n/ts/index.html   |   2 +-
 .../cb-i18n/ts/locale/messages.es.xlf         |  41 +++
 .../cb-i18n/ts/locale/messages.es.xlf.html    |  54 +++
 .../cb-i18n/ts/locale/messages.fr.xlf         |  13 -
 .../cb-i18n/ts/locale/messages.fr.xlf.html    |  17 -
 .../cb-i18n/ts/locale/trans-unit.html         |   7 -
 public/docs/_examples/cb-i18n/ts/messages.xlf |  41 +++
 public/docs/_examples/cb-i18n/ts/plnkr.json   |   4 +-
 public/docs/ts/latest/cookbook/i18n.jade      | 314 ++++++++++++++----
 public/docs/ts/latest/guide/change-log.jade   |   5 +
 16 files changed, 466 insertions(+), 109 deletions(-)
 create mode 100644 public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf
 create mode 100644 public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf.html
 delete mode 100644 public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf
 delete mode 100644 public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf.html
 delete mode 100644 public/docs/_examples/cb-i18n/ts/locale/trans-unit.html
 create mode 100644 public/docs/_examples/cb-i18n/ts/messages.xlf

diff --git a/public/docs/_examples/cb-i18n/e2e-spec.ts b/public/docs/_examples/cb-i18n/e2e-spec.ts
index f3249272af..ee66ff6683 100644
--- a/public/docs/_examples/cb-i18n/e2e-spec.ts
+++ b/public/docs/_examples/cb-i18n/e2e-spec.ts
@@ -1,4 +1,4 @@
-'use strict'; // necessary for es6 output in node 
+'use strict'; // necessary for es6 output in node
 
 import { browser, element, by } from 'protractor';
 
@@ -8,8 +8,26 @@ describe('i18n E2E Tests', () => {
     browser.get('');
   });
 
-  it('should display i18n translated welcome: Bonjour i18n!', function () {
-    expect(element(by.css('h1')).getText()).toEqual('Bonjour i18n!');
+  it('should display i18n translated welcome: ¡Hola i18n!', function () {
+    expect(element(by.css('h1')).getText()).toEqual('¡Hola i18n!');
+  });
+
+  it('should display the node texts without elements', function () {
+    expect(element(by.css('my-app')).getText()).toContain('No genero ningún elemento');
+    expect(element(by.css('my-app')).getText()).toContain('Yo tampoco genero ningún elemento');
+  });
+
+  it('should display the translated title attribute', function () {
+    const title = element(by.css('img')).getAttribute('title');
+    expect(title).toBe('Logo de Angular 2');
+  });
+
+  it('should display the plural of: a horde of wolves', function () {
+    expect(element.all(by.css('span')).get(0).getText()).toBe('ningún lobo');
+  });
+
+  it('should display the select of gender', function () {
+    expect(element.all(by.css('span')).get(1).getText()).toBe('El heroe es mujer');
   });
 
 });
diff --git a/public/docs/_examples/cb-i18n/ts/.gitignore b/public/docs/_examples/cb-i18n/ts/.gitignore
index 8357331dc7..0aa8a6416f 100644
--- a/public/docs/_examples/cb-i18n/ts/.gitignore
+++ b/public/docs/_examples/cb-i18n/ts/.gitignore
@@ -1,6 +1,5 @@
 **/*.ngfactory.ts
 **/*.metadata.json
-**/messages.xlf
 dist
 !app/tsconfig.json
-!rollup.js
\ No newline at end of file
+!rollup.js
diff --git a/public/docs/_examples/cb-i18n/ts/app/app.component.1.html b/public/docs/_examples/cb-i18n/ts/app/app.component.1.html
index 7813de7d31..cc19182338 100644
--- a/public/docs/_examples/cb-i18n/ts/app/app.component.1.html
+++ b/public/docs/_examples/cb-i18n/ts/app/app.component.1.html
@@ -9,3 +9,7 @@
 <!--#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">
+<!--#enddocregion i18n-title-->
diff --git a/public/docs/_examples/cb-i18n/ts/app/app.component.html b/public/docs/_examples/cb-i18n/ts/app/app.component.html
index 3469b42e86..7c5562bece 100644
--- a/public/docs/_examples/cb-i18n/ts/app/app.component.html
+++ b/public/docs/_examples/cb-i18n/ts/app/app.component.html
@@ -1,4 +1,34 @@
 <!--#docregion-->
 <!--#docregion i18n-attribute-meaning-->
 <h1 i18n="User welcome|An introduction header for this sample">Hello i18n!</h1>
-<!--#enddocregion i18n-attribute-meaning-->
\ No newline at end of file
+<!--#enddocregion i18n-attribute-meaning-->
+
+<!--#docregion i18n-ng-container-->
+<ng-container i18n>I don't output any element</ng-container>
+<!--#enddocregion i18n-ng-container-->
+
+<br />
+
+<!--#docregion i18n-with-comment-->
+<!--i18n: optional meaning|optional description -->
+I don't output any element either
+<!--/i18n-->
+<!--#enddocregion i18n-with-comment-->
+
+<br />
+
+<!--#docregion i18n-title-translate-->
+<img [src]="logo" i18n-title title="Angular 2 logo" />
+<!--#enddocregion i18n-title-translate-->
+<br>
+<button (click)="inc(1)">+</button> <button (click)="inc(-1)">-</button>
+<!--#docregion i18n-plural-->
+<span i18n>{wolves, plural, =0 {no wolves} =1 {one wolf} =2 {two wolves} other {a wolf pack}}</span>
+<!--#enddocregion i18n-plural-->
+({{wolves}})
+<br><br>
+<button (click)="male()">&#9794;</button> <button (click)="female()">&#9792;</button>
+<!--#docregion i18n-select-->
+<span i18n>The hero is {gender, select, m {male} f {female}}</span>
+<!--#enddocregion i18n-select-->
+<br>
diff --git a/public/docs/_examples/cb-i18n/ts/app/app.component.ts b/public/docs/_examples/cb-i18n/ts/app/app.component.ts
index e065c38917..e8f93321a4 100644
--- a/public/docs/_examples/cb-i18n/ts/app/app.component.ts
+++ b/public/docs/_examples/cb-i18n/ts/app/app.component.ts
@@ -6,5 +6,15 @@ import { Component } from '@angular/core';
   selector: 'my-app',
   templateUrl: 'app.component.html'
 })
-export class AppComponent { }
+export class AppComponent {
+  wolves = 0;
+  gender = 'f';
+  fly = true;
+  logo = 'https://angular.io/resources/images/logos/angular2/angular.png';
+  inc(i: number) {
+    this.wolves = Math.min(5, Math.max(0, this.wolves + i));
+  }
+  male()   { this.gender = 'm'; }
+  female() { this.gender = 'f'; }
+}
 
diff --git a/public/docs/_examples/cb-i18n/ts/app/i18n-providers.ts b/public/docs/_examples/cb-i18n/ts/app/i18n-providers.ts
index 84328f0d22..f0bb662dc3 100644
--- a/public/docs/_examples/cb-i18n/ts/app/i18n-providers.ts
+++ b/public/docs/_examples/cb-i18n/ts/app/i18n-providers.ts
@@ -14,7 +14,7 @@ export function getTranslationProviders(): Promise<Object[]> {
     return Promise.resolve(noProviders);
   }
 
-  // Ex: 'locale/messages.fr.xlf`
+  // Ex: 'locale/messages.es.xlf`
   const translationFile = `./locale/messages.${locale}.xlf`;
 
   return getTranslationsWithSystemJs(translationFile)
diff --git a/public/docs/_examples/cb-i18n/ts/index.html b/public/docs/_examples/cb-i18n/ts/index.html
index fc88d9284e..9a5fa496c5 100644
--- a/public/docs/_examples/cb-i18n/ts/index.html
+++ b/public/docs/_examples/cb-i18n/ts/index.html
@@ -18,7 +18,7 @@
     <!-- #docregion i18n -->
     <script>
       // Get the locale id somehow
-      document.locale = 'fr';
+      document.locale = 'es';
 
       // Map to the text plugin
       System.config({
diff --git a/public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf b/public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf
new file mode 100644
index 0000000000..df053ed9cf
--- /dev/null
+++ b/public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+  <file source-language="en" datatype="plaintext" original="ng2.template">
+    <body>
+      <trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
+        <source>Hello i18n!</source>
+        <target>¡Hola i18n!</target>
+        <note priority="1" from="description">An introduction header for this sample</note>
+        <note priority="1" from="meaning">User welcome</note>
+      </trans-unit>
+      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">
+        <source>I don&apos;t output any element</source>
+        <target>No genero ningún elemento</target>
+      </trans-unit>
+      <trans-unit id="df3cf8b55cb528cf8c00167e0b119bfb828538b5" datatype="html">
+        <source>
+I don&apos;t output any element either
+</source>
+        <target>Yo tampoco genero ningún elemento</target>
+        <note priority="1" from="description">optional description</note>
+        <note priority="1" from="meaning">optional meaning</note>
+      </trans-unit>
+      <trans-unit id="35ab5d6121ecbe0decdda638571a5a55ac77d5c4" datatype="html">
+        <source>Angular 2 logo</source>
+        <target>Logo de Angular 2</target>
+      </trans-unit>
+      <trans-unit id="6e22e74e8cbd3095560cfe08993c4fdfa3c50eb0" datatype="html">
+        <source/>
+        <target>{wolves, plural, =0 {ningún lobo} =1 {un lobo} =2 {dos lobos} other {una horda de lobos}}</target>
+      </trans-unit>
+      <trans-unit id="61cafedb85466ab789b3ae817bba1a545468ee1c" datatype="html">
+        <source>The hero is <x id="ICU"/></source>
+        <target>El heroe es <x id="ICU"/></target>
+      </trans-unit>
+      <trans-unit id="14c7055d67771a3b7b6888d282ac092896be06b6" datatype="html">
+        <source/>
+        <target>{gender, select, m {hombre} f {mujer}}</target>
+      </trans-unit>
+    </body>
+  </file>
+</xliff>
diff --git a/public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf.html b/public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf.html
new file mode 100644
index 0000000000..b0584d7f2e
--- /dev/null
+++ b/public/docs/_examples/cb-i18n/ts/locale/messages.es.xlf.html
@@ -0,0 +1,54 @@
+<!-- The `messages.es.xlf` after translation for documentation purposes -->
+<!-- #docregion -->
+<?xml version="1.0" encoding="UTF-8" ?>
+<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+  <file source-language="en" datatype="plaintext" original="ng2.template">
+    <body>
+      <!-- #docregion translated-hello -->
+      <trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
+        <source>Hello i18n!</source>
+        <target>¡Hola i18n!</target>
+        <note priority="1" from="description">An introduction header for this sample</note>
+        <note priority="1" from="meaning">User welcome</note>
+      </trans-unit>
+      <!-- #enddocregion translated-hello -->
+      <!-- #docregion translated-other-nodes -->
+      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">
+        <source>I don&apos;t output any element</source>
+        <target>No genero ningún elemento</target>
+      </trans-unit>
+      <trans-unit id="df3cf8b55cb528cf8c00167e0b119bfb828538b5" datatype="html">
+        <source>I don&apos;t output any element either</source>
+        <target>Yo tampoco genero ningún elemento</target>
+        <note priority="1" from="description">optional description</note>
+        <note priority="1" from="meaning">optional meaning</note>
+      </trans-unit>
+      <trans-unit id="35ab5d6121ecbe0decdda638571a5a55ac77d5c4" datatype="html">
+        <source>Angular 2 logo</source>
+        <target>Logo de Angular 2</target>
+      </trans-unit>
+      <!-- #enddocregion translated-other-nodes -->
+      <!-- #docregion translated-plural -->
+      <trans-unit id="6e22e74e8cbd3095560cfe08993c4fdfa3c50eb0" datatype="html">
+        <source/>
+        <target>{wolves, plural, =0 {ningún lobo} =1 {un lobo} =2 {dos lobos} other {una horda de lobos}}</target>
+      </trans-unit>
+      <!-- #enddocregion translated-plural -->
+      <!-- #docregion translated-select -->
+      <!-- #docregion translate-select-1 -->
+      <trans-unit id="61cafedb85466ab789b3ae817bba1a545468ee1c" datatype="html">
+        <source>The hero is <x id="ICU"/></source>
+        <target>El heroe es <x id="ICU"/></target>
+      </trans-unit>
+      <!-- #enddocregion translate-select-1 -->
+      <!-- #docregion translate-select-2 -->
+      <trans-unit id="14c7055d67771a3b7b6888d282ac092896be06b6" datatype="html">
+        <source/>
+        <target>{gender, select, m {hombre} f {mujer}}</target>
+      </trans-unit>
+      <!-- #enddocregion translate-select-2 -->
+      <!-- #enddocregion translated-select -->
+    </body>
+  </file>
+</xliff>
+
diff --git a/public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf b/public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf
deleted file mode 100644
index 005b98ba73..0000000000
--- a/public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf
+++ /dev/null
@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
- <file source-language="en" datatype="plaintext" original="ng2.template">
-   <body>
-     <trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
-       <source>Hello i18n!</source>
-       <target>Bonjour i18n!</target>
-       <note priority="1" from="description">An introduction header for this sample</note>
-       <note priority="1" from="meaning">User welcome</note>
-     </trans-unit>
-   </body>
- </file>
-</xliff>
diff --git a/public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf.html b/public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf.html
deleted file mode 100644
index 2130c25275..0000000000
--- a/public/docs/_examples/cb-i18n/ts/locale/messages.fr.xlf.html
+++ /dev/null
@@ -1,17 +0,0 @@
-<!-- The `messages.fr.xlf` after translation for documentation purposes -->
-<!-- #docregion -->
-<?xml version="1.0" encoding="UTF-8" ?>
-<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
- <file source-language="en" datatype="plaintext" original="ng2.template">
-   <body>
-     <!-- #docregion  trans-unit -->
-     <trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
-       <source>Hello i18n!</source>
-       <target>Bonjour i18n!</target>
-       <note priority="1" from="description">An introduction header for this sample</note>
-       <note priority="1" from="meaning">User welcome</note>
-     </trans-unit>
-     <!-- #enddocregion  trans-unit -->
-   </body>
- </file>
-</xliff>
diff --git a/public/docs/_examples/cb-i18n/ts/locale/trans-unit.html b/public/docs/_examples/cb-i18n/ts/locale/trans-unit.html
deleted file mode 100644
index 6cb66ca12d..0000000000
--- a/public/docs/_examples/cb-i18n/ts/locale/trans-unit.html
+++ /dev/null
@@ -1,7 +0,0 @@
-<!-- #docregion -->
-<trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
-  <source>Hello i18n!</source>
-  <target/>
-  <note priority="1" from="description">An introduction header for this sample</note>
-  <note priority="1" from="meaning">User welcome</note>
-</trans-unit>
diff --git a/public/docs/_examples/cb-i18n/ts/messages.xlf b/public/docs/_examples/cb-i18n/ts/messages.xlf
new file mode 100644
index 0000000000..be48f69e2b
--- /dev/null
+++ b/public/docs/_examples/cb-i18n/ts/messages.xlf
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+  <file source-language="en" datatype="plaintext" original="ng2.template">
+    <body>
+      <trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
+        <source>Hello i18n!</source>
+        <target/>
+        <note priority="1" from="description">An introduction header for this sample</note>
+        <note priority="1" from="meaning">User welcome</note>
+      </trans-unit>
+      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">
+        <source>I don&apos;t output any element</source>
+        <target/>
+      </trans-unit>
+      <trans-unit id="df3cf8b55cb528cf8c00167e0b119bfb828538b5" datatype="html">
+        <source>
+I don&apos;t output any element either
+</source>
+        <target/>
+        <note priority="1" from="description">optional description</note>
+        <note priority="1" from="meaning">optional meaning</note>
+      </trans-unit>
+      <trans-unit id="35ab5d6121ecbe0decdda638571a5a55ac77d5c4" datatype="html">
+        <source>Angular 2 logo</source>
+        <target/>
+      </trans-unit>
+      <trans-unit id="6e22e74e8cbd3095560cfe08993c4fdfa3c50eb0" datatype="html">
+        <source/>
+        <target/>
+      </trans-unit>
+      <trans-unit id="61cafedb85466ab789b3ae817bba1a545468ee1c" datatype="html">
+        <source>The hero is <x id="ICU"/></source>
+        <target/>
+      </trans-unit>
+      <trans-unit id="14c7055d67771a3b7b6888d282ac092896be06b6" datatype="html">
+        <source/>
+        <target/>
+      </trans-unit>
+    </body>
+  </file>
+</xliff>
diff --git a/public/docs/_examples/cb-i18n/ts/plnkr.json b/public/docs/_examples/cb-i18n/ts/plnkr.json
index e7074f222d..db48ff5c51 100644
--- a/public/docs/_examples/cb-i18n/ts/plnkr.json
+++ b/public/docs/_examples/cb-i18n/ts/plnkr.json
@@ -4,8 +4,8 @@
     "app/**/*.css",
     "app/**/*.html",
     "app/**/*.ts",
-    "locale/messages.xlf",
-    "locale/messages.fr.xlf",
+    "messages.xlf",
+    "locale/messages.*.xlf",
 
     "!**/*.[1].*",
 
diff --git a/public/docs/ts/latest/cookbook/i18n.jade b/public/docs/ts/latest/cookbook/i18n.jade
index 33175c0801..d0a16541e5 100644
--- a/public/docs/ts/latest/cookbook/i18n.jade
+++ b/public/docs/ts/latest/cookbook/i18n.jade
@@ -1,21 +1,26 @@
 include ../_util-fns
 
+a#top
 :marked
   Angular's _internationalization_ ("_i18n_") tools help make your app available in multiple languages.
   
-  <a id="top"></a>
   ## Table of contents
-    
+
     * [Angular and i18n template translation](#angular-i18n)
     * [Mark text with the _i18n_ attribute](#i18n-attribute)
-    * [Create a translation source file with the _ng-xi18n_ tool](#ng-xi18n)
+    * [Add _i18n-..._ translation attributes](#translate-attributes)
+    * [Handle singular and plural](#cardinality)
+    * [Select among alternative texts](#select)
+    * [Use the **_ng-xi18n_ extraction tool** to create a translation source file](#ng-xi18n)
     * [Translate](#translate)
     * [Merge the completed translation file into the app](#merge)
       * [JiT configuration](#jit)
       * [AoT configuration](#aot)
+    * [Translation file maintenance and _id_ changes](#maintenance)
 
 :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" title="i18n Example in Spanish">live example</live-example> 
+  of a JiT-compiled app, translated into Spanish.
 
   
 a#angular-i18n
@@ -67,7 +72,7 @@ a#i18n-attribute
     It will be removed by the compiler _after_ translation.
 
 :marked
-  In the accompanying sample, an `<h1>` tag displays a simple English language greeting which you will translate to French:
+  In the accompanying sample, an `<h1>` tag displays a simple English language greeting which you will translate to Spanish:
 +makeExample('cb-i18n/ts/app/app.component.1.html', 'greeting', 'app/app.component.html')(format=".")
 :marked
   Add the `i18n` attribute to the tag to mark it for translation.
@@ -75,29 +80,132 @@ a#i18n-attribute
 +makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute', 'app/app.component.html')(format=".")
 
 :marked
+  ### Help the translator with a _description_ and _intent_
+
   The translator may need a description of the message to translate it accurately.
   Assign a description to the i18n attribute:
   
 +makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-desc', 'app/app.component.html')(format=".")
 
 :marked
-  The true _meaning_ of the text may require some application context.
-  Add a contextual meaning to the assigned string, separating it from the description with the `|` character:
+  The translator may need to know your _intent_ &mdash; 
+  the true _meaning_ of the text within _this particular_ application context &mdash; 
+  in order to deliver a correct translation.
+  Add some contextual meaning to the assigned string, in front of the description,
+  separating it from the description with the `|` character (`<meaning>|<description>`):
   
 +makeExample('cb-i18n/ts/app/app.component.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".")
 
 :marked
-  While all appearance of a message with the _same_ meaning should have the _same_ translation, 
+  While all appearances of a message with the _same_ meaning have the _same_ translation, 
   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.
+  You could wrap it in a `<span>` but for some reason (CSS comes to mind)
+  you don't want to create a new DOM element merely to facilitate translation.
+  
+  Here are two techniques to try.
+
+  (1) Wrap the text in an `<ng-container>` element. The `<ng-container>` is never renderered:
+
++makeExample('cb-i18n/ts/app/app.component.html', 'i18n-ng-container', 'app/app.component.html')(format=".")
+
+:marked
+  (2) Wrap the text in a pair of HTML comments:
+
++makeExample('cb-i18n/ts/app/app.component.html', 'i18n-with-comment', 'app/app.component.html')(format=".")
+
+.l-main-section
+a#translate-attributes
+:marked
+  ## Add _i18n-..._ translation attributes
+  You've added an image to your template. You care about accessibility too so you add a `title` tag:
+
++makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-title', 'app/app.component.html')(format=".")
+
+:marked
+  The `title` attribute needs to be translated. 
+  Angular i18n support has more translation attributes in the form,`i18n-x`, where `x` is the
+  name of the attribute to translate. 
+  
+  To translate the `title` on the `img` tag from the previous example, write:
+
++makeExample('cb-i18n/ts/app/app.component.html', 'i18n-title-translate', 'app/app.component.html')(format=".")
+
+:marked
+  You can also assign a meaning and a description with the `i18n-x="<meaning>|<description>"` syntax.
+
+.l-main-section
+a#cardinality
+:marked
+  ## Handle singular and plural
+  
+  Different languages have different pluralization rules.
+  
+  Suppose your application says something about a collection of wolves. 
+  In English, depending upon the number of wolves, you could display "no wolves", "one wolf", "two wolves", or "a wolf pack".
+  Other languages might express the _cardinality_ differently. 
+  
+  Here's how you could markup the component template to display the phrase appropriate to the number of wolves:
+
++makeExample('cb-i18n/ts/app/app.component.html', 'i18n-plural', 'app/app.component.html')(format=".")
+
+:marked
+  * The first parameter is the key. It will be bound to the component property (`wolves`) that determines the number of wolves.
+  * The second parameter indentifies this as a `plural` translation type.
+  * The third parameter defines a pluralization pattern consisting of pluralization categories and their matching values.
+
+  Pluralization categories include:
+  * =0
+  * =1
+  * =5
+  * few
+  * other
+
+  Put the default _English_ translation in braces (`{}`) next to the pluralization category.
+  * When you're talking about one wolf, you could write `=1 {one wolf}`.
+  * For zero wolves, you could write `=0 {no wolves}`.
+  * For two wolves, you could write `=2 {two wolves}`. 
+
+  You could keep this up for three, four, and every other number of wolves.
+  Or you could specify the **`other`** category as a catch-all for any unmatched cardinality
+  and write something like: `other {a wolf pack}`.
+
+.l-sub-section
+  :marked
+    This syntax conforms to the
+    <a href="http://userguide.icu-project.org/formatparse/messages" target="_blank" title="ICU Message Format">ICU Message Format</a>
+    which derives from the 
+    <a href="http://cldr.unicode.org/" target="_blank" title="CLDR">Common Locale Data Repository (CLDR)</a>
+    which specifies the
+    <a href="http://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules" target="_blank" title="Pluralization Rules">pluralization rules</a>.
+
+a#select
+:marked
+  ## Select
+  The application displays different text depending upon whether the hero is male or female.
+  These text alternatives require translation too.
+
+  You can handle this with a `select` translation. 
+  A `select` also follows the
+  <a href="http://userguide.icu-project.org/formatparse/messages" target="_blank" title="ICU Message Format">ICU message syntax</a>. 
+  You choose among alternative translation based on a string value instead of a number.
+
+  The following format message in the component template binds to the component's `gender` property which outputs either an 'm' or an 'f'.
+  The message maps those values to the appropriate translation:
+
++makeExample('cb-i18n/ts/app/app.component.html', 'i18n-select', 'app/app.component.html')(format=".")
+
 a#ng-xi18n
 .l-main-section
 :marked
   ## Create a translation source file with the _ng-xi18n_ tool
   
-  Use the `ng-xi18n` extraction tool to extract the `i18n`-marked texts 
+  Use the **_ng-xi18n_ extraction tool** to extract the `i18n`-marked texts 
   into a translation source file in an industry standard format.
   
   This is an Angular CLI tool in the `@angular/compiler-cli` npm package.
@@ -112,48 +220,68 @@ code-example(language="sh" class="code-shell").
 code-example(language="sh" class="code-shell").
   ./node_modules/.bin/ng-xi18n
 
+.l-sub-section
+  :marked
+    Windows users may have to quote the command: like this `"./node_modules/.bin/ng-xi18n"`
+
 :marked
   By default the tool generates a translation file named **`messages.xlf`** in the
   <a href="https://en.wikipedia.org/wiki/XLIFF" target="_blank">XML Localisation Interchange File Format (XLIFF, version 1.2)</a>.
 
-code-example(language="sh" class="code-shell").
-  ./node_modules/.bin/ng-xi18n  --i18nFormat=xmb
-
-.l-sub-section
-  :marked
-    Windows users may have to quote the command:
-  code-example(language="sh").
-    "./node_modules/.bin/ng-xi18n"
-  :marked
-    Consider adding a convenience shortcut to the `scripts` section of the `package.json`
-    to make the command easier to remember and run:
-  code-example(format='.').
-    "scripts": {
-      "i18n": "ng-xi18n", 
-      ...
-    }
-  :marked
-    Now you can enter:
-  code-example(language="sh" class="code-shell").
-    npm run i18n
-
+a#other-formats
 :marked
   ### Other translation formats
 
   You can generate a file named **`messages.xmb`** in the 
   <a href="http://cldr.unicode.org/development/development-process/design-proposals/xmb"  target="_blank">XML Message Bundle (XMB)</a> format
-  by adding the `--i18nFormat=xmb` switch.
+  by adding the `--i18nFormat=xmb` flag.
 
+code-example(language="sh" class="code-shell").
+  ./node_modules/.bin/ng-xi18n  --i18nFormat=xmb
+
+:marked
   This sample sticks with the _XLIFF_ format.
 
+a#ng-xi18n-options
+:marked
+  ### Other options
+  You may have to specify additional options. 
+  For example, if the `tsconfig.json` TypeScript configuration file is located other than in the root folder,
+  you must identify the path to it with the `-p` option:
+code-example(language="sh" class="code-shell").
+  ./node_modules/.bin/ng-xi18n -p path/to/tsconfig.json
+  ./node_modules/.bin/ng-xi18n  --i18nFormat=xmb -p path/to/tsconfig.json
+
+
+a#npm-i18n-script
+:marked
+  ### Add an _npm_ script for convenience
+  
+  Consider adding a convenience shortcut to the `scripts` section of the `package.json`
+  to make the command easier to remember and run:
+code-example(format='.' language='sh' ).
+  "scripts": {
+    "i18n": "ng-xi18n", 
+    ...
+  }
+:marked
+  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
+  npm run i18n -- --i18nFormat=xmb -p path/to/tsconfig.json
+:marked
+  Note the `--` flag before the options. 
+  It tells _npm_ that every flag thereafter should be passed through to `ng-xi18n`.
+
 a#translate
 .l-main-section
 :marked
-  ## Translate _le message textuel_
+  ## Translate _los mensajes de texto_
   
   The `ng-xi18n` command generated a translation source file in the project root folder named `messages.xlf`.
   The next step is to translate the English language template text into the specific language translation
-  files. The cookbook sample creates a French translation file.
+  files. The cookbook sample creates a Spanish translation file.
 
 a#localization-folder
 :marked
@@ -169,39 +297,88 @@ a#localization-folder
     Localization and internationalization are 
     <a href="https://en.wikipedia.org/wiki/Internationalization_and_localization" target="_blank">different but closely related terms</a>.
 :marked
-  This sample follows that suggestion. It has `locale` folder immediately under the project root.
+  This sample follows that suggestion. It has a `locale` folder under the project root.
   Assets within the folder carry a filename extension that matches a language-culture code from a
   <a href="https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx" target="_blank">well-known codeset</a>.
 
-  Move `messages.xlf` into the `locale` folder where it will become the source for all language-specific translations.
-  Then make a copy for the French language named `messages.fr.xlf` .
+  Make a copy of the `messages.xlf` file in the `locale` folder and 
+  rename it `messages.es.xlf`for the Spanish language translation.
+  Do the same for each target language.
 
-  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
-  using one of the 
+  ### Translate text nodes
+  In the real world, you send the `messages.es.xlf` file to a Spanish translator who fills in the translations
+  using one of the
   <a href="https://en.wikipedia.org/wiki/XLIFF#Editors" target="_blank">many XLIFF file editors</a>.
 
-  This sample file is easy to translate without a special editor or knowledge of French.
-  Open `messages.fr.xlf` and find the `<trans-unit>` section:
+  This sample file is easy to translate without a special editor or knowledge of Spanish.
+  Open `messages.es.xlf` and find the first `<trans-unit>` section:
 
-+makeExample('cb-i18n/ts/locale/trans-unit.html', '', 'locale/messages.fr.xlf (<trans-unit>)')(format=".")
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-hello', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
 :marked
   This XML element represents the translation of the `<h1>` greeting tag you marked with the `i18n` attribute. 
   
   Using the _source_, _description_, and _meaning_ elements to guide your translation,
-  replace the `<target/>` tag with the French greeting:
-+makeExample('cb-i18n/ts/locale/messages.fr.xlf.html', 'trans-unit', 'locale/messages.fr.xlf (<trans-unit>, after translation)')(format=".")
-: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.
-.alert.is-helpful
+  replace the `<target/>` tag with the Spanish greeting:
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-hello', 'locale/messages.es.xlf (<trans-unit>, after translation)')(format=".")
+
+.alert.is-important
   :marked
-    Repeat the extraction process whenever you add new app messages or edit existing ones.
-    Be careful not to lose the previous translations.
-    Specialized software can help manage the change process.
+    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.
+    See the **[translation file maintenance discussion](#maintenance)** below.
+
+:marked
+  Translate the other text nodes the same way:
+
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-other-nodes', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
+
+a#translate-plural-select
+:marked
+  ## Translate _plural_ and _select_
+  Translating _plural_ and _select_ messages is a little tricky.
+
+  The `<source>` tag is empty for `plural` and `select` translation units which makes them hard to correlate with the original template.
+  The ICU rules are not yet supported in the `XLIFF` format; they soon will be.
+  The ICU rules _are_ supported in the `XMB` format.  
+
+  You'll just have to look for them in relation to other translation units that you recognize from elsewhere in the source template.
+  In this example, you know the translation unit for the `select` must be just below the translation unit for the logo.
+
+:marked
+  ### Translate _plural_ 
+  To translate a `plural`, translate its ICU format match values:
+
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-plural', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
+
+:marked
+  ### Translate _select_ 
+  The `select` behaves a little differently. Here again is the ICU format message in the component template:
+
++makeExample('cb-i18n/ts/app/app.component.html', 'i18n-select', 'app/app.component.html')(format=".")
+
+:marked
+  The extraction tool broke that into _two_ translation units.
+  
+  The first unit contains the text that was _outside_ the `select`.
+  In place of the `select` is a placeholder, `<x id="ICU">`, that represents the `select` message. 
+  Translate the text and leave the placeholder where it is.
+
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translate-select-1', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
+
+:marked
+  The second translation unit, immediately below the first one, contains the `select` message. Translate that.
+
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translate-select-2', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
+
+:marked
+  Here they are together, after translation:
+
++makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-select', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
+
+.l-main-content
+:marked
+  The entire template translation is complete. It's time to incorporate that translation in the application.
 
 #app-pre-translation
 :marked
@@ -214,13 +391,13 @@ a#localization-folder
   cb-i18n/ts/app/app.component.ts,
   cb-i18n/ts/app/app.module.ts,
   cb-i18n/ts/app/main.1.ts,
-  cb-i18n/ts/locale/messages.fr.xlf.html
+  cb-i18n/ts/locale/messages.es.xlf.html
 `, '', `
   app/app.component.html,
   app/app.component.ts,
   app/app.module.ts,
   app/main.ts,
-  locale/messages.fr.xlf
+  locale/messages.es.xlf
 `)
 
 a#merge
@@ -237,7 +414,7 @@ a#merge
     * the translation file
     * the translation file format 
     * the   <a href="https://en.wikipedia.org/wiki/XLIFF" target="_blank">_Locale ID_</a>
-    (`fr` or `en-US` for instance)
+    (`es` or `en-US` for instance)
   
   _How_ you provide this information depends upon whether you compile with
   the JiT (_Just-in-Time_) compiler or the AoT (_Ahead-of-Time_) compiler. 
@@ -320,7 +497,7 @@ a#text-plugin
   Notice that it waits for the `getTranslationProviders` promise to resolve before
   bootstrapping the app.
 
-  The app is now _internationalized_ for English and French and there is a clear path for adding
+  The app is now _internationalized_ for English and Spanish and there is a clear path for adding
   more languages.
 
 a#aot
@@ -352,12 +529,27 @@ a#aot
     * `--locale`: the name of the locale
     * `--i18nFormat`: the format of the localization file
   
-  For this sample, the French language command would be
+  For this sample, the Spanish language command would be
 code-example(language="sh" class="code-shell").
-  ./node_modules/.bin/ngc --i18nFile=./locale/messages.fr.xlf --locale=fr --i18nFormat=xlf
+  ./node_modules/.bin/ngc --i18nFile=./locale/messages.es.xlf --locale=es --i18nFormat=xlf
 
 .l-sub-section
   :marked
     Windows users may have to quote the command:
   code-example(language="sh" class="code-shell").
-    "./node_modules/.bin/ngc" --i18nFile=./locale/messages.fr.xlf --locale=fr --i18nFormat=xlf
+    "./node_modules/.bin/ngc" --i18nFile=./locale/messages.es.xlf --locale=es --i18nFormat=xlf
+
+a#maintenance
+:marked
+  ## Translation file maintenance and _id_ changes
+    
+  As the application evolves, you will change the _i18n_ markup and re-run the `ng-xi18n` extraction tool many times.
+  The _new_ markup that you add is not a problem. 
+  But _most_ changes to _existing_ markup will trigger generation of _new_ `id`s for the affected translation units.
+  
+  After an `id` changes, the translation files are no longer in-sync.
+  **All translated versions of the application will fail** during re-compilation. 
+  The error messages identify the old `id`s that are no longer valid but they don't tell you what the new `id`s should be.
+  
+  **Commit all translation message files to source control**, especially the English source `messages.xlf`.
+  The difference between the old and the new `messages.xlf` file will help you find and update `id` changes across your translation files.
diff --git a/public/docs/ts/latest/guide/change-log.jade b/public/docs/ts/latest/guide/change-log.jade
index 2c25cf8572..7756f83af7 100644
--- a/public/docs/ts/latest/guide/change-log.jade
+++ b/public/docs/ts/latest/guide/change-log.jade
@@ -5,6 +5,11 @@ block includes
   The Angular documentation is a living document with continuous improvements.
   This log calls attention to recent significant changes.
 
+  ## Internationalization: pluralization and _select_ (2016-11-30)
+  The [Internationalization (i18n)](i18n.html) guide explains how to handle pluralization and
+  translation of alternative texts with `select`.
+  The sample demonstrates these features too.
+
   ## Testing: karma file updates (2016-11-30)
   * karma.config + karma-test-shim can handle multiple spec source paths;
   see quickstart issue: [angular/quickstart#294](https://github.com/angular/quickstart/issues/294)