From 62bb4b8c37ada04c10d2a37990326636ea7791d6 Mon Sep 17 00:00:00 2001
From: Jannis Leidel <jannis@leidel.info>
Date: Wed, 15 Jun 2011 10:48:13 +0000
Subject: [PATCH] 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 | 57 +++++++++++
docs/topics/i18n/internationalization.txt | 110 +++++++++-------------
2 files changed, 104 insertions(+), 63 deletions(-)
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 2b06548aa2..3d70c2989b 100644
--- a/docs/ref/utils.txt
+++ b/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.
diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt
index d4c436e39a..ccc47cb260 100644
--- a/docs/topics/i18n/internationalization.txt
+++ b/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
-convention to import this as a shorter alias, ``_``, to save typing.
+Specify a translation string by using the function
+: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
- more useful than ``gettext()``. Sometimes, you should be using
- ``ugettext_lazy()`` as the default translation method for a particular
- file. Without ``_()`` in the global namespace, the developer has to
- think about which is the most appropriate translation function.
+ 1. For international character set (Unicode) support,
+ :func:`~django.utils.translation.ugettext` is more useful than
+ ``gettext()``. Sometimes, you should be using
+ :func:`~django.utils.translation.ugettext_lazy` as the default
+ 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
-as a translation string without translating it. The string is later translated
-from a variable.
+Use the function :func:`django.utils.translation.ugettext_noop()` to mark a
+string as a translation string without translating it. The string is later
+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
-a database -- but should be translated at the last possible point in time, such
-as when the string is presented to the user.
+language because they are exchanged over systems or users -- such as strings
+in a database -- but should be translated at the last possible point in time,
+such as when the string is presented to the user.
Pluralization
-------------
-Use the function ``django.utils.translation.ungettext()`` to specify pluralized
-messages.
+Use the function :func:`django.utils.translation.ungettext()` to specify
+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
-the ``count`` variable.
+In this example the number of objects is passed to the translation
+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
-``django.utils.translation.npgettext()`` function if the string needs
+:func:`django.utils.translation.pgettext()` function, or the
+: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
-concatenates its contents *and* converts them to strings only when the result
-is included in a string. For example::
+:func:`django.utils.translation.string_concat()`, which creates a lazy object
+that concatenates its contents *and* converts them to strings only when the
+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::