Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #13317 - Clarified documentation about how the blocktrans and t…

…rans 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
  • Loading branch information...
commit c796fc7e3630fcbc273d288609ab3cdbeda602a1 1 parent 49bd7f0
Jannis Leidel jezdez authored
9 docs/ref/templates/builtins.txt
View
@@ -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`.
64 docs/topics/i18n/internationalization.txt
View
@@ -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::
Please sign in to comment.
Something went wrong with that request. Please try again.