Ticket #13317: 13317-r13135.diff

File 13317-r13135.diff, 5.1 KB (added by ramiro, 5 years ago)

Patch for trunk

  • docs/ref/templates/builtins.txt

    diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
    a b  
    20612061
    20622062A collection of template tags that can be useful while designing a website,
    20632063such as a generator of Lorem Ipsum text. See :ref:`ref-contrib-webdesign`.
     2064
     2065i18n
     2066~~~~
     2067
     2068Provides a couple of templatetags that allow specifying translatable text in
     2069Django templates. It is slightly different from the libraries described
     2070above because you don't need to add any application to the ``INSTALLED_APPS``
     2071setting but rather set :setting:`USE_I18N` to True, then loading it with
     2072``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`.
  • docs/topics/i18n/internationalization.txt

    diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt
    a b  
    325325input is a proper string, then add support for lazy translation objects at the
    326326end.
    327327
     328.. _specifying-translation-strings-in-template-code:
     329
    328330Specifying translation strings: In template code
    329331================================================
    330332
     
    334336tags and a slightly different syntax than in Python code. To give your template
    335337access to these tags, put ``{% load i18n %}`` toward the top of your template.
    336338
     339``trans`` template tag
     340----------------------
     341
    337342The ``{% trans %}`` template tag translates either a constant string
    338343(enclosed in single or double quotes) or variable content::
    339344
     
    348353
    349354Internally, inline translations use an ``ugettext`` call.
    350355
     356In the translation of a template var case (``myvar`` above), at run-time the tag
     357first resolves such variable to a string and then looks up that string in the
     358message catalogs.
     359
    351360It's not possible to mix a template variable inside a string within ``{% trans
    352361%}``. If your translations require strings with variables (placeholders), use
    353 ``{% blocktrans %}``::
     362``{% blocktrans %}`` instead.
     363
     364``blocktrans`` template tag
     365---------------------------
     366
     367Contrarily to the ``trans`` tag, ``blocktrans`` allows to mark as translatable
     368complex sentences with mixed literal and variable content at template
     369creation-time by making use of placeholders::
    354370
    355371    {% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
    356372
    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::
     373To translate a template expression -- say, accessing object attributes or using
     374template filters -- you need to bind the expression to a local variable for use
     375within the translation block. Examples::
     376
     377    {% blocktrans with article.price as amount %}
     378    That will cost $ {{ amount }}.
     379    {% endblocktrans %}
    360380
    361381    {% blocktrans with value|filter as myvar %}
    362382    This will have {{ myvar }} inside.
     
    369389    This is {{ book_t }} by {{ author_t }}
    370390    {% endblocktrans %}
    371391
    372 To pluralize, specify both the singular and plural forms with the
    373 ``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
    374 ``{% endblocktrans %}``. Example::
     392This tag is also in charge of handling another functionality: Pluralization. To
     393make use of it you should:
     394
     395    * Designate and bind a counter value by using ``count``, such value will be
     396      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
     402An example::
    375403
    376404    {% blocktrans count list|length as counter %}
    377405    There is only one {{ name }} object.
     
    379407    There are {{ counter }} {{ name }} objects.
    380408    {% endblocktrans %}
    381409
    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.
     410A 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
     418When you both use the pluralization feature and bind values to local variables
     419in addition to the counter value, have in mind that the ``blocktrans`` construct
     420is internally converted to an ``ungettext`` call. This means the same
     421:ref:`notes regarding ungettext variables <pluralization-var-notes>` apply.
    387422
    388423.. _template-translation-vars:
    389424
     425Other tags
     426----------
     427
    390428Each ``RequestContext`` has access to three translation-specific variables:
    391429
    392430    * ``LANGUAGES`` is a list of tuples in which the first element is the
     
    400438      right-to-left language, e.g.: Hebrew, Arabic. If False it's a
    401439      left-to-right language, e.g.: English, French, German etc.
    402440
    403 
    404441If you don't use the ``RequestContext`` extension, you can get those values with
    405442three tags::
    406443
Back to Top