Bug 748869 - Document l10n enhancements in 1.7; r=@ochameau

doc/dev-guide-source/tutorials/l10n.md

@@ -96,31 +96,95 @@ hello_string= Bonjour!
 
 ## Plurals ##
 
-The `l10n` module has basic support for plural forms. The following
-`.properties` file includes separate localizations for the singular
-and plural form of "child":
+The `l10n` module supports plural forms. Different languages have
+different rules for the formation of plurals. For example,
+English has two forms: a singular form for "one", and a plural form
+for "everything else, including zero":
 
 <pre>
-child_id[one]= one child
-child_id= %d children
+one tomato
+no tomatoes
+two tomatoes
 </pre>
 
-To use it, list the count of the item after its identifier:
+But Russian has different forms for numbers ending in 1 (except 11),
+numbers ending in 2-4 (except 12-14) and other numbers:
+
+<pre>
+один помидор     // one tomato
+два помидора     // two tomatoes
+пять помидоров   // five tomatoes
+</pre>
+
+The SDK uses the [Unicode CLDR](http://cldr.unicode.org/index) data
+to describe the different plural forms used by different languages.
+
+### Unicode CLDR Plural Forms ###
+
+The Unicode CLDR project defines a scheme for describing a particular
+language's plural rules. In this scheme a language maps each distinct
+range of numbers on to one of up to six forms, identified by the
+following categories: *zero*, *one*, *two*, *few*, *many*, and *other*.
+
+English has two forms, which can be described by mapping "1" to "one"
+and "everything else" to "other":
+
+<pre>
+one   → n is 1;
+other → everything else
+</pre>
+
+Russian uses four forms, that can be described as follows:
+
+<pre>
+one   → n mod 10 is 1 and n mod 100 is not 11;
+few   → n mod 10 in 2..4 and n mod 100 not in 12..14;
+many  → n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14;
+other → everything else
+</pre>
+
+Plural rules for all languages can be found in the CLDR
+[Language Plural Rules](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html)
+page (although this table is out of date compared to the
+[CLDR XML source](http://unicode.org/repos/cldr/trunk/common/supplemental/plurals.xml)).
+
+### Plural Forms in the SDK ###
+
+In the code, you supply an extra parameter alongside the identifier,
+describing how many items there are:
 
     var _ = require("l10n").get;
-    console.log(_("child_id", 1));
-    console.log(_("child_id", 2));
+    console.log(_("tomato_id"));
+    console.log(_("tomato_id", 1));
+    console.log(_("tomato_id", 2));
+    console.log(_("tomato_id", 5));
+    console.log(_("tomato_id", .5));
 
-This will give the following output:
+In the `.properties` file for each language you can define a different
+localization for each plural form possible in that language, using the
+CLDR keywords. So in English we could have two plural localizations
+(note that the "other" category does **not** take the CLDR keyword):
 
 <pre>
-info: one child
-info: 2 children
+# en-US translations
+tomato_id[one]= %d tomato
+tomato_id= %d tomatoes
 </pre>
 
-At the moment `l10n` only distinguishes between two plural forms:
-"one", and "not one". So it doesn't support
-[languages which have different plural rules](https://developer.mozilla.org/en/Localization_and_Plurals).
+In Russian we could have four plural localizations:
+
+<pre>
+# ru-RU translations
+tomato_id[one]= %d помидор
+tomato_id[few]= %d помидора
+tomato_id[many]= %d помидоров
+tomato_id= %d помидоры
+</pre>
+
+The localization module itself understands the CLDR definitions for each
+language, enabling it to map between, for example, "2" in the code and
+"few" in the `ru-RU.properties` file. Then it retrieves and returns
+the localization appropriate for the count you supplied.
 
 ## Placeholders ##
 
@@ -199,6 +263,20 @@ This gives us the following output:
 info: London is Bob's home town.
 </pre>
 
+## Locale Updater ##
+
+The [locale updater](https://github.com/downloads/ochameau/locale-updater/locale-updater.xpi)
+add-on makes it easier to update locale files. Once you've installed it,
+open the Add-on Manager, and you'll see a see a new button labeled
+"Update l10n" next to each add-on you've installed:
+
+<img class="align-center" src="static-files/media/screenshots/locale-updater.png"
+alt="Add-on manager with locale updater installed" />
+
+Click the button and you'll be prompted for a new `.properties` file
+for that add-on. If you provide a new file, the add-on's locale data
+will be updated with the new file.
+
 ## <a name="limitations">Limitations</a> ##
 
 The current localization support is a first step towards full support,
@@ -223,8 +301,3 @@ a command to `cfx` that scans the add-on for localizable strings and
 builds a template `.properties` file listing all the strings that need
 to be translated.
 
-* The algorithm used to find a matching locale is based on the
-[Firefox implementation](http://mxr.mozilla.org/mozilla-central/source/chrome/src/nsChromeRegistryChrome.cpp#93)
-which is known to be sub-optimal for some locales. We're working on
-improving this in
-[bug 711041](https://bugzilla.mozilla.org/show_bug.cgi?id=711041).