Ticket #13317: 13317-r13135.diff

docs/ref/templates/builtins.txt

@@ -2061 +2061 @@
 
 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 +325 @@
 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 +336 @@
 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 +353 @@
 
 Internally, inline translations use an ``ugettext`` call.
 
+In the translation of a template var case (``myvar`` above), at run-time the tag
+first resolves such variable to a string and then looks 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, ``blocktrans`` allows to mark as translatable
+complex sentences with mixed literal and variable content at template
+creation-time 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 +389 @@
     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 +407 @@
     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 +438 @@
       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::