Plurals and Genders

pkg/intl/lib/intl.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * This library provides internationalization and localization. This includes
  * message formatting and replacement, date and number formatting and parsing,
  * and utilities for working with Bidirectional text.
  *
  * ## Installing ##
@@ skipping 53 matching lines @@
  *          name: 'today',
  *          args: [date],
  *          desc: 'Indicate the current date',
  *          examples: {'date' : 'June 8, 2012'});
  *      print(today(new DateTime.now());
  *
  *      msg(num_people, place) => Intl.message(
  *           '''I see ${Intl.plural(num_people,
  *             {'0': 'no one at all',
  *              '1': 'one other person',
- *              'other': '$num_people other people'})} in $place.'''',
+ *              'other': '$num_people other people'})} in $place.''',
  *          name: 'msg',
  *          args: [num_people, place],
  *          desc: 'Description of how many people are seen as program start.',
  *          examples: {'num_people': 3, 'place': 'London'});
  *
  * Calling `msg(2, 'Athens');` would
  * produce "I see 2 other people in Athens." as output in the default locale.
  *
  * To use a locale other than the default, use the `withLocale` function.
  *       var todayString = new DateFormat("pt_BR").format(new DateTime.now());
@@ skipping 146 matching lines @@
     if (aLocale == null) return systemLocale;
     if (aLocale == "C") return "en_ISO";
     if ((aLocale.length < 5) || (aLocale.length > 6)) return aLocale;
     if (aLocale[2] != '-' && (aLocale[2] != '_')) return aLocale;
     var lastRegionLetter = aLocale.length == 5 ? "" : aLocale[5].toUpperCase();
     return '${aLocale[0]}${aLocale[1]}_${aLocale[3].toUpperCase()}'
            '${aLocale[4].toUpperCase()}$lastRegionLetter';
   }
 
   /**
-   * Support method for message formatting. Select the correct plural form from
-   * [cases] given [howMany].
+   * Format a message differently depending on [howMany]. Normally used
+   * as part of an Intl.message message that is to be translated.

[Emily Fortuna, 2013/07/03 17:52:33]

`Intl.message` 
also you probably can do without the second "message" in that sentence....

[Alan Knight, 2013/07/03 18:41:07]

Done. Changed second "message" to "text"

+   * Selects the correct plural form from
+   * the provided alternatives. The [other] named argument is mandatory.
    */
-  static String plural(var howMany, Map cases, [num offset=0]) {
-    // TODO(efortuna): Deal with "few" and "many" cases, offset, and others!
-    return select(howMany.toString(), cases);
+  static String plural(int howMany, {zero, one, two, few, many, other}) {
+    if (other == null) {
+      throw new ArgumentError("The 'other' named argument must be provided");

[Emily Fortuna, 2013/07/03 17:52:33]

in which case should we make it a positional required argument?

[Alan Knight, 2013/07/03 18:41:07]

That would mean you'd have to write it first, which seems awkward. Also, since
these names correspond to the known ICU names, it seems nice to have them all be
there and named consistently to match. In different locales, different other
forms will also be mandatory, so we can't use this as a way to be sure all the
required forms are provided.

+    }
+    // TODO(alanknight): This algorithm needs to be locale-dependent.

[Emily Fortuna, 2013/07/03 17:52:33]

how will we be able to change this behavior based on locale?

[Alan Knight, 2013/07/03 18:41:07]

I was thinking that there would be a generated implementation included with the
generated message libraries for each locale, and that this would either delegate
to that, or possibly that the translated messages would directly call the
version specific to their locale. e.g. the translation might be 
   Intl.message("${localPlural(...)}");
rather than
   Intl.message("${Intl.plural(...)}");
where localPlural is defined in each generated library.

+    switch (howMany) {
+      case 0 : return (zero == null) ? other : zero;
+      case 1 : return (one == null) ? other : one;
+      case 2: return (two == null) ? ((few == null) ? other : few) : two;
+      default:
+        if (howMany == 3 || howMany == 4 && few != null) return few;
+        if (howMany > 10 && howMany < 100 && many != null) return many;
+        return other;
+    }
+    throw new ArgumentError("Invalid plural usage for $howMany");
   }
 
   /**
+   * Format a message differently depending on [gender]. Normally used as part
+   * of an Intl.message message that is to be translated.
+   */
+  static String gender(String gender,
+      {String male, String female, String other}) {
+    if (other == null) {
+      throw new ArgumentError("The 'other' named argument must be specified");
+    }
+    switch(gender) {
+      case "female" : return female == null ? other : female;
+      case "male" : return male == null ? other : male;
+      default: return other;
+    }
+  }
+
+  /**
    * Format the given function with a specific [locale], given a
    * [message_function] that takes no parameters. The [message_function] can be
    * a simple message function that just returns the result of `Intl.message()`
    * it can be a wrapper around a message function that takes arguments, or it
    * can be something more complex that manipulates multiple message
    * functions.
    *
    * In either case, the purpose of this is to delay calling [message_function]
    * until the proper locale has been set. This returns the result of calling
    * [message_function], which could be of an arbitrary type.
    */
   static withLocale(String locale, Function message_function) {
     // We have to do this silliness because Locale is not known at compile time,
     // but must be a static variable in order to be visible to the Intl.message
     // invocation.
     var oldLocale = getCurrentLocale();
     _defaultLocale = locale;
     var result = message_function();
     _defaultLocale = oldLocale;
     return result;
   }
 
   /**
    * Support method for message formatting. Select the correct exact (gender,
    * usually) form from [cases] given the user [choice].
    */
   static String select(String choice, Map cases) {
-    if (cases.containsKey(choice)) {
-      return cases[choice];
-    } else if (cases.containsKey('other')){
-      return cases['other'];
-    } else {
-      return '';
-    }
+    var exact = cases[choice];
+    if (exact != null) return exact;
+    var other = cases["other"];
+    return (other == null) ? '' : other;
   }
 
   /**
    * Accessor for the current locale. This should always == the default locale,
    * unless for some reason this gets called inside a message that resets the
    * locale.
    */
   static String getCurrentLocale() {
     if (_defaultLocale == null) _defaultLocale = systemLocale;
     return _defaultLocale;
   }
 
   toString() => "Intl($locale)";
 }