Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Enhanced traanslator comments documentation.

Partial (docs only) backport of 47ddd6a from master.
  • Loading branch information...
commit 73bb9664da6a1be1477e0f7e40c9e1b995f2114f 1 parent 11ec025
Ramiro Morales authored January 31, 2013
75  docs/topics/i18n/translation.txt
@@ -142,14 +142,22 @@ preceding the string, e.g.::
142 142
         # Translators: This message appears on the home page only
143 143
         output = ugettext("Welcome to my site.")
144 144
 
145  
-This also works in templates with the :ttag:`comment` tag:
  145
+The comment will then appear in the resulting ``.po`` file associated with the
  146
+translatable contruct located below it and should also be displayed by most
  147
+translation tools.
146 148
 
147  
-.. code-block:: html+django
  149
+.. note:: Just for completeness, this is the corresponding fragment of the
  150
+    resulting ``.po`` file:
  151
+
  152
+    .. code-block:: po
148 153
 
149  
-    {% comment %}Translators: This is a text of the base template {% endcomment %}
  154
+        #. Translators: This message appears on the home page only
  155
+        # path/to/python/file.py:123
  156
+        msgid "Welcome to my site."
  157
+        msgstr ""
150 158
 
151  
-The comment will then appear in the resulting ``.po`` file and should also be
152  
-displayed by most translation tools.
  159
+This also works in templates. See :ref:`translator-comments-in-templates` for
  160
+more details.
153 161
 
154 162
 Marking strings as no-op
155 163
 ------------------------
@@ -629,6 +637,63 @@ markers<contextual-markers>` using the ``context`` keyword:
629 637
 
630 638
     {% blocktrans with name=user.username context "greeting" %}Hi {{ name }}{% endblocktrans %}
631 639
 
  640
+.. _translator-comments-in-templates:
  641
+
  642
+Comments for translators in templates
  643
+-------------------------------------
  644
+
  645
+Just like with :ref:`Python code <translator-comments>`, these notes for
  646
+translators can be specified using comments, either with the :ttag:`comment`
  647
+tag:
  648
+
  649
+.. code-block:: html+django
  650
+
  651
+    {% comment %}Translators: View verb{% endcomment %}
  652
+    {% trans "View" %}
  653
+
  654
+    {% comment %}Translators: Short intro blurb{% endcomment %}
  655
+    <p>{% blocktrans %}A multiline translatable
  656
+    literal.{% endblocktrans %}</p>
  657
+
  658
+or with the ``{#`` ... ``#}`` :ref:`one-line comment constructs <template-comments>`:
  659
+
  660
+.. code-block:: html+django
  661
+
  662
+    {# Translators: Label of a button that triggers search{% endcomment #}
  663
+    <button type="submit">{% trans "Go" %}</button>
  664
+
  665
+    {# Translators: This is a text of the base template #}
  666
+    {% blocktrans %}Ambiguous translatable block of text{% endtransblock %}
  667
+
  668
+.. note:: Just for completeness, these are the corresponding fragments of the
  669
+    resulting ``.po`` file:
  670
+
  671
+    .. code-block:: po
  672
+
  673
+        #. Translators: View verb
  674
+        # path/to/template/file.html:10
  675
+        msgid "View"
  676
+        msgstr ""
  677
+
  678
+        #. Translators: Short intro blurb
  679
+        # path/to/template/file.html:13
  680
+        msgid ""
  681
+        "A multiline translatable"
  682
+        "literal."
  683
+        msgstr ""
  684
+
  685
+        # ...
  686
+
  687
+        #. Translators: Label of a button that triggers search
  688
+        # path/to/template/file.html:100
  689
+        msgid "Go"
  690
+        msgstr ""
  691
+
  692
+        #. Translators:
  693
+        # path/to/template/file.html:103
  694
+        msgid "Ambiguous translatable block of text"
  695
+        msgstr ""
  696
+
632 697
 .. _template-translation-vars:
633 698
 
634 699
 Other tags
2  docs/topics/templates.txt
@@ -250,6 +250,8 @@ You can also create your own custom template tags; see
250 250
     tags and filters available for a given site. See
251 251
     :doc:`/ref/contrib/admin/admindocs`.
252 252
 
  253
+.. _template-comments:
  254
+
253 255
 Comments
254 256
 ========
255 257
 

0 notes on commit 73bb966

Please sign in to comment.
Something went wrong with that request. Please try again.