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,
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
end.
.. _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
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
(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.
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
%}``. 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 %}
To translate a template expression -- say, using template filters -- you need
to bind the expression to a local variable for use within the translation
block::
To translate a template expression -- say, accessing object attributes or
using template filters -- you need to bind the expression to a local variable
for use within the translation block. Examples::
{% blocktrans with article.price as amount %}
That will cost $ {{ amount }}.
{% endblocktrans %}
{% blocktrans with value|filter as myvar %}
This will have {{ myvar }} inside.
@ -369,9 +389,17 @@ separate the pieces with ``and``::
This is {{ book_t }} by {{ author_t }}
{% endblocktrans %}
To pluralize, specify both the singular and plural forms with the
``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
``{% endblocktrans %}``. Example::
This tag is also in charge of handling another functionality: Pluralization.
To make use of it you should:
* 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 %}
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.
{% endblocktrans %}
When you use the pluralization feature and bind additional values to local
variables apart from the counter value that selects the translated literal to be
used, 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.
A more complex example::
{% blocktrans with article.price as amount count i.length as years %}
That will cost $ {{ amount }} per year.
{% 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:
Other tags
----------
Each ``RequestContext`` has access to three translation-specific variables:
* ``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
left-to-right language, e.g.: English, French, German etc.
If you don't use the ``RequestContext`` extension, you can get those values with
three tags::