Localization-Proposal.md

@@ -89,22 +89,49 @@ would also be valid.
 
 Although it would be rare to need more than 9 additional parameters, you can use `%10`, `%11`, etc., to get the 10-th, 11-th, and so on.  If you need a parameter to be followed directly by a number, use `%{1}0` rather than `%10`.
 
-A `%` followed by a non-number (and not matching `%\{\d+\}` as a regular expression) generates just the character following the percent, so `%%` is a literal `%`, and `%:` would generate just `:`.
+A `%` followed by a non-number (and not matching `%\{(\d+|plural:%\d+([+-]\d+|(%\{\d+\}|%.|.)*?)\}` as a regular expression) generates just the character following the percent, so `%%` is a literal `%`, and `%:` would generate just `:`.
 
 
 ### Plural Forms ###
 
-If a message must be represented differently depending on a particular numeric value (say to distinguish between "1 file loaded" and "2 files loaded"), replace the message by an array consisting of the numeric value followed by the strings to use when that value is 1, 2, 3, etc., where the last string is used if the numeric value is outside the number of entries given.  For example,
+If a message must be represented differently depending on a particular numeric value (say to distinguish between "1 file loaded" and "2 files loaded"), the word or words that need changing can be encoded using a special escape sequence, as in the following
 
-    MathJax.Message.Set(_("fl",[n,"%1 file loaded","%1 files loaded"],n));
+    MathJax.Message.Set(_("fl","%1 %{plural:%1|file|files} loaded",n));
+
+The `%{plural:%1|file|files}` specifies the value that controls the plural form (here `%1` indicates the first argument after the message string, which is `n` in the example), and the `|` characters separate the variations.  This format allows the message to depend on multiple values, as in
+
+    MathJax.Message.Set(_("fl", "%1 %{plural:%1|file|files} loaded and %2 {plural:%2|image|images} displayed.", n, m));
+
+Note that the translation string may contain such constructs even if the original English one doesn't.  For example
+
+    _("alone","We are %1 in this family but alone in this World.", n)
+
+could be translated into French by
+
+    "Nous sommes %1 dans cette famille mais %{plural:%1|seul|seuls} en ce monde."
+
+Note that if one of the options for the plural forms requires a literal close brace, it can be quoted with a percent:
+
+    %{plural:%1|One {only%}|Two {or more%}}
+
+would produce `One {only}` when the first argument is 1, and `Two {or more}` otherwise.  If a string needs to include a literal string that looks like one of these selectors, the original `%` can be quoted.  So
+`"%%{plural:%%1|A|B}"` would be the literal string `%{plural:%1|A|B}`.
 
-would select `"%1 file loaded"` when `n` is 1, and `"%1 files loaded"` for any other value of `n`.  Then that string is used as the message, with the value of `n` inserted for `%1` (since `n` is passed as the third parameter to `_()`).
+The usual treatment for plurals is that the value after the colon is treated as an index into the array of options separated by vertical bars, and if the index is outside the range of the choices, the last choice is used.  So
+
+    _("om","%{plural:%1|One|Many}",n)
+
+would return `One` if `n` is 1, and `Many` if `n` is anything else (including 0 or negative numbers).
+
+    MathJax.Message.Set(_("fl",[n,"%1 file loaded","%1 files loaded"],n));
 
 If you need a different value for 0, for example, you could use something like
 
-    MathJax.Message.Set(_("fl",[n+1,"No files loaded","%1 file loaded","%1 files loaded"],n));
+    MathJax.Message.Set(_("fl","%{plural:%1+1|No files|%1 file|%1 files} loaded",n));
+
+That is, the specification for the value matches `%(\d+)([+-]\d+)?` as a regular expression, and the sum of the two numbers is used as the index into the array of choices.  The second number acts as a "shift" that determines what the index is for the initial choice (note that it can be negative, as in `%1-3`).
 
-to select the string based on `n+1` rather than `n`.
+Some languages have a more complex means of determining forms.  For instance, Polish has different forms for 1, 2 through 4, 5 through 21, 22 through 24, 25 through 31, and so on  (see the [gnu gettext documentation](http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#Plural-forms) for more examples).  So the plural escape must be more complex for these languages.  One approach would be to allow the language files to provide their own routine that implements the selection of the form.  The routine would be passed the value and the array and would return the proper one.  That way, any special treatment could be done on a language-by-language basis.  Alternatively, there could be data describing the value-to-index transformation needed for the language.
 
 
 ### HTML Snippets ###
@@ -115,16 +142,7 @@ A number of the dialogs used in MathJax are defined using [HTML snippets](http:/
 
 would get the translation for the snippet (that is effectively `Do this <b>now!</b>`) and put it in a `<span>`.
 
-If the snippet depends on a numeric value for its plural form, then you can use an array that consists of a number followed by the various HTML snippets; the snippet corresponding to the given numeric value will be selected (just as it was for strings above).  E.g.,
-
-    MathJax.HTML.Element("span,null,_("fl",[n,
-      ["%1 ",["b",null,"file"]," loaded"],
-      ["%1 ",["b",null,"files"], loaded"]
-    ],n));
-
-would return a DOM element representing `<span>1 <b>file</b> loaded</span>` if `n` is 1, but `<span>3 <b>files</b> loaded</span>` if `n` is 3.
-
-Note that parameter substitution is performed on the strings of the snippet that will become text in the DOM fragment that is generated from the snippet.
+Note that parameter substitution and plural form substitution are performed on the strings of the snippet that will become text in the DOM fragment that is generated from the snippet.
 
 
 ### Specifying a Form ###
@@ -166,6 +184,9 @@ The methods in `MathJax.Localization` include:
 <dt>fontFamily()</dt>
 <dd>Get the font-family needed to display text in the selected language.  Returns <code>null</code> if no special font is required.</dd>
 
+<dt>plural(n,str)</dt>
+<dd>The method that returns the correct plural form for the value <i>n</i> from an array of strings.  This is the <i>n</i>-th string in the array, if there is one, or the last entry if not.  Individual languages can override this function with one that properly handles the requirements for their plural forms.</dd>
+
 </dl>
 
 
@@ -198,6 +219,7 @@ A typical example might be
       meta: {
         translator: "...",                       // other metadata could be added
       },
+      plural: function (n,str) {...},            // optional implementation of plural forms
       domains: {
         hub: {
           version: "1.0",
@@ -238,7 +260,10 @@ The fields have the following meanings:
 <dd>This is a font-family (or list of font-families) that should be used when text in this language is displayed.  If not present, then no special font is needed.</dd>
 
 <dt>meta</dt>
-<dd>This is an object that contains the meta-data about the translation.  Such information can include the name of the translator, the date of the translation, etc.</dd>
+<dd>This is an object that contains the meta-data about the translation.  Such information can include the name of the translator, the date of the translation, etc. [This may not be needed in the data itself, so perhaps this could be in comments instead.]</dd>
+
+<dt>plural</dt>
+<dd>This is an optional function that implements the selection of the plural form given an integer value and an array of plural forms.  If not present, the default plural selector is used (which returns the <i>n</i>-th element of the array if <i>n</i> is within the range of the array, and the last element otherwise).</dd>
 
 <dt>domains</dt>
 <dd>This is an object that contains the translation strings for this language, grouped by domain.  Each domain has an entry, and its value is an object that contains the translation strings for that domain.  The format is described in more detail below.</dd>