Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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 authored May 09, 2010
9  docs/ref/templates/builtins.txt
@@ -2071,3 +2071,12 @@ django.contrib.webdesign
2071 2071
 
2072 2072
 A collection of template tags that can be useful while designing a website,
2073 2073
 such as a generator of Lorem Ipsum text. See :ref:`ref-contrib-webdesign`.
  2074
+
  2075
+i18n
  2076
+~~~~
  2077
+
  2078
+Provides a couple of templatetags that allow specifying translatable text in
  2079
+Django templates. It is slightly different from the libraries described
  2080
+above because you don't need to add any application to the ``INSTALLED_APPS``
  2081
+setting but rather set :setting:`USE_I18N` to True, then loading it with
  2082
+``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`.
64  docs/topics/i18n/internationalization.txt
@@ -325,6 +325,8 @@ Using this decorator means you can write your function and assume that the
325 325
 input is a proper string, then add support for lazy translation objects at the
326 326
 end.
327 327
 
  328
+.. _specifying-translation-strings-in-template-code:
  329
+
328 330
 Specifying translation strings: In template code
329 331
 ================================================
330 332
 
@@ -334,6 +336,9 @@ Translations in :ref:`Django templates <topics-templates>` uses two template
334 336
 tags and a slightly different syntax than in Python code. To give your template
335 337
 access to these tags, put ``{% load i18n %}`` toward the top of your template.
336 338
 
  339
+``trans`` template tag
  340
+----------------------
  341
+
337 342
 The ``{% trans %}`` template tag translates either a constant string
338 343
 (enclosed in single or double quotes) or variable content::
339 344
 
@@ -348,15 +353,30 @@ require translation in the future::
348 353
 
349 354
 Internally, inline translations use an ``ugettext`` call.
350 355
 
  356
+In case a template var (``myvar`` above) is passed to the tag, the tag will
  357
+first resolve such variable to a string at run-time and then look up that
  358
+string in the message catalogs.
  359
+
351 360
 It's not possible to mix a template variable inside a string within ``{% trans
352 361
 %}``. If your translations require strings with variables (placeholders), use
353  
-``{% blocktrans %}``::
  362
+``{% blocktrans %}`` instead.
  363
+
  364
+``blocktrans`` template tag
  365
+---------------------------
  366
+
  367
+Contrarily to the ``trans`` tag, the ``blocktrans`` tag allows you to mark
  368
+complex sentences consisting of literals and variable content for translation
  369
+by making use of placeholders::
354 370
 
355 371
     {% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
356 372
 
357  
-To translate a template expression -- say, using template filters -- you need
358  
-to bind the expression to a local variable for use within the translation
359  
-block::
  373
+To translate a template expression -- say, accessing object attributes or
  374
+using template filters -- you need to bind the expression to a local variable
  375
+for use within the translation block. Examples::
  376
+
  377
+    {% blocktrans with article.price as amount %}
  378
+    That will cost $ {{ amount }}.
  379
+    {% endblocktrans %}
360 380
 
361 381
     {% blocktrans with value|filter as myvar %}
362 382
     This will have {{ myvar }} inside.
@@ -369,9 +389,17 @@ separate the pieces with ``and``::
369 389
     This is {{ book_t }} by {{ author_t }}
370 390
     {% endblocktrans %}
371 391
 
372  
-To pluralize, specify both the singular and plural forms with the
373  
-``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
374  
-``{% endblocktrans %}``. Example::
  392
+This tag is also in charge of handling another functionality: Pluralization.
  393
+To make use of it you should:
  394
+
  395
+    * Designate and bind a counter value by using ``count``, such value will
  396
+      be the one used to select the right plural form.
  397
+
  398
+    * Specify both the singular and plural forms separating them with the
  399
+      ``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
  400
+      ``{% endblocktrans %}``.
  401
+
  402
+An example::
375 403
 
376 404
     {% blocktrans count list|length as counter %}
377 405
     There is only one {{ name }} object.
@@ -379,14 +407,25 @@ To pluralize, specify both the singular and plural forms with the
379 407
     There are {{ counter }} {{ name }} objects.
380 408
     {% endblocktrans %}
381 409
 
382  
-When you use the pluralization feature and bind additional values to local
383  
-variables apart from the counter value that selects the translated literal to be
384  
-used, have in mind that the ``blocktrans`` construct is internally converted
385  
-to an ``ungettext`` call. This means the same :ref:`notes regarding ungettext
386  
-variables <pluralization-var-notes>` apply.
  410
+A more complex example::
  411
+
  412
+    {% blocktrans with article.price as amount count i.length as years %}
  413
+    That will cost $ {{ amount }} per year.
  414
+    {% plural %}
  415
+    That will cost $ {{ amount }} per {{ years }} years.
  416
+    {% endblocktrans %}
  417
+
  418
+When you both use the pluralization feature and bind values to local variables
  419
+in addition to the counter value, have in mind that the ``blocktrans``
  420
+construct is internally converted to an ``ungettext`` call. This means the
  421
+same :ref:`notes regarding ungettext variables <pluralization-var-notes>`
  422
+apply.
387 423
 
388 424
 .. _template-translation-vars:
389 425
 
  426
+Other tags
  427
+----------
  428
+
390 429
 Each ``RequestContext`` has access to three translation-specific variables:
391 430
 
392 431
     * ``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:
400 439
       right-to-left language, e.g.: Hebrew, Arabic. If False it's a
401 440
       left-to-right language, e.g.: English, French, German etc.
402 441
 
403  
-
404 442
 If you don't use the ``RequestContext`` extension, you can get those values with
405 443
 three tags::
406 444
 

0 notes on commit c796fc7

Please sign in to comment.
Something went wrong with that request. Please try again.