Fixed #13317 - Clarified documentation about how the blocktrans and trans template tags work with regard to variables. Thanks for the initial patch, Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13184 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jannis Leidel 2010-05-09 13:55:15 +00:00
parent 49bd7f0959
commit c796fc7e36
2 changed files with 60 additions and 13 deletions

View File

@ -2071,3 +2071,12 @@ django.contrib.webdesign
A collection of template tags that can be useful while designing a website, A collection of template tags that can be useful while designing a website,
such as a generator of Lorem Ipsum text. See :ref:`ref-contrib-webdesign`. such as a generator of Lorem Ipsum text. See :ref:`ref-contrib-webdesign`.
i18n
~~~~
Provides a couple of templatetags that allow specifying translatable text in
Django templates. It is slightly different from the libraries described
above because you don't need to add any application to the ``INSTALLED_APPS``
setting but rather set :setting:`USE_I18N` to True, then loading it with
``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`.

View File

@ -325,6 +325,8 @@ 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 input is a proper string, then add support for lazy translation objects at the
end. end.
.. _specifying-translation-strings-in-template-code:
Specifying translation strings: In template code Specifying translation strings: In template code
================================================ ================================================
@ -334,6 +336,9 @@ Translations in :ref:`Django templates <topics-templates>` uses two template
tags and a slightly different syntax than in Python code. To give your template tags and a slightly different syntax than in Python code. To give your template
access to these tags, put ``{% load i18n %}`` toward the top of your template. access to these tags, put ``{% load i18n %}`` toward the top of your template.
``trans`` template tag
----------------------
The ``{% trans %}`` template tag translates either a constant string The ``{% trans %}`` template tag translates either a constant string
(enclosed in single or double quotes) or variable content:: (enclosed in single or double quotes) or variable content::
@ -348,15 +353,30 @@ require translation in the future::
Internally, inline translations use an ``ugettext`` call. Internally, inline translations use an ``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
string in the message catalogs.
It's not possible to mix a template variable inside a string within ``{% trans It's not possible to mix a template variable inside a string within ``{% trans
%}``. If your translations require strings with variables (placeholders), use %}``. If your translations require strings with variables (placeholders), use
``{% blocktrans %}``:: ``{% blocktrans %}`` instead.
``blocktrans`` template tag
---------------------------
Contrarily to the ``trans`` tag, the ``blocktrans`` tag allows you to mark
complex sentences consisting of literals and variable content for translation
by making use of placeholders::
{% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %} {% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
To translate a template expression -- say, using template filters -- you need To translate a template expression -- say, accessing object attributes or
to bind the expression to a local variable for use within the translation using template filters -- you need to bind the expression to a local variable
block:: for use within the translation block. Examples::
{% blocktrans with article.price as amount %}
That will cost $ {{ amount }}.
{% endblocktrans %}
{% blocktrans with value|filter as myvar %} {% blocktrans with value|filter as myvar %}
This will have {{ myvar }} inside. This will have {{ myvar }} inside.
@ -369,9 +389,17 @@ separate the pieces with ``and``::
This is {{ book_t }} by {{ author_t }} This is {{ book_t }} by {{ author_t }}
{% endblocktrans %} {% endblocktrans %}
To pluralize, specify both the singular and plural forms with the This tag is also in charge of handling another functionality: Pluralization.
``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and To make use of it you should:
``{% endblocktrans %}``. Example::
* Designate and bind a counter value by using ``count``, such value will
be the one used to select the right plural form.
* Specify both the singular and plural forms separating them with the
``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
``{% endblocktrans %}``.
An example::
{% blocktrans count list|length as counter %} {% blocktrans count list|length as counter %}
There is only one {{ name }} object. There is only one {{ name }} object.
@ -379,14 +407,25 @@ To pluralize, specify both the singular and plural forms with the
There are {{ counter }} {{ name }} objects. There are {{ counter }} {{ name }} objects.
{% endblocktrans %} {% endblocktrans %}
When you use the pluralization feature and bind additional values to local A more complex example::
variables apart from the counter value that selects the translated literal to be
used, have in mind that the ``blocktrans`` construct is internally converted {% blocktrans with article.price as amount count i.length as years %}
to an ``ungettext`` call. This means the same :ref:`notes regarding ungettext That will cost $ {{ amount }} per year.
variables <pluralization-var-notes>` apply. {% plural %}
That will cost $ {{ amount }} per {{ years }} years.
{% endblocktrans %}
When you both use the pluralization feature and bind values to local variables
in addition to the counter value, have in mind that the ``blocktrans``
construct is internally converted to an ``ungettext`` call. This means the
same :ref:`notes regarding ungettext variables <pluralization-var-notes>`
apply.
.. _template-translation-vars: .. _template-translation-vars:
Other tags
----------
Each ``RequestContext`` has access to three translation-specific variables: Each ``RequestContext`` has access to three translation-specific variables:
* ``LANGUAGES`` is a list of tuples in which the first element is the * ``LANGUAGES`` is a list of tuples in which the first element is the
@ -400,7 +439,6 @@ Each ``RequestContext`` has access to three translation-specific variables:
right-to-left language, e.g.: Hebrew, Arabic. If False it's a right-to-left language, e.g.: Hebrew, Arabic. If False it's a
left-to-right language, e.g.: English, French, German etc. left-to-right language, e.g.: English, French, German etc.
If you don't use the ``RequestContext`` extension, you can get those values with If you don't use the ``RequestContext`` extension, you can get those values with
three tags:: three tags::