Commit 73bb9664 authored by Ramiro Morales's avatar Ramiro Morales
Browse files

Enhanced traanslator comments documentation. 

Partial (docs only) backport of 47ddd6a4 from master.
parent 11ec0253

docs/topics/i18n/translation.txt

+70 −5
Original line number Diff line number Diff line
@@ -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

+2 −0
Original line number Diff line number Diff line
@@ -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

========