[1.1.X] Fixed #13317 - Clarified documentation about how the blocktra…

…ns and trans template tags work with regard to variables. Thanks for the initial patch, Ramiro Morales.

Backport from trunk, r13184.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@13185 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/ref/templates/builtins.txt

@@ -1848,3 +1848,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`.

docs/topics/i18n/internationalization.txt

@@ -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,21 +389,42 @@ 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.
     {% plural %}
     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:
 
@@ -398,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::