[1.3.X] Added a few cross references to the i18n docs and documented pgettext and colleagues.

    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``

=====================

    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

    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.

Internationalization

====================

.. module:: django.utils.translation

Overview

========

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

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.

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::

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

    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

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.

    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')

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

    ...

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.

Localized names of languages

============================

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.

.. function:: get_language_info

.. versionadded:: 1.3

Localized names of languages

============================

The ``get_language_info()`` function provides detailed information about

languages::

    <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

.. 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::