Merge pull request #1206 from MatthewWilkes/master

Update pluralize docs now lingua1.7 is out

2 files changed, 25 insertions, 14 deletions

diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index c9b782c08..5f50ca212 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -607,10 +607,8 @@ object, but the domain and mapping information attached is ignored.
    def aview(request):
        localizer = request.localizer
        num = 1
-       translated = localizer.pluralize(
-                          _('item_plural', default="${number} items"), 
-                          None, num, 'mydomain', mapping={'number':num}
-                          )
+       translated = localizer.pluralize('item_plural', '${number} items',
+           num, 'mydomain', mapping={'number':num})
 
 The corresponding message catalog must have language plural definitions and
 plural alternatives set.
diff --git a/pyramid/i18n.py b/pyramid/i18n.py
index 6ffd93e8f..aaba769c6 100644
--- a/pyramid/i18n.py
+++ b/pyramid/i18n.py
@@ -75,16 +75,16 @@ class Localizer(object):
         :term:`message identifier` objects as a singular/plural pair
         and an ``n`` value representing the number that appears in the
         message using gettext plural forms support.  The ``singular``
-        and ``plural`` objects passed may be translation strings or
-        unicode strings.  ``n`` represents the number of elements.
-        ``domain`` is the translation domain to use to do the
-        pluralization, and ``mapping`` is the interpolation mapping
-        that should be used on the result.  Note that if the objects
-        passed are translation strings, their domains and mappings are
-        ignored.  The domain and mapping arguments must be used
-        instead.  If the ``domain`` is not supplied, a default domain
-        is used (usually ``messages``).
-
+        and ``plural`` objects should be unicode strings. There is no
+        reason to use translation string objects as arguments as all
+        metadata is ignored.
+        
+        ``n`` represents the number of elements. ``domain`` is the
+        translation domain to use to do the pluralization, and ``mapping``
+        is the interpolation mapping that should be used on the result. If
+        the ``domain`` is not supplied, a default domain is used (usually
+        ``messages``).
+        
         Example::
 
            num = 1
@@ -93,6 +93,19 @@ class Localizer(object):
                                             num,
                                             mapping={'num':num})
 
+        If using the gettext plural support, which is required for
+        languages that have pluralisation rules other than n != 1, the
+        ``singular`` argument must be the message_id defined in the
+        translation file. The plural argument is not used in this case.
+
+        Example::
+
+           num = 1
+           translated = localizer.pluralize('item_plural',
+                                            '',
+                                            num,
+                                            mapping={'num':num})
+
         
         """
         if self.pluralizer is None: