From 2da03fedcdebd9499d13eadf1500f80d04f4d796 Mon Sep 17 00:00:00 2001
From: Matthew Wilkes <git@matthewwilkes.name>
Date: Tue, 10 Dec 2013 20:36:34 +0000
Subject: Expand on docstring

---
 pyramid/i18n.py | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)

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:
-- 
cgit v1.2.3