Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Enhanced traanslator comments documentation.

Partial (docs only) backport of 47ddd6a from master.
  • Loading branch information...
commit 73bb9664da6a1be1477e0f7e40c9e1b995f2114f 1 parent 11ec025
@ramiro ramiro authored
Showing with 72 additions and 5 deletions.
  1. +70 −5 docs/topics/i18n/translation.txt
  2. +2 −0  docs/topics/templates.txt
View
75 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
------------------------
@@ -629,6 +637,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
View
2  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
========
Please sign in to comment.
Something went wrong with that request. Please try again.