From b8f7e7c476ed332bd1d27b881e169c78e8db2e4e Mon Sep 17 00:00:00 2001
From: maxime-allex <ma.allex@gmail.com>
Date: Wed, 7 Dec 2016 11:49:52 +0100
Subject: [PATCH] docs(compiler): add doc + examples for i18n explicit ID
 option

---
 .../cb-i18n/ts/app/app.component.1.html         | 12 ++++++++++++
 public/docs/ts/latest/cookbook/i18n.jade        | 17 +++++++++++++++++
 2 files changed, 29 insertions(+)

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 cc19182338..ae0901a409 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
@@ -10,6 +10,18 @@ <h1 i18n>Hello i18n!</h1>
 <h1 i18n="An introduction header for this sample">Hello i18n!</h1>
 <!--#enddocregion i18n-attribute-desc-->
 
+<!--#docregion i18n-attribute-id-->
+<h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1>
+<!--#enddocregion i18n-attribute-id-->
+
+<!--#docregion i18n-attribute-meaning-and-id-->
+<h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1>
+<!--#enddocregion i18n-attribute-meaning-and-id-->
+
+<!--#docregion i18n-attribute-solo-id-->
+<h1 i18n="@@introductionHeader">Hello i18n!</h1>
+<!--#enddocregion i18n-attribute-solo-id-->
+
 <!--#docregion i18n-title-->
 <img [src]="logo" title="Angular 2 logo">
 <!--#enddocregion i18n-title-->
diff --git a/public/docs/ts/latest/cookbook/i18n.jade b/public/docs/ts/latest/cookbook/i18n.jade
index d0a16541e5..18b5858787 100644
--- a/public/docs/ts/latest/cookbook/i18n.jade
+++ b/public/docs/ts/latest/cookbook/i18n.jade
@@ -96,6 +96,23 @@ a#i18n-attribute
   
 +makeExample('cb-i18n/ts/app/app.component.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".")
 
+:marked
+  ### Strengthen translation messages consistancy with an explicit _id_
+
+  By default the angular _i18n_ extractor tool generates a unique ID for each `i18n` attributes in templates.
+  If you fix a typo in a translatable block of your template, the extractor tool will generate another new _id_ for your translation.
+  To avoid this behavior, you can specify an explicit _id_ in the `i18n` attribute that will be used by the extractor tool and compiler.
+  To specify an _id_, just prefix it with `@@` in the i18n attribute:
+
++makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-id', 'app/app.component.html')(format=".")
+:marked
+  With a _meaning_ and a _description_ :
+
++makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-meaning-and-id', 'app/app.component.html')(format=".")
+:marked
+  Moreover, you can just specify an _id_ in the `i18n` attribute :
++makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-solo-id', 'app/app.component.html')(format=".")
+
 :marked
   While all appearances of a message with the _same_ meaning have the _same_ translation, 
   a message with *different meanings* could have different translations.