docs(i18n): expand the MessageFormat syntax documentation

Author: chirayuk

docs/content/guide/i18n.ngdoc

@@ -18,8 +18,10 @@ application means providing translations and localized formats for the abstracte
 Angular supports i18n/l10n for {@link ng.filter:date date}, {@link ng.filter:number number} and
 {@link ng.filter:currency currency} filters.
 
-Additionally, Angular supports localizable pluralization support through the {@link
-ng.directive:ngPluralize `ngPluralize` directive}.
+Localizable pluralization is supported via the {@link ng.directive:ngPluralize `ngPluralize`
+directive}.  Additionally, you can use <a href="#MessageFormat">MessageFormat extensions</a> to
+`$interpolate` for localizable pluralization and gender support in all interpolations via the
+`ngMessageFormat` module.
 
 All localizable Angular components depend on locale-specific rule sets managed by the {@link
 ng.$locale `$locale` service}.
@@ -142,96 +144,200 @@ displaying the date with a timezone specified by the developer.
 <a name="MessageFormat"></a>
 ## MessageFormat extensions 
 
-AngularJS interpolations via `$interpolate` and in templates
-support an extended syntax based on a subset of the ICU
-MessageFormat that covers plurals and gender selections.
+You can write localizable plural and gender based messages in Angular interpolation expressions and
+`$interpolate` calls.
+
+This syntax extension is provided by way of the `ngMessageFormat` module that your application can
+depend upon (shipped separately as `angular-messageFormat.min.js` and `angular-messageFormat.js`.)
+A current limitation of the `ngMessageFormat` module, is that it does not support redefining the
+`$interpolate` start and end symbols. Only the default `{{` and `}}` are allowed.
+
+The syntax extension is based on a subset of the ICU MessageFormat syntax that covers plurals and
+gender selections.  Please refer to the links in the “Further Reading” section at the bottom of this
+section.
+
+You may find it helpful to play with our [Plnkr Example](http://plnkr.co/edit/QBVRQ70dvKZDWmHW9RyR?p=preview)
+as you read the examples below.
+
+### Plural Syntax
+
+The syntax for plural based message selection looks like this following:
+
+```text
+{{NUMERIC_EXPRESSION, plural,
+    =0 {MESSAGE_WHEN_VALUE_IS_0}
+    =1 {MESSAGE_WHEN_VALUE_IS_1}
+    =2 {MESSAGE_WHEN_VALUE_IS_2}
+    =3 {MESSAGE_WHEN_VALUE_IS_3}
+    ...
+    zero {MESSAGE_WHEN_PLURAL_CATEGORY_IS_ZERO}
+    one {MESSAGE_WHEN_PLURAL_CATEGORY_IS_ONE}
+    two {MESSAGE_WHEN_PLURAL_CATEGORY_IS_TWO}
+    few {MESSAGE_WHEN_PLURAL_CATEGORY_IS_FEW}
+    many {MESSAGE_WHEN_PLURAL_CATEGORY_IS_MANY}
+    other {MESSAGE_WHEN_THERE_IS_NO_MATCH}
+}}
+```
 
-Please refer to our [design doc](https://docs.google.com/a/google.com/document/d/1pbtW2yvtmFBikfRrJd8VAsabiFkKezmYZ_PbgdjQOVU/edit)
-for a lot more details.  You may find it helpful to play with our [Plnkr Example](http://plnkr.co/edit/QBVRQ70dvKZDWmHW9RyR?p=preview).
+Please note that whitespace (including newline) is generally insignificant except as part of the
+actual message text that occurs in curly braces.  Whitespace is generally used to aid readability.
+
+Here, `NUMERIC_EXPRESSION` is an expression that evaluates to a numeric value based on which the
+displayed message should change based on pluralization rules.
+
+Following the Angular expression, you would denote the plural extension syntax by the `, plural,`
+syntax element.  The spaces there are optional.
+
+This is followed by a list of selection keyword and corresponding message pairs.  The "other"
+keyword and corresponding message are **required** but you may have as few or as many of the other
+categories as you need.
+
+#### Selection Keywords
+
+The selection keywords can be either exact matches or language dependant [plural
+categories](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html).
+
+Exact matches are written as the equal sign followed by the exact value. `=0`, `=1`, `=2` and
+`=123` are all examples of exact matches.  Note that there should be no space between the equal sign
+and the numeric value.
+
+Plural category matches are single words corresponding to the [plural
+categories](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html) of
+the CLDR plural category spec.  These categories vary by locale.  The "en" (English) locale, for
+example, defines just "one" and "other" while the "ga" (Irish) locale defines "one", "two", "few",
+"many" and "other".  Typically, you would just write the categories for your language.  During
+translation, the translators will add or remove more categories depending on the target locale.
+
+Exact matches always win over keyword matches.  Therefore, if you define both `=0` and `zero`, when
+the value of the expression is zero, the `=0` message is the one that will be selected.  (The
+duplicate keyword categories are helpful when used with the optional `offset` syntax described
+later.)
 
-You can read more about the ICU MessageFormat syntax at
-[Formatting Messages | ICU User Guide](http://userguide.icu-project.org/formatparse/messages#TOC-MessageFormat).
 
-This extended syntax is provided by way of the
-`ngMessageFormat` module that your application can depend
-upon (shipped separately as `angular-messageFormat.min.js` and
-`angular-messageFormat.js`.)  A current limitation of the
-`ngMessageFormat` module, is that it does not support
-redefining the `$interpolate` start and end symbols. Only the
-default `{{` and `}}` are allowed.
-
-This syntax extension, while based on MessageFormat, has
-been designed to be backwards compatible with existing
-AngularJS interpolation expressions.  The key rule is simply
-this: **All interpolations are done inside double curlies.**
-The top level comma operator after an expression inside the
-double curlies causes MessageFormat extensions to be
-recognized.  Such a top level comma is otherwise illegal in
-an Angular expression and is used by MessageFormat to
-specify the function (such as plural/select) and it's
-related syntax.
-
-To understand the extension, take a look at the ICU
-MessageFormat syntax as specified by the ICU documentation.
-Anywhere in that MessageFormat that you have regular message
-text and you want to substitute an expression, just put it
-in double curlies instead of single curlies that
-MessageFormat dictates.  This has a huge advantage.  **You
-are no longer limited to simple identifiers for
-substitutions**.  Because you are using double curlies, you
-can stick in any arbitrary interpolation syntax there,
-including nesting more MessageFormat expressions!  Some
-examples will make this clear.  In the following example, I
-will only be showing you the AngularJS syntax.
+#### Messages
 
+Messages immediately follow a selection keyword and are optionally preceded by whitespace.  They are
+written in single curly braces (`{}`).  They may contain Angular interpolation syntax inside them.
+In addition, the `#` symbol is a placeholder for the actual numeric value of the expression.
 
 ### Simple plural example
 
-```
+```text
 {{numMessages, plural,
-      =0 { You have no new messages }
-      =1 { You have one new message }
-   other { You have # new messages }
+      =0 {You have no new messages}
+      =1 {You have one new message}
+   other {You have # new messages}
 }}
 ```
 
-While I won't be teaching you MessageFormat here, you will
-note that the `#` symbol works as expected.  You could have
-also written it as:
+Because these messages can themselves contain Angular expressions, you could also write this as
+follows:
 
-```
+```text
 {{numMessages, plural,
-      =0 { You have no new messages }
-      =1 { You have one new message }
-   other { You have {{numMessages}} new messages }
+      =0 {You have no new messages}
+      =1 {You have one new message}
+   other {You have {{numMessages}} new messages}
 }}
 ```
 
-where you explicitly typed in `numMessages` for "other"
-instead of using `#`.  They are nearly the same except if
-you're using "offset".  Refer to the ICU MessageFormat
-documentation to learn about offset.
 
-Please note that **other** is a **required** category (for
-both the plural syntax and the select syntax that is shown
-later.)
+### Plural syntax with optional `offset`
+
+The plural syntax supports an optional `offset` syntax that is used in matching.  It's simpler to
+explain this with an example.
+
+```text
+{{recipients.length, plural, offset:1
+    =0    {You gave no gifts}
+    =1    {You gave {{recipients[0].name}} a gift}
+    one   {You gave {{recipients[0].name}} and one other person a gift}
+    other {You gave {{recipients[0].name}} and # other people a gift}
+}}
+```
+
+When an `offset` is specified, the matching works as follows.  First, the exact value of the Angular
+expression is matched against the exact matches (i.e. `=N` selectors) to find a match.  If there is
+one, that message is used.  If there was no match, then the offset value is subtracted from the
+value of the expression and locale specific pluralization rules are applied to this new value to
+obtain its plural category (such as “one”, “few”, “many”, etc.) and a match is attempted against the
+keyword selectors and the matching message is used.  If there was no match, then the “other”
+category (required) is used.  The value of the `#` character inside a message is the value of
+original expression reduced by the offset value that was specified.
+
+### Escaping / Quoting
+
+You might need to quote the curly braces or the `#` character inside the message texts so that they
+are treated literally with no special meaning.  To support such cases, you may escape any character
+by preceding it with a `\` (backslash) character.  The backslash character removes any special
+meaning to the character that immediately follows it.  Therefore, you can escape or quote the
+backslash itself by preceding it with another backslash character.
 
 
-### Simple select (for gender) example
+### Gender (aka select) Syntax
 
+The gender support is provided by the more generic "select" syntax that is more akin to a switch
+statement.  It is general enough to support use for gender based messages.
+
+The syntax for gender based message selection looks like this following:
+
+```text
+{{EXPRESSION, select,
+    male {MESSAGE_WHEN_EXPRESSION_IS_MALE}
+    female {MESSAGE_WHEN_EXPRESSION_IS_FEMALE}
+    ...
+    other {MESSAGE_WHEN_THERE_IS_NO_GENDER_MATCH}
+}}
 ```
+
+Please note that whitespace (including newline) is generally insignificant except as part of the
+actual message text that occurs in curly braces.  Whitespace is generally used to aid readability.
+
+Here, `EXPRESSION` is an Angular expression that evaluates to the gender of the person that
+is used to select the message that should be displayed.
+
+The Angular expression is followed by `, select,` where the spaces are optional.
+
+This is followed by a list of selection keyword and corresponding message pairs.  The "other"
+keyword and corresponding message are **required** but you may have as few or as many of the other
+gender values as you need (i.e. it isn't restricted to male/female.)  Note however, that the
+matching is **case-sensitive**.
+
+#### Selection Keywords
+
+Selection keywords are simple words like "male" and "female".  The keyword, "other", and it's
+corresponding message are required while others are optional.  It is used when the Angular
+expression does not match (case-insensitively) any of the other keywords specified.
+
+#### Messages
+
+Messages immediately follow a selection keyword and are optionally preceded by whitespace.  They are
+written in single curly braces (`{}`).  They may contain Angular interpolation syntax inside them.
+
+### Simple gender example
+
+```text
 {{friendGender, select,
        male { Invite him }
      female { Invite her }
       other { Invite them }
 }}
 ```
 
-### More complex example that combines some of these
+### Nesting
+
+As mentioned in the syntax for plural and select, the embedded messages can contain Angular
+interpolation syntax.  Since you can use MessageFormat extensions in Angular interpolation, this
+allows you to nest plural and gender expressions in any order.
+
+Please note that if these are intended to reach a translator and be translated, it is recommended
+that the messages appear as a while and not be split up.
+
+### More complex example that demonstrates nesting
 
 This is taken from the [plunker example](http://plnkr.co/edit/QBVRQ70dvKZDWmHW9RyR?p=preview) linked to earlier.
 
-```
+```text
 {{recipients.length, plural, offset:1
     =0 {You ({{sender.name}}) gave no gifts}
     =1 { {{ recipients[0].gender, select,
@@ -249,3 +355,27 @@ This is taken from the [plunker example](http://plnkr.co/edit/QBVRQ70dvKZDWmHW9R
     other {You ({{sender.name}}) gave {{recipients.length}} people gifts. }
 }}
 ```
+
+### Differences from the ICU MessageFormat syntax
+
+This section is useful to you if you're already familiar with the ICU MessageFormat syntax.
+
+This syntax extension, while based on MessageFormat, has been designed to be backwards compatible
+with existing AngularJS interpolation expressions.  The key rule is simply this: **All
+interpolations are done inside double curlies.** The top level comma operator after an expression
+inside the double curlies causes MessageFormat extensions to be recognized.  Such a top level comma
+is otherwise illegal in an Angular expression and is used by MessageFormat to specify the function
+(such as plural/select) and it's related syntax.
+
+To understand the extension, take a look at the ICU MessageFormat syntax as specified by the ICU
+documentation.  Anywhere in that MessageFormat that you have regular message text and you want to
+substitute an expression, just put it in double curlies instead of single curlies that MessageFormat
+dictates.  This has a huge advantage.  **You are no longer limited to simple identifiers for
+substitutions**.  Because you are using double curlies, you can stick in any arbitrary interpolation
+syntax there, including nesting more MessageFormat expressions!  Some examples will make this clear.
+In the following example, I will only be showing you the AngularJS syntax.
+
+### Further Reading
+For more details, please refer to our [design doc](https://docs.google.com/a/google.com/document/d/1pbtW2yvtmFBikfRrJd8VAsabiFkKezmYZ_PbgdjQOVU/edit)
+for a lot more details.  You can read more about the ICU MessageFormat syntax at
+[Formatting Messages | ICU User Guide](http://userguide.icu-project.org/formatparse/messages#TOC-MessageFormat).