From c796fc7e3630fcbc273d288609ab3cdbeda602a1 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Sun, 9 May 2010 13:55:15 +0000 Subject: [PATCH] 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 --- docs/ref/templates/builtins.txt | 9 ++++ docs/topics/i18n/internationalization.txt | 64 ++++++++++++++++++----- 2 files changed, 60 insertions(+), 13 deletions(-) diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 5f04c3d5e1..24c0af5699 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -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`. diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt index 1b1c68593a..7ae8d18791 100644 --- a/docs/topics/i18n/internationalization.txt +++ b/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 ` 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 ` 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 ` +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::