Added a few cross references to the i18n docs and documented pgettext and colleagues.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16403 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/ref/utils.txt

@@ -315,6 +315,48 @@ Atom1Feed
 
     Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
 
+``django.utils.functional``
+===========================
+
+.. module:: django.utils.functional
+    :synopsis: Functional programming tools.
+
+.. function:: allow_lazy(func, *resultclasses)
+
+    Django offers many utility functions (particularly in ``django.utils``) that
+    take a string as their first argument and do something to that string. These
+    functions are used by template filters as well as directly in other code.
+
+    If you write your own similar functions and deal with translations, you'll
+    face the problem of what to do when the first argument is a lazy translation
+    object. You don't want to convert it to a string immediately, because you might
+    be using this function outside of a view (and hence the current thread's locale
+    setting will not be correct).
+
+    For cases like this, use the ``django.utils.functional.allow_lazy()``
+    decorator. It modifies the function so that *if* it's called with a lazy
+    translation as the first argument, the function evaluation is delayed until it
+    needs to be converted to a string.
+
+    For example::
+
+        from django.utils.functional import allow_lazy
+
+        def fancy_utility_function(s, ...):
+            # Do some conversion on string 's'
+            ...
+        fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
+
+    The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
+    a number of extra arguments (``*args``) specifying the type(s) that the
+    original function can return. Usually, it's enough to include ``unicode`` here
+    and ensure that your function returns only Unicode strings.
+
+    Using this decorator means you can write your function and assume that the
+    input is a proper string, then add support for lazy translation objects at the
+    end.
+
+
 ``django.utils.http``
 =====================
 
@@ -428,14 +470,23 @@ For a complete discussion on the usage of the following see the
 
     Translates ``message`` and returns it in a unicode string
 
+.. function:: pgettext(context, message)
+
+    Translates ``message`` given the ``context`` and returns
+    it in a unicode string.
+
+    For more information, see :ref:`contextual-markers`.
+
 .. function:: gettext_lazy(message)
 .. function:: ugettext_lazy(message)
+.. function:: pgettext_lazy(context, message)
 
     Same as the non-lazy versions above, but using lazy execution.
 
     See :ref:`lazy translations documentation <lazy-translations>`.
 
 .. function:: gettext_noop(message)
+.. function:: ugettext_noop(message)
 
     Marks strings for translation but doesn't translate them now. This can be
     used to store strings in global variables that should stay in the base
@@ -452,8 +503,14 @@ For a complete discussion on the usage of the following see the
     Translates ``singular`` and ``plural`` and returns the appropriate string
     based on ``number`` in a unicode string.
 
+.. function:: npgettext(context, singular, plural, number)
+
+    Translates ``singular`` and ``plural`` and returns the appropriate string
+    based on ``number`` and the ``context`` in a unicode string.
+
 .. function:: ngettext_lazy(singular, plural, number)
 .. function:: ungettext_lazy(singular, plural, number)
+.. function:: npgettext_lazy(singular, plural, number)
 
     Same as the non-lazy versions above, but using lazy execution.
 

docs/topics/i18n/internationalization.txt

@@ -2,6 +2,8 @@
 Internationalization
 ====================
 
+.. module:: django.utils.translation
+
 Overview
 ========
 
@@ -24,19 +26,22 @@ Specifying translation strings: In Python code
 Standard translation
 --------------------
 
-Specify a translation string by using the function ``ugettext()``. It's
+Specify a translation string by using the function
-convention to import this as a shorter alias, ``_``, to save typing.
+:func:`~django.utils.translation.ugettext`. It's convention to import this
+as a shorter alias, ``_``, to save typing.
 
 .. note::
     Python's standard library ``gettext`` module installs ``_()`` into the
     global namespace, as an alias for ``gettext()``. In Django, we have chosen
     not to follow this practice, for a couple of reasons:
 
-      1. For international character set (Unicode) support, ``ugettext()`` is
+      1. For international character set (Unicode) support,
-         more useful than ``gettext()``. Sometimes, you should be using
+         :func:`~django.utils.translation.ugettext` is more useful than
-         ``ugettext_lazy()`` as the default translation method for a particular
+         ``gettext()``. Sometimes, you should be using
-         file. Without ``_()`` in the global namespace, the developer has to
+         :func:`~django.utils.translation.ugettext_lazy` as the default
-         think about which is the most appropriate translation function.
+         translation method for a particular file. Without ``_()`` in the
+         global namespace, the developer has to think about which is the
+         most appropriate translation function.
 
       2. The underscore character (``_``) is used to represent "the previous
          result" in Python's interactive shell and doctest tests. Installing a
@@ -127,20 +132,20 @@ displayed by most translation tools.
 Marking strings as no-op
 ------------------------
 
-Use the function ``django.utils.translation.ugettext_noop()`` to mark a string
+Use the function :func:`django.utils.translation.ugettext_noop()` to mark a
-as a translation string without translating it. The string is later translated
+string as a translation string without translating it. The string is later
-from a variable.
+translated from a variable.
 
 Use this if you have constant strings that should be stored in the source
-language because they are exchanged over systems or users -- such as strings in
+language because they are exchanged over systems or users -- such as strings
-a database -- but should be translated at the last possible point in time, such
+in a database -- but should be translated at the last possible point in time,
-as when the string is presented to the user.
+such as when the string is presented to the user.
 
 Pluralization
 -------------
 
-Use the function ``django.utils.translation.ungettext()`` to specify pluralized
+Use the function :func:`django.utils.translation.ungettext()` to specify
-messages.
+pluralized messages.
 
 ``ungettext`` takes three arguments: the singular translation string, the plural
 translation string and the number of objects.
@@ -155,14 +160,18 @@ of its value.)
 For example::
 
     from django.utils.translation import ungettext
+
     def hello_world(request, count):
-        page = ungettext('there is %(count)d object', 'there are %(count)d objects', count) % {
+        page = ungettext(
+            'there is %(count)d object',
+            'there are %(count)d objects',
+        count) % {
             'count': count,
         }
         return HttpResponse(page)
 
-In this example the number of objects is passed to the translation languages as
+In this example the number of objects is passed to the translation
-the ``count`` variable.
+languages as the ``count`` variable.
 
 Lets see a slightly more complex usage example::
 
@@ -226,8 +235,8 @@ Contextual markers
 Sometimes words have several meanings, such as ``"May"`` in English, which
 refers to a month name and to a verb. To enable translators to translate
 these words correctly in different contexts, you can use the
-``django.utils.translation.pgettext()`` function, or the
+:func:`django.utils.translation.pgettext()` function, or the
-``django.utils.translation.npgettext()`` function if the string needs
+:func:`django.utils.translation.npgettext()` function if the string needs
 pluralization. Both take a context string as the first variable.
 
 In the resulting .po file, the string will then appear as often as there are
@@ -241,6 +250,14 @@ For example::
 
     month = pgettext("month name", "May")
 
+or::
+
+    from django.utils.translation import pgettext_lazy
+
+    class MyThing(models.Model):
+        name = models.CharField(help_text=pgettext_lazy(
+            'help text for MyThing model', 'This is the help text'))
+
 will appear in the .po file as:
 
 .. code-block:: po
@@ -254,7 +271,7 @@ will appear in the .po file as:
 Lazy translation
 ----------------
 
-Use the function ``django.utils.translation.ugettext_lazy()`` to translate
+Use the function :func:`django.utils.translation.ugettext_lazy()` to translate
 strings lazily -- when the value is accessed rather than when the
 ``ugettext_lazy()`` function is called.
 
@@ -308,6 +325,7 @@ name::
 
     class MyThing(models.Model):
         name = models.CharField(_('name'), help_text=_('This is the help text'))
+
         class Meta:
             verbose_name = _('my thing')
             verbose_name_plural = _('mythings')
@@ -360,9 +378,9 @@ Joining strings: string_concat()
 
 Standard Python string joins (``''.join([...])``) will not work on lists
 containing lazy translation objects. Instead, you can use
-``django.utils.translation.string_concat()``, which creates a lazy object that
+:func:`django.utils.translation.string_concat()`, which creates a lazy object
-concatenates its contents *and* converts them to strings only when the result
+that concatenates its contents *and* converts them to strings only when the
-is included in a string. For example::
+result is included in a string. For example::
 
     from django.utils.translation import string_concat
     ...
@@ -374,46 +392,11 @@ In this case, the lazy translations in ``result`` will only be converted to
 strings when ``result`` itself is used in a string (usually at template
 rendering time).
 
-The allow_lazy() decorator
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Django offers many utility functions (particularly in ``django.utils``) that
-take a string as their first argument and do something to that string. These
-functions are used by template filters as well as directly in other code.
-
-If you write your own similar functions and deal with translations, you'll
-face the problem of what to do when the first argument is a lazy translation
-object. You don't want to convert it to a string immediately, because you might
-be using this function outside of a view (and hence the current thread's locale
-setting will not be correct).
-
-For cases like this, use the ``django.utils.functional.allow_lazy()``
-decorator. It modifies the function so that *if* it's called with a lazy
-translation as the first argument, the function evaluation is delayed until it
-needs to be converted to a string.
-
-For example::
-
-    from django.utils.functional import allow_lazy
-
-    def fancy_utility_function(s, ...):
-        # Do some conversion on string 's'
-        ...
-    fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
-
-The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
-a number of extra arguments (``*args``) specifying the type(s) that the
-original function can return. Usually, it's enough to include ``unicode`` here
-and ensure that your function returns only Unicode strings.
-
-Using this decorator means you can write your function and assume that the
-input is a proper string, then add support for lazy translation objects at the
-end.
-
-
 Localized names of languages
 ============================
 
+.. function:: get_language_info
+
 .. versionadded:: 1.3
 
 The ``get_language_info()`` function provides detailed information about
@@ -457,7 +440,8 @@ require translation in the future::
 
     <title>{% trans "myvar" noop %}</title>
 
-Internally, inline translations use an ``ugettext`` call.
+Internally, inline translations use an
+:func:`~django.utils.translation.ugettext` call.
 
 In case a template var (``myvar`` above) is passed to the tag, the tag will
 first resolve such variable to a string at run-time and then look up that
@@ -778,7 +762,7 @@ The ``set_language`` redirect view
 
 .. function:: set_language(request)
 
-As a convenience, Django comes with a view, :meth:`django.views.i18n.set_language`,
+As a convenience, Django comes with a view, :func:`django.views.i18n.set_language`,
 that sets a user's language preference and redirects back to the previous page.
 
 Activate this view by adding the following line to your URLconf::