Enhanced traanslator comments documentation.

Partial (docs only) backport of 47ddd6a from master.

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

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
 ========