[docs] [issue25907] Documentation i18n: Added trans tags in sphinx templates

[Julien]

Julien added the comment:

@haypo I used the ``{trans}`` ``{endtrans}`` syntax because [Sphinx uses Jinja](http://www.sphinx-doc.org/en/stable/templating.html) and [``{trans}`` is the Jinja syntax for internationalisation](http://jinja.pocoo.org/docs/dev/templates/#i18n)

So ``{trans}`` is the standard syntax in this context and as you see I did not implemented a small script to parse them, Sphinx does it for me and add them in ``po`` files by itself, so Sphinx understand them, without need of some code.

It is possible to parse HTML to extract the strings to translate, but it would also fetch some false positives, and probably won't cut sentences at the right place, typically:

    <h1>The Python Documentation<h1>

is easy to parse, extract the sentence, translate it, and, at compile-time, search and replace the sentence by its translation, nice.

    Here are <a href="...">more details</a> about it.

Would be hard to parse: we'll need to introduce an heuristic to tell if we keep the HTML tag in the translation, or split it in three sentences "Here are", "more details", "about it". Sadly, splitting it in three sentences is not possible, because in some languages the order or those blocks may be swapped. So we need to get the <a href> and </a> inside the sentence to allow translator to move the three part around freely.

Also, the Jinja xgettext parser handle variables inside translation, to start from a non-standard syntax ``{{ variable_name }}`` to a more standard one (normally ``%s`` so the string can be used on almost every languages, but here) ``%(variable)s``.

Those variables are obligatory, without them we'll get *code* inside translations strings, like ``pathto("whatsnew/index")``, which is even uglier than ``%(variable)s``.

Here it is:

    <span class="linkdescr"> {% trans whatsnew_index=pathto("whatsnew/index") %}or <a href="{{ whatsnew_index }}">all "What's new" documents</a> since 2.0{% endtrans %}</span></p>

Which yiels, in po files:

    "or <a href=\"%(whatsnew_index)s\">all \"What's new\" documents</a> since 2.0"

Which is better than:

    "or <a href=\"{{ pathto("whatsnew/index") }}\">all \"What's new\" documents</a> since 2.0"

Which itself is better (for the re-ordering problem in other languages) than:

    "or"
    "all \"What's new documents"
    "since 2.0"

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue25907>
_______________________________________