Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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.