doc: i18n HTML templates

Issue #25907: Use {% trans %} tags in HTML templates to ease the translation of
the documentation. The tag comes from Jinja templating system, used by Sphinx.

Patch written by Julien Palard.

Doc/tools/templates/download.html

@@ -7,55 +7,96 @@
 {% endif %}
 
 {% block body %}
-<h1>Download Python {{ release }} Documentation</h1>
+<h1>{% trans %}Download Python {{ release }} Documentation{% endtrans %}</h1>
 
-{% if last_updated %}<p><b>Last updated on: {{ last_updated }}.</b></p>{% endif %}
+{% if last_updated %}
+  <p><b>{% trans %}Last updated on: {{ last_updated }}.{% endtrans %}</b></p>
+{% endif %}
 
-<p>To download an archive containing all the documents for this version of
-Python in one of various formats, follow one of links in this table. The numbers
-in the table are the size of the download files in megabytes.</p>
+<p>{% trans %}To download an archive containing all the documents for
+this version of Python in one of various formats, follow one of links
+in this table. The numbers in the table are the size of the download
+files in megabytes.{% endtrans %}</p>
 
 <table class="docutils">
-  <tr><th>Format</th><th>Packed as .zip</th><th>Packed as .tar.bz2</th></tr>
-  <tr><td>PDF (US-Letter paper size)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.zip">Download</a> (ca. 8 MB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.tar.bz2">Download</a> (ca. 8 MB)</td>
+  <tr><th>{% trans %}Format{% endtrans %}</th>
+    <th>{% trans %}Packed as .zip{% endtrans %}</th>
+    <th>{% trans %}Packed as .tar.bz2{% endtrans %}</th>
+  </tr>
+  <tr><td>{% trans %}PDF (US-Letter paper size){% endtrans %}</td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.zip">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 8 MB){% endtrans %}
+    </td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.tar.bz2">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 8 MB){% endtrans %}
+    </td>
   </tr>
-  <tr><td>PDF (A4 paper size)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.zip">Download</a> (ca. 8 MB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.tar.bz2">Download</a> (ca. 8 MB)</td>
+  <tr><td>{% trans %}PDF (A4 paper size){% endtrans %}</td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.zip">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 8 MB){% endtrans %}</td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.tar.bz2">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 8 MB){% endtrans %}</td>
   </tr>
-  <tr><td>HTML</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-html.zip">Download</a> (ca. 6 MB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-html.tar.bz2">Download</a> (ca. 4 MB)</td>
+  <tr><td>{% trans %}HTML{% endtrans %}</td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-html.zip">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 6 MB){% endtrans %}
+    </td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-html.tar.bz2">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 4 MB){% endtrans %}
+    </td>
   </tr>
-  <tr><td>Plain Text</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-text.zip">Download</a> (ca. 2 MB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-text.tar.bz2">Download</a> (ca. 1.5 MB)</td>
+  <tr>
+    <td>{% trans %}Plain Text{% endtrans %}</td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-text.zip">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 2 MB){% endtrans %}
+    </td>
+    <td>
+      <a href="{{ dlbase }}/python-{{ release }}-docs-text.tar.bz2">
+        {% trans %}Download{% endtrans %}
+      </a> {% trans %}(ca. 1.5 MB){% endtrans %}
+    </td>
   </tr>
 </table>
 
-<p>These archives contain all the content in the documentation.</p>
+<p>{% trans %}These archives contain all the content in the
+documentation.{% endtrans %}</p>
 
-<p>HTML Help (<tt>.chm</tt>) files are made available in the "Windows" section
-on the <a href="https://www.python.org/download/releases/{{ release[:5] }}/">Python
-download page</a>.</p>
+<p>{% trans download_page="https://www.python.org/download/releases/{{ release[:5] }}/" %}HTML Help
+(<tt>.chm</tt>) files are made available in the "Windows" section
+on the <a href={{ download_page }}>Python download page</a>.{% endtrans %}</p>
 
 
-<h2>Unpacking</h2>
+<h2>{% trans %}Unpacking{% endtrans %}</h2>
 
-<p>Unix users should download the .tar.bz2 archives; these are bzipped tar
-archives and can be handled in the usual way using tar and the bzip2
-program. The <a href="http://www.info-zip.org">InfoZIP</a> unzip program can be
-used to handle the ZIP archives if desired. The .tar.bz2 archives provide the
-best compression and fastest download times.</p>
+<p>{% trans %}Unix users should download the .tar.bz2 archives; these
+are bzipped tar archives and can be handled in the usual way using tar
+and the bzip2 program. The <a href="http://www.info-zip.org">InfoZIP</a> unzip
+program can be used to handle the ZIP archives if desired. The
+.tar.bz2 archives provide the best compression and fastest download
+times.{% endtrans %}</p>
 
-<p>Windows users can use the ZIP archives since those are customary on that
-platform. These are created on Unix using the InfoZIP zip program.</p>
+<p>{% trans %}Windows users can use the ZIP archives since those are
+customary on that platform. These are created on Unix using the
+InfoZIP zip program.{% endtrans %}</p>
 
 
-<h2>Problems</h2>
+<h2>{% trans %}Problems{% endtrans %}</h2>
 
-<p>If you have comments or suggestions for the Python documentation, please send
-email to <a href="mailto:docs@python.org">docs@python.org</a>.</p>
+<p>{% trans %}If you have comments or suggestions for the Python
+documentation, please send email to
+<a href="mailto:docs@python.org">docs@python.org</a>.{% endtrans %}</p>
 {% endblock %}

Doc/tools/templates/indexcontent.html

 {% extends "defindex.html" %}
 {% block tables %}
-  <p><strong>Parts of the documentation:</strong></p>
+  <p><strong>{% trans %}Parts of the documentation:{% endtrans %}</strong></p>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">What's new in Python {{ version }}?</a><br/>
-         <span class="linkdescr">or <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a> since 2.0</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">Tutorial</a><br/>
-         <span class="linkdescr">start here</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
-         <span class="linkdescr">keep this under your pillow</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">Language Reference</a><br/>
-         <span class="linkdescr">describes syntax and language elements</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">Python Setup and Usage</a><br/>
-         <span class="linkdescr">how to use Python on different platforms</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">Python HOWTOs</a><br/>
-         <span class="linkdescr">in-depth documents on specific topics</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">{% trans %}What's new in Python {{ version }}?{% endtrans %}</a><br/>
+         <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>
+      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{% trans %}Tutorial{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}start here{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">{% trans %}Library Reference{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}keep this under your pillow{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">{% trans %}Language Reference{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}describes syntax and language elements{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">{% trans %}Python Setup and Usage{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}how to use Python on different platforms{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}in-depth documents on specific topics{% endtrans %}</span></p>
     </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">Extending and Embedding</a><br/>
-         <span class="linkdescr">tutorial for C/C++ programmers</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br/>
-         <span class="linkdescr">reference for C/C++ programmers</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Modules</a><br/>
-         <span class="linkdescr">information for installers &amp; sys-admins</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">Distributing Python Modules</a><br/>
-         <span class="linkdescr">sharing modules with others</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
-         <span class="linkdescr">frequently asked questions (with answers!)</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and Embedding{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}tutorial for C/C++ programmers{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">{% trans %}Python/C API{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}reference for C/C++ programmers{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}information for installers &amp; sys-admins{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}sharing modules with others{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}frequently asked questions (with answers!){% endtrans %}</span></p>
     </td></tr>
   </table>
 
-  <p><strong>Indices and tables:</strong></p>
+  <p><strong>{% trans %}Indices and tables:{% endtrans %}</strong></p>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("py-modindex") }}">Global Module Index</a><br/>
-         <span class="linkdescr">quick access to all modules</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
-         <span class="linkdescr">all functions, classes, terms</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/>
-         <span class="linkdescr">the most important terms explained</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("py-modindex") }}">{% trans %}Global Module Index{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}quick access to all modules{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{% trans %}General Index{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}all functions, classes, terms{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">{% trans %}Glossary{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}the most important terms explained{% endtrans %}</span></p>
     </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
-         <span class="linkdescr">search this documentation</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br/>
-         <span class="linkdescr">lists all sections and subsections</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{% trans %}Search page{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}search this documentation{% endtrans %}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{% trans %}Complete Table of Contents{% endtrans %}</a><br/>
+         <span class="linkdescr">{% trans %}lists all sections and subsections{% endtrans %}</span></p>
     </td></tr>
   </table>
 
-  <p><strong>Meta information:</strong></p>
+  <p><strong>{% trans %}Meta information:{% endtrans %}</strong></p>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About the documentation</a></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">{% trans %}Reporting bugs{% endtrans %}</a></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">{% trans %}About the documentation{% endtrans %}</a></p>
     </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">History and License of Python</a></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("copyright") }}">Copyright</a></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">{% trans %}History and License of Python{% endtrans %}</a></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("copyright") }}">{% trans %}Copyright{% endtrans %}</a></p>
     </td></tr>
   </table>
 {% endblock %}

Doc/tools/templates/indexsidebar.html

-<h3>Download</h3>
-<p><a href="{{ pathto('download') }}">Download these documents</a></p>
-<h3>Docs for other versions</h3>
+<h3>{% trans %}Download{% endtrans %}</h3>
+<p><a href="{{ pathto('download') }}">{% trans %}Download these documents{% endtrans %}</a></p>
+<h3>{% trans %}Docs for other versions{% endtrans %}</h3>
 <ul>
-  <li><a href="https://docs.python.org/3.4/">Python 3.4 (stable)</a></li>
-  <li><a href="https://docs.python.org/3.5/">Python 3.5 (in development)</a></li>
-  <li><a href="https://www.python.org/doc/versions/">Old versions</a></li>
+  <li><a href="https://docs.python.org/3.4/">{% trans %}Python 3.4 (stable){% endtrans %}</a></li>
+  <li><a href="https://docs.python.org/3.5/">{% trans %}Python 3.5 (in development){% endtrans %}</a></li>
+  <li><a href="https://www.python.org/doc/versions/">{% trans %}Old versions{% endtrans %}</a></li>
 </ul>
 
-<h3>Other resources</h3>
+<h3>{% trans %}Other resources{% endtrans %}</h3>
 <ul>
   {# XXX: many of these should probably be merged in the main docs #}
-  <li><a href="https://www.python.org/dev/peps/">PEP Index</a></li>
-  <li><a href="https://wiki.python.org/moin/BeginnersGuide">Beginner's Guide</a></li>
-  <li><a href="https://wiki.python.org/moin/PythonBooks">Book List</a></li>
-  <li><a href="https://www.python.org/doc/av/">Audio/Visual Talks</a></li>
+  <li><a href="https://www.python.org/dev/peps/">{% trans %}PEP Index{% endtrans %}</a></li>
+  <li><a href="https://wiki.python.org/moin/BeginnersGuide">{% trans %}Beginner's Guide{% endtrans %}</a></li>
+  <li><a href="https://wiki.python.org/moin/PythonBooks">{% trans %}Book List{% endtrans %}</a></li>
+  <li><a href="https://www.python.org/doc/av/">{% trans %}Audio/Visual Talks{% endtrans %}</a></li>
 </ul>

Doc/tools/templates/layout.html

@@ -6,7 +6,7 @@
         <li>
           {%- if versionswitcher is defined %}
           <span class="version_switcher_placeholder">{{ release }}</span>
-          <a href="{{ pathto('index') }}">Documentation</a>{{ reldelim1 }}
+          <a href="{{ pathto('index') }}">{% trans %}Documentation{% endtrans %}</a>{{ reldelim1 }}
           {%- else %}
           <a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}
           {%- endif %}
@@ -28,24 +28,24 @@
 {% endblock %}
 {% block footer %}
     <div class="footer">
-    &copy; <a href="{{ pathto('copyright') }}">Copyright</a> {{ copyright|e }}.
+    &copy; <a href="{{ pathto('copyright') }}">{% trans %}Copyright{% endtrans %}</a> {{ copyright|e }}.
     <br />
-    The Python Software Foundation is a non-profit corporation.
-    <a href="https://www.python.org/psf/donations/">Please donate.</a>
+    {% trans %}The Python Software Foundation is a non-profit corporation.{% endtrans %}
+    <a href="https://www.python.org/psf/donations/">{% trans %}Please donate.{% endtrans %}</a>
     <br />
-    Last updated on {{ last_updated|e }}.
-    <a href="{{ pathto('bugs') }}">Found a bug</a>?
+    {% trans last_update=last_updated|e %}Last updated on {{ last_update }}.{% endtrans %}
+    {% trans pathto_bugs=pathto('bugs') %}<a href="{{ pathto_bugs }}">Found a bug</a>?{% endtrans %}
     <br />
-    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version|e }}.
+    {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
     </div>
 {% endblock %}
 {% block sidebarsourcelink %}
 {%- if show_source and has_source and sourcename %}
 <h3>{{ _('This Page') }}</h3>
 <ul class="this-page-menu">
-  <li><a href="{{ pathto('bugs') }}">Report a Bug</a></li>
+  <li><a href="{{ pathto('bugs') }}">{% trans %}Report a Bug{% endtrans %}</a></li>
   <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
-         rel="nofollow">Show Source</a></li>
+         rel="nofollow">{% trans %}Show Source{% endtrans %}</a></li>
 </ul>
 {%- endif %}
 {% endblock %}