i18n: Add full support

.gitignore

@@ -46,10 +46,6 @@ coverage.xml
 *.cover
 .hypothesis/
 
-# Translations
-*.mo
-*.pot
-
 # Django stuff:
 *.log
 local_settings.py

MANIFEST.in

@@ -1,3 +1,4 @@
+include babel.cfg
 include MANIFEST.in
 include LICENSE
 include README.md

babel.cfg

@@ -0,0 +1,5 @@
+# See https://github.com/sphinx-doc/sphinx/blob/4.x/babel.cfg
+[jinja2: **.html]
+encoding = utf-8
+ignore_tags = script,style
+include_attrs = alt title summary placeholder

docs/contributing.rst

@@ -284,6 +284,34 @@ is required. The steps are roughly:
 - potentially remove the font being replaced from ``package.json`` and re-run ``yarn``
 - commit all of the changed files
 
+.. _translating-the-theme:
+
+Translating the theme
+=====================
+
+If any strings to be translated are added or changed, update the POT file:
+
+.. code-block:: bash
+
+   python setup.py extract_messages
+
+and then update the PO files:
+
+.. code-block:: bash
+
+   python setup.py update_catalog
+
+To add a new language, add a PO file (replace ``LANGUAGE_CODE`` with the two-letter lowercase ISO 639-1 language code):
+
+.. code-block:: bash
+
+   python setup.py init_catalog -l LANGUAGE_CODE
+
+If any PO files are updated, update the MO files:
+
+.. code-block:: bash
+
+   python setup.py compile_catalog
 
 Contributing changes
 ====================

docs/user_guide/i18n.rst

@@ -0,0 +1,61 @@
+Internationalization
+====================
+
+This theme contains translatable strings. Most strings will automatically be translated if the language is `supported <https://github.com/pydata/pydata-sphinx-theme/tree/master/pydata_sphinx_theme/locale>`__. To add another language, see :ref:`translating-the-theme`.
+
+The theme's :doc:`options<configuring>` also contain translatable strings, which require a different process. The following instructions assume that you store your translations in a ``locale`` directory under your documentation directory, and that you want to use ``theme`` as the name the message catalog for these strings.
+
+#. In your ``conf.py`` file:
+
+   .. code-block:: rst
+
+      import os.path
+      from sphinx.locale import get_translation
+
+      catalog = "theme"
+      _ = get_translation(catalog)
+
+      html_theme_options = {
+          "search_bar_text": _("Search the docs..."),
+
+          # You only need to translate the following if you use these features.
+          "icon_links_label": _("Quick Links"),
+          "icon_links": [
+              {
+                  "name": _("GitHub"),
+                  "url": "https://github.com/<your-org>/<your-repo>",
+                  "icon": "fab fa-github-square",
+              },
+          ],
+          "external_links": [
+              {
+                  "name": _("link-one-name"),
+                  "url": "https://<link-one>",
+              },
+          ],
+      }
+
+      def setup(app):
+         locale_dir = os.path.join(os.path.abspath(os.path.dirname(__file__), "locale")
+
+         app.add_message_catalog(catalog, locale_dir)
+
+#. Extract the strings to translate:
+
+   .. code-block:: bash
+
+      pybabel extract . -o locale/theme.pot
+
+#. Create a message catalog (changing the ``--locale`` option as desired):
+
+   .. code-block:: bash
+
+      pybabel init --input-file=locale/theme.pot --domain=theme --output-dir=locale --locale=fr
+
+#. Translate the message catalog by editing the file.
+
+#. Compile the message catalog:
+
+   .. code-block:: bash
+
+      pybabel compile --directory=locale --domain=theme

docs/user_guide/index.rst

@@ -10,3 +10,4 @@ User Guide
    configuring
    sections
    customizing
+   i18n

pydata_sphinx_theme/__init__.py

@@ -517,6 +517,9 @@ def setup(app):
     app.add_html_theme("pydata_sphinx_theme", theme_path)
     app.set_translator("html", BootstrapHTML5Translator)
 
+    # https://www.sphinx-doc.org/en/master/extdev/i18n.html#extension-internationalization-i18n-and-localization-l10n-using-i18n-api
+    app.add_message_catalog("sphinx", os.path.join(theme_path, "locale"))
+
     # Read the Docs uses ``readthedocs`` as the name of the build, and also
     # uses a special "dirhtml" builder so we need to replace these both with
     # our custom HTML builder
@@ -529,7 +532,7 @@ def setup(app):
 
     # Update templates for sidebar
     pkgdir = os.path.abspath(os.path.dirname(__file__))
-    path_templates = os.path.join(pkgdir, "_templates")
+    path_templates = os.path.join(pkgdir, "templates")
     app.config.templates_path.append(path_templates)
 
     return {"parallel_read_safe": True, "parallel_write_safe": True}

pydata_sphinx_theme/icon-links.html

@@ -1,20 +1,20 @@
 {%- macro icon_link_nav_item(url, icon, name) -%}
   {%- if url | length > 2 %}
         <li class="nav-item">
-          <a class="nav-link" href="{{ url }}" rel="noopener" target="_blank" title="{{ _(name) }}">
+          <a class="nav-link" href="{{ url }}" rel="noopener" target="_blank" title="{{ name }}">
             <span><i class="{{ icon }}"></i></span>
-            <label class="sr-only">{{ _(name) }}</label>
+            <label class="sr-only">{{ name }}</label>
           </a>
         </li>
   {%- endif -%}
 {%- endmacro -%}
 
-      <ul id="navbar-icon-links" class="navbar-nav" aria-label="{{ _(theme_icon_links_label) }}">
+      <ul id="navbar-icon-links" class="navbar-nav" aria-label="{{ theme_icon_links_label }}">
         {%- block icon_link_shortcuts -%}
-        {{ icon_link_nav_item(theme_github_url, "fab fa-github-square", "GitHub") -}}
-        {{ icon_link_nav_item(theme_gitlab_url, "fab fa-gitlab", "GitLab") -}}
-        {{ icon_link_nav_item(theme_bitbucket_url, "fab fa-bitbucket", "Bitbucket") -}}
-        {{ icon_link_nav_item(theme_twitter_url, "fab fa-twitter-square", "Twitter") -}}
+        {{ icon_link_nav_item(theme_github_url, "fab fa-github-square", _("GitHub")) -}}
+        {{ icon_link_nav_item(theme_gitlab_url, "fab fa-gitlab", _("GitLab")) -}}
+        {{ icon_link_nav_item(theme_bitbucket_url, "fab fa-bitbucket", _("Bitbucket")) -}}
+        {{ icon_link_nav_item(theme_twitter_url, "fab fa-twitter-square", _("Twitter")) -}}
         {% endblock -%}
         {%- for icon_link in theme_icon_links -%}
         {{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"]) -}}

pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po

@@ -0,0 +1,83 @@
+# Spanish translations for pydata-sphinx-theme.
+# Copyright (C) 2021 ORGANIZATION
+# This file is distributed under the same license as the pydata-sphinx-theme
+# project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2021.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: pydata-sphinx-theme 0.6.1\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2021-04-22 16:46-0400\n"
+"PO-Revision-Date: 2021-04-22 16:46-0400\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: es\n"
+"Language-Team: es <[email protected]>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.0\n"
+
+#: pydata_sphinx_theme/docs-navbar.html:9
+msgid "Toggle navigation"
+msgstr "Alternar navegación"
+
+#: pydata_sphinx_theme/icon-links.html:14
+msgid "GitHub"
+msgstr "GitHub"
+
+#: pydata_sphinx_theme/icon-links.html:15
+msgid "GitLab"
+msgstr "GitLab"
+
+#: pydata_sphinx_theme/icon-links.html:16
+msgid "Bitbucket"
+msgstr "Bitbucket"
+
+#: pydata_sphinx_theme/icon-links.html:17
+msgid "Twitter"
+msgstr "Twitter"
+
+#: pydata_sphinx_theme/layout.html:7
+msgid "previous page"
+msgstr "página anterior"
+
+#: pydata_sphinx_theme/layout.html:10
+msgid "next page"
+msgstr "siguiente página"
+
+#: pydata_sphinx_theme/templates/copyright.html:3
+#, python-format
+msgid "&copy; <a href=\"%(path)s\">Copyright</a> %(copyright)s."
+msgstr "&copy; <a href=\"%(path)s\">Copyright</a> %(copyright)s."
+
+#: pydata_sphinx_theme/templates/copyright.html:5
+#, python-format
+msgid "&copy; Copyright %(copyright)s."
+msgstr "&copy; Copyright %(copyright)s."
+
+#: pydata_sphinx_theme/templates/edit-this-page.html:5
+msgid "Edit this page"
+msgstr "Editar esta página"
+
+#: pydata_sphinx_theme/templates/last-updated.html:2
+#, python-format
+msgid "Last updated on %(last_updated)s."
+msgstr "Última actualización el %(last_updated)s"
+
+#: pydata_sphinx_theme/templates/page-toc.html:5
+msgid "On this page"
+msgstr "En esta página"
+
+#: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1
+msgid "Main navigation"
+msgstr "Navegación principal"
+
+#: pydata_sphinx_theme/templates/sphinx-version.html:2
+#, python-format
+msgid ""
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
+"%(sphinx_version)s."
+msgstr "Creado con <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
+"%(sphinx_version)s."

pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po

@@ -0,0 +1,83 @@
+# French translations for pydata-sphinx-theme.
+# Copyright (C) 2021 ORGANIZATION
+# This file is distributed under the same license as the pydata-sphinx-theme
+# project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2021.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: pydata-sphinx-theme 0.6.1\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2021-04-22 16:46-0400\n"
+"PO-Revision-Date: 2021-04-22 16:46-0400\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: fr\n"
+"Language-Team: fr <[email protected]>\n"
+"Plural-Forms: nplurals=2; plural=(n > 1)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.9.0\n"
+
+#: pydata_sphinx_theme/docs-navbar.html:9
+msgid "Toggle navigation"
+msgstr "Basculer la navigation"
+
+#: pydata_sphinx_theme/icon-links.html:14
+msgid "GitHub"
+msgstr "GitHub"
+
+#: pydata_sphinx_theme/icon-links.html:15
+msgid "GitLab"
+msgstr "GitLab"
+
+#: pydata_sphinx_theme/icon-links.html:16
+msgid "Bitbucket"
+msgstr "Bitbucket"
+
+#: pydata_sphinx_theme/icon-links.html:17
+msgid "Twitter"
+msgstr "Twitter"
+
+#: pydata_sphinx_theme/layout.html:7
+msgid "previous page"
+msgstr "page précédente"
+
+#: pydata_sphinx_theme/layout.html:10
+msgid "next page"
+msgstr "page suivante"
+
+#: pydata_sphinx_theme/templates/copyright.html:3
+#, python-format
+msgid "&copy; <a href=\"%(path)s\">Copyright</a> %(copyright)s."
+msgstr "&copy; <a href=\"%(path)s\">Droit d'auteur</a> %(copyright)s."
+
+#: pydata_sphinx_theme/templates/copyright.html:5
+#, python-format
+msgid "&copy; Copyright %(copyright)s."
+msgstr "&copy; Droit d'auteur %(copyright)s."
+
+#: pydata_sphinx_theme/templates/edit-this-page.html:5
+msgid "Edit this page"
+msgstr "Modifier cette page"
+
+#: pydata_sphinx_theme/templates/last-updated.html:2
+#, python-format
+msgid "Last updated on %(last_updated)s."
+msgstr "Dernière mise à jour le %(last_updated)s."
+
+#: pydata_sphinx_theme/templates/page-toc.html:5
+msgid "On this page"
+msgstr "Sur cette page"
+
+#: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1
+msgid "Main navigation"
+msgstr "Navigation principale"
+
+#: pydata_sphinx_theme/templates/sphinx-version.html:2
+#, python-format
+msgid ""
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
+"%(sphinx_version)s."
+msgstr "Créé à l'aide de <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
+"%(sphinx_version)s."