diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/releases/1.6.txt | 20 | ||||
| -rw-r--r-- | docs/topics/i18n/translation.txt | 75 | ||||
| -rw-r--r-- | docs/topics/templates.txt | 2 |
3 files changed, 92 insertions, 5 deletions
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index e0c07c40fe..79fa3ffb86 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -47,6 +47,26 @@ Backwards incompatible changes in 1.6 should review it as ``type='text'`` widgets might be now output as ``type='email'`` or ``type='url'`` depending on their corresponding field type. +* Extraction of translatable literals from templates with the + :djadmin:`makemessages` command now correctly detects i18n constructs when + they are located after a ``{#`` / ``#}``-type comment on the same line. E.g.: + + .. code-block:: html+django + + {# A comment #}{% trans "This literal was incorrectly ignored. Not anymore" %} + +* (Related to the above item.) Validation of the placement of + :ref:`translator-comments-in-templates` specified using ``{#`` / ``#}`` is now + stricter. All translator comments not located at the end of their respective + lines in a template are ignored and a warning is generated by + :djadmin:`makemessages` when it finds them. E.g.: + + .. code-block:: html+django + + {# Translators: This is ignored #}{% trans "Translate me" %} + {{ title }}{# Translators: Extracted and associated with 'Welcome' below #} + <h1>{% trans "Welcome" %}</h1> + .. warning:: In addition to the changes outlined in this section, be sure to review the diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 01f168bc10..3cf08e7ddf 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -142,14 +142,22 @@ preceding the string, e.g.:: # Translators: This message appears on the home page only output = ugettext("Welcome to my site.") -This also works in templates with the :ttag:`comment` tag: +The comment will then appear in the resulting ``.po`` file associated with the +translatable contruct located below it and should also be displayed by most +translation tools. -.. code-block:: html+django +.. note:: Just for completeness, this is the corresponding fragment of the + resulting ``.po`` file: + + .. code-block:: po - {% comment %}Translators: This is a text of the base template {% endcomment %} + #. Translators: This message appears on the home page only + # path/to/python/file.py:123 + msgid "Welcome to my site." + msgstr "" -The comment will then appear in the resulting ``.po`` file and should also be -displayed by most translation tools. +This also works in templates. See :ref:`translator-comments-in-templates` for +more details. Marking strings as no-op ------------------------ @@ -620,6 +628,63 @@ markers<contextual-markers>` using the ``context`` keyword: {% blocktrans with name=user.username context "greeting" %}Hi {{ name }}{% endblocktrans %} +.. _translator-comments-in-templates: + +Comments for translators in templates +------------------------------------- + +Just like with :ref:`Python code <translator-comments>`, these notes for +translators can be specified using comments, either with the :ttag:`comment` +tag: + +.. code-block:: html+django + + {% comment %}Translators: View verb{% endcomment %} + {% trans "View" %} + + {% comment %}Translators: Short intro blurb{% endcomment %} + <p>{% blocktrans %}A multiline translatable + literal.{% endblocktrans %}</p> + +or with the ``{#`` ... ``#}`` :ref:`one-line comment constructs <template-comments>`: + +.. code-block:: html+django + + {# Translators: Label of a button that triggers search{% endcomment #} + <button type="submit">{% trans "Go" %}</button> + + {# Translators: This is a text of the base template #} + {% blocktrans %}Ambiguous translatable block of text{% endtransblock %} + +.. note:: Just for completeness, these are the corresponding fragments of the + resulting ``.po`` file: + + .. code-block:: po + + #. Translators: View verb + # path/to/template/file.html:10 + msgid "View" + msgstr "" + + #. Translators: Short intro blurb + # path/to/template/file.html:13 + msgid "" + "A multiline translatable" + "literal." + msgstr "" + + # ... + + #. Translators: Label of a button that triggers search + # path/to/template/file.html:100 + msgid "Go" + msgstr "" + + #. Translators: + # path/to/template/file.html:103 + msgid "Ambiguous translatable block of text" + msgstr "" + .. _template-translation-vars: Other tags diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index fb2119515b..58a3ee9870 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -250,6 +250,8 @@ You can also create your own custom template tags; see tags and filters available for a given site. See :doc:`/ref/contrib/admin/admindocs`. +.. _template-comments: + Comments ======== |