From cf9fb89b4bcf456f42332aa5e1840bbc2f62d56e Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 16:45:48 -0400 Subject: [PATCH 01/17] chore: Rename _templates to templates so that it is visible to Babel --- pydata_sphinx_theme/__init__.py | 2 +- pydata_sphinx_theme/{_templates => templates}/copyright.html | 0 .../{_templates => templates}/edit-this-page.html | 0 pydata_sphinx_theme/{_templates => templates}/last-updated.html | 0 .../{_templates => templates}/navbar-icon-links.html | 0 pydata_sphinx_theme/{_templates => templates}/navbar-logo.html | 0 pydata_sphinx_theme/{_templates => templates}/navbar-nav.html | 0 pydata_sphinx_theme/{_templates => templates}/page-toc.html | 0 .../{_templates => templates}/sidebar-ethical-ads.html | 0 .../{_templates => templates}/sidebar-nav-bs.html | 0 .../{_templates => templates}/sphinx-version.html | 0 11 files changed, 1 insertion(+), 1 deletion(-) rename pydata_sphinx_theme/{_templates => templates}/copyright.html (100%) rename pydata_sphinx_theme/{_templates => templates}/edit-this-page.html (100%) rename pydata_sphinx_theme/{_templates => templates}/last-updated.html (100%) rename pydata_sphinx_theme/{_templates => templates}/navbar-icon-links.html (100%) rename pydata_sphinx_theme/{_templates => templates}/navbar-logo.html (100%) rename pydata_sphinx_theme/{_templates => templates}/navbar-nav.html (100%) rename pydata_sphinx_theme/{_templates => templates}/page-toc.html (100%) rename pydata_sphinx_theme/{_templates => templates}/sidebar-ethical-ads.html (100%) rename pydata_sphinx_theme/{_templates => templates}/sidebar-nav-bs.html (100%) rename pydata_sphinx_theme/{_templates => templates}/sphinx-version.html (100%) diff --git a/pydata_sphinx_theme/__init__.py b/pydata_sphinx_theme/__init__.py index d9e7e9ec6..8028bf8af 100644 --- a/pydata_sphinx_theme/__init__.py +++ b/pydata_sphinx_theme/__init__.py @@ -529,7 +529,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} diff --git a/pydata_sphinx_theme/_templates/copyright.html b/pydata_sphinx_theme/templates/copyright.html similarity index 100% rename from pydata_sphinx_theme/_templates/copyright.html rename to pydata_sphinx_theme/templates/copyright.html diff --git a/pydata_sphinx_theme/_templates/edit-this-page.html b/pydata_sphinx_theme/templates/edit-this-page.html similarity index 100% rename from pydata_sphinx_theme/_templates/edit-this-page.html rename to pydata_sphinx_theme/templates/edit-this-page.html diff --git a/pydata_sphinx_theme/_templates/last-updated.html b/pydata_sphinx_theme/templates/last-updated.html similarity index 100% rename from pydata_sphinx_theme/_templates/last-updated.html rename to pydata_sphinx_theme/templates/last-updated.html diff --git a/pydata_sphinx_theme/_templates/navbar-icon-links.html b/pydata_sphinx_theme/templates/navbar-icon-links.html similarity index 100% rename from pydata_sphinx_theme/_templates/navbar-icon-links.html rename to pydata_sphinx_theme/templates/navbar-icon-links.html diff --git a/pydata_sphinx_theme/_templates/navbar-logo.html b/pydata_sphinx_theme/templates/navbar-logo.html similarity index 100% rename from pydata_sphinx_theme/_templates/navbar-logo.html rename to pydata_sphinx_theme/templates/navbar-logo.html diff --git a/pydata_sphinx_theme/_templates/navbar-nav.html b/pydata_sphinx_theme/templates/navbar-nav.html similarity index 100% rename from pydata_sphinx_theme/_templates/navbar-nav.html rename to pydata_sphinx_theme/templates/navbar-nav.html diff --git a/pydata_sphinx_theme/_templates/page-toc.html b/pydata_sphinx_theme/templates/page-toc.html similarity index 100% rename from pydata_sphinx_theme/_templates/page-toc.html rename to pydata_sphinx_theme/templates/page-toc.html diff --git a/pydata_sphinx_theme/_templates/sidebar-ethical-ads.html b/pydata_sphinx_theme/templates/sidebar-ethical-ads.html similarity index 100% rename from pydata_sphinx_theme/_templates/sidebar-ethical-ads.html rename to pydata_sphinx_theme/templates/sidebar-ethical-ads.html diff --git a/pydata_sphinx_theme/_templates/sidebar-nav-bs.html b/pydata_sphinx_theme/templates/sidebar-nav-bs.html similarity index 100% rename from pydata_sphinx_theme/_templates/sidebar-nav-bs.html rename to pydata_sphinx_theme/templates/sidebar-nav-bs.html diff --git a/pydata_sphinx_theme/_templates/sphinx-version.html b/pydata_sphinx_theme/templates/sphinx-version.html similarity index 100% rename from pydata_sphinx_theme/_templates/sphinx-version.html rename to pydata_sphinx_theme/templates/sphinx-version.html From 44ad97f84c89a37e48902a6e8cbdf7c7c8e1e0cc Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 16:46:58 -0400 Subject: [PATCH 02/17] gitignore: Do not ignore MO and POT files, which must be committed --- .gitignore | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.gitignore b/.gitignore index 28b7d6492..62bcb3e7f 100644 --- a/.gitignore +++ b/.gitignore @@ -46,10 +46,6 @@ coverage.xml *.cover .hypothesis/ -# Translations -*.mo -*.pot - # Django stuff: *.log local_settings.py From 41eca955db5b67446860f0ab2e24b51c12766702 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 16:47:49 -0400 Subject: [PATCH 03/17] templates: Translate strings instead of variables where possible --- pydata_sphinx_theme/icon-links.html | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pydata_sphinx_theme/icon-links.html b/pydata_sphinx_theme/icon-links.html index 4dd3aa921..ad8aa2dec 100644 --- a/pydata_sphinx_theme/icon-links.html +++ b/pydata_sphinx_theme/icon-links.html @@ -1,9 +1,9 @@ {%- macro icon_link_nav_item(url, icon, name) -%} {%- if url | length > 2 %}
  • - + - +
    • {%- endif -%} @@ -11,12 +11,12 @@ From cff23742a49444292a04f9406e31eea2b5012e4e Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 16:48:28 -0400 Subject: [PATCH 04/17] i18n: Configure Babel --- MANIFEST.in | 1 + babel.cfg | 5 +++++ setup.cfg | 20 ++++++++++++++++++++ 3 files changed, 26 insertions(+) create mode 100644 babel.cfg diff --git a/MANIFEST.in b/MANIFEST.in index 5fc45e8d0..7c869bb77 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,4 @@ +include babel.cfg include MANIFEST.in include LICENSE include README.md diff --git a/babel.cfg b/babel.cfg new file mode 100644 index 000000000..fb61a5494 --- /dev/null +++ b/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 diff --git a/setup.cfg b/setup.cfg index 0d9abf7dd..86e02c2c7 100644 --- a/setup.cfg +++ b/setup.cfg @@ -4,3 +4,23 @@ ignore = E203, # space before : (needed for how black formats slicing) W503, # line break before binary operator exclude = setup.py,docs/conf.py,node_modules,docs,build,dist + +# See https://github.com/sphinx-doc/sphinx/blob/4.x/setup.cfg +[extract_messages] +mapping_file = babel.cfg +output_file = pydata_sphinx_theme/locale/sphinx.pot +keywords = _ __ l_ lazy_gettext + +[init_catalog] +domain = sphinx +input_file = pydata_sphinx_theme/locale/sphinx.pot +output_dir = pydata_sphinx_theme/locale/ + +[update_catalog] +domain = sphinx +input_file = pydata_sphinx_theme/locale/sphinx.pot +output_dir = pydata_sphinx_theme/locale/ + +[compile_catalog] +domain = sphinx +directory = pydata_sphinx_theme/locale/ From ad6058213844df533eef58c913c02dc36d3a30ba Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 16:50:44 -0400 Subject: [PATCH 05/17] i18n: Generate POT files and empty PO files --- .../locale/es/LC_MESSAGES/sphinx.po | 83 +++++++++++++++++++ .../locale/fr/LC_MESSAGES/sphinx.po | 83 +++++++++++++++++++ pydata_sphinx_theme/locale/sphinx.pot | 82 ++++++++++++++++++ 3 files changed, 248 insertions(+) create mode 100644 pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po create mode 100644 pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po create mode 100644 pydata_sphinx_theme/locale/sphinx.pot diff --git a/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..56831ca16 --- /dev/null +++ b/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 , 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 \n" +"Language: es\n" +"Language-Team: es \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 "" + +#: pydata_sphinx_theme/icon-links.html:14 +msgid "GitHub" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:15 +msgid "GitLab" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:16 +msgid "Bitbucket" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:17 +msgid "Twitter" +msgstr "" + +#: pydata_sphinx_theme/layout.html:7 +msgid "previous page" +msgstr "" + +#: pydata_sphinx_theme/layout.html:10 +msgid "next page" +msgstr "" + +#: pydata_sphinx_theme/templates/copyright.html:3 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: pydata_sphinx_theme/templates/copyright.html:5 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: pydata_sphinx_theme/templates/edit-this-page.html:5 +msgid "Edit this page" +msgstr "" + +#: pydata_sphinx_theme/templates/last-updated.html:2 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "" + +#: pydata_sphinx_theme/templates/page-toc.html:5 +msgid "On this page" +msgstr "" + +#: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1 +msgid "Main navigation" +msgstr "" + +#: pydata_sphinx_theme/templates/sphinx-version.html:2 +#, python-format +msgid "" +"Created using Sphinx " +"%(sphinx_version)s." +msgstr "" + diff --git a/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..19a9fee85 --- /dev/null +++ b/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 , 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 \n" +"Language: fr\n" +"Language-Team: fr \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 "" + +#: pydata_sphinx_theme/icon-links.html:14 +msgid "GitHub" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:15 +msgid "GitLab" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:16 +msgid "Bitbucket" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:17 +msgid "Twitter" +msgstr "" + +#: pydata_sphinx_theme/layout.html:7 +msgid "previous page" +msgstr "" + +#: pydata_sphinx_theme/layout.html:10 +msgid "next page" +msgstr "" + +#: pydata_sphinx_theme/templates/copyright.html:3 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: pydata_sphinx_theme/templates/copyright.html:5 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: pydata_sphinx_theme/templates/edit-this-page.html:5 +msgid "Edit this page" +msgstr "" + +#: pydata_sphinx_theme/templates/last-updated.html:2 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "" + +#: pydata_sphinx_theme/templates/page-toc.html:5 +msgid "On this page" +msgstr "" + +#: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1 +msgid "Main navigation" +msgstr "" + +#: pydata_sphinx_theme/templates/sphinx-version.html:2 +#, python-format +msgid "" +"Created using Sphinx " +"%(sphinx_version)s." +msgstr "" + diff --git a/pydata_sphinx_theme/locale/sphinx.pot b/pydata_sphinx_theme/locale/sphinx.pot new file mode 100644 index 000000000..e3fb3dde1 --- /dev/null +++ b/pydata_sphinx_theme/locale/sphinx.pot @@ -0,0 +1,82 @@ +# Translations template for pydata-sphinx-theme. +# Copyright (C) 2021 ORGANIZATION +# This file is distributed under the same license as the pydata-sphinx-theme +# project. +# FIRST AUTHOR , 2021. +# +#, fuzzy +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: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \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 "" + +#: pydata_sphinx_theme/icon-links.html:14 +msgid "GitHub" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:15 +msgid "GitLab" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:16 +msgid "Bitbucket" +msgstr "" + +#: pydata_sphinx_theme/icon-links.html:17 +msgid "Twitter" +msgstr "" + +#: pydata_sphinx_theme/layout.html:7 +msgid "previous page" +msgstr "" + +#: pydata_sphinx_theme/layout.html:10 +msgid "next page" +msgstr "" + +#: pydata_sphinx_theme/templates/copyright.html:3 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: pydata_sphinx_theme/templates/copyright.html:5 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: pydata_sphinx_theme/templates/edit-this-page.html:5 +msgid "Edit this page" +msgstr "" + +#: pydata_sphinx_theme/templates/last-updated.html:2 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "" + +#: pydata_sphinx_theme/templates/page-toc.html:5 +msgid "On this page" +msgstr "" + +#: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1 +msgid "Main navigation" +msgstr "" + +#: pydata_sphinx_theme/templates/sphinx-version.html:2 +#, python-format +msgid "" +"Created using Sphinx " +"%(sphinx_version)s." +msgstr "" + From a4a6d683eb1a722a4d992e04cd3f2a7a75957ab9 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 16:50:57 -0400 Subject: [PATCH 06/17] i18n: Add basic documentation --- docs/contributing.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index 542ea2489..3c6afb4cf 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -284,6 +284,32 @@ 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 +===================== + +If any strings to be translated are added or changed, maintainers 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 + +After updating the PO files, update the MO files: + +.. code-block:: bash + + python setup.py compile_catalog Contributing changes ==================== From 67f1c7a7d31f30a95de672ddba3fb1579a6e8033 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 18:06:17 -0400 Subject: [PATCH 07/17] i18n: Babel can't translate variables --- pydata_sphinx_theme/icon-links.html | 4 ++-- pydata_sphinx_theme/search-field.html | 2 +- pydata_sphinx_theme/templates/navbar-nav.html | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pydata_sphinx_theme/icon-links.html b/pydata_sphinx_theme/icon-links.html index ad8aa2dec..2f8ff425a 100644 --- a/pydata_sphinx_theme/icon-links.html +++ b/pydata_sphinx_theme/icon-links.html @@ -9,7 +9,7 @@ {%- endif -%} {%- endmacro -%} - \ No newline at end of file From 13526fd47a1eaaaa6aa76c637df477d00b863c33 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 18:42:22 -0400 Subject: [PATCH 08/17] i18n: Make Sphinx aware of the theme's message catalog --- pydata_sphinx_theme/__init__.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pydata_sphinx_theme/__init__.py b/pydata_sphinx_theme/__init__.py index 8028bf8af..1511af041 100644 --- a/pydata_sphinx_theme/__init__.py +++ b/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 From 5fab594a7be2b65064b65e9b40326ec48e5e9588 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 21:00:53 -0400 Subject: [PATCH 09/17] i18n: Add es and fr translations --- docs/contributing.rst | 4 +-- .../locale/es/LC_MESSAGES/sphinx.mo | Bin 0 -> 1345 bytes .../locale/es/LC_MESSAGES/sphinx.po | 30 +++++++++--------- .../locale/fr/LC_MESSAGES/sphinx.mo | Bin 0 -> 1362 bytes .../locale/fr/LC_MESSAGES/sphinx.po | 30 +++++++++--------- 5 files changed, 32 insertions(+), 32 deletions(-) create mode 100644 pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.mo create mode 100644 pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.mo diff --git a/docs/contributing.rst b/docs/contributing.rst index 3c6afb4cf..bfc9e59f4 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -287,7 +287,7 @@ is required. The steps are roughly: Translating the theme ===================== -If any strings to be translated are added or changed, maintainers update the POT file: +If any strings to be translated are added or changed, update the POT file: .. code-block:: bash @@ -305,7 +305,7 @@ To add a new language, add a PO file (replace ``LANGUAGE_CODE`` with the two-let python setup.py init_catalog -l LANGUAGE_CODE -After updating the PO files, update the MO files: +If any PO files are updated, update the MO files: .. code-block:: bash diff --git a/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.mo b/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.mo new file mode 100644 index 0000000000000000000000000000000000000000..f8c96aa339a3378092b1094450babd41ca5530fe GIT binary patch literal 1345 zcmcJO&rcIU6vr1ujTQW@(ZuLLq5+cWuMh%D+fdqqkQNA3uVlJAY)7}Vo7q_e{|HYS z6K{I+X5!TwM{nMYi3k4!&tCjayDgQ27vm^f+4f1K{=-X876Er9FrSHNrF3()AkOZXm~f&Brz0e%CG{!j2aIC7?^dlNKu z+yyU#S$> zuFyocMMOg8acfoRhjGiG&RSNTMViE++tmvsYVzUPO+4oF1{0D#@Ps>>uDSGauST1MhtOv2mBvv>Di>)+n#lm&(=Zc5P=TwYAx#-HxF;TE#(ZlF#OIG&@W4d6Jv6 zXXmiaW)VoYQHtryU*k+qXj3s6`Ai4OCM%EXb+S=z)JWkE=~AlBq!**BHsR60piRy? z#zPAA`jRiqHI-6Zeyo^JR|3_EY$C(185Q%3q_-?iNitC+x#?76tx-E}PA;8IRRXEG zL{Wz!q%>Na34PqlB5~SGMO+tSy+`Md<4o~;T+y0z0vAJMllhj=sZ}nyGFMHP4{fr{ zTHGi3^a2$6)A@gg+6{<Copyright %(copyright)s." -msgstr "" +msgstr "© Copyright %(copyright)s." #: pydata_sphinx_theme/templates/copyright.html:5 #, python-format msgid "© Copyright %(copyright)s." -msgstr "" +msgstr "© Copyright %(copyright)s." #: pydata_sphinx_theme/templates/edit-this-page.html:5 msgid "Edit this page" -msgstr "" +msgstr "Editar esta página" #: pydata_sphinx_theme/templates/last-updated.html:2 #, python-format msgid "Last updated on %(last_updated)s." -msgstr "" +msgstr "Última actualización el %(last_updated)s" #: pydata_sphinx_theme/templates/page-toc.html:5 msgid "On this page" -msgstr "" +msgstr "En esta página" #: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1 msgid "Main navigation" -msgstr "" +msgstr "Navegación principal" #: pydata_sphinx_theme/templates/sphinx-version.html:2 #, python-format msgid "" "Created using Sphinx " "%(sphinx_version)s." -msgstr "" - +msgstr "Creado con Sphinx " +"%(sphinx_version)s." diff --git a/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.mo b/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.mo new file mode 100644 index 0000000000000000000000000000000000000000..8a9a1a36f80c5821f56f6d7a71d0547490210bc5 GIT binary patch literal 1362 zcmbW0Pfr_17{;d!Z4?Jur6^Snjq(;X4Wt_X6GF*iEHE}H)fy0Xdqv~j@p|YoyPBP) z;d`__a}4*~l2d%_t+!q(^$YY1^wMW+1ExhBvf9;e-<5gkAf5vsflcrZ7=mq3gP(wJ!H>b;Cj1@z67e6PTl*hy7QFi*WB0%Z;BD|J z=+>)(b6^ep6}jJmtBC))#n@Ni!Qq@Ow71)>%idIq z<-%s7t<{}V_BtOAWSChT5kLN*=3%qy)O-K=^zQ=A&;K*lr6lFS{irK zym8`DL-b@!)#7s~oSX9+Pd7~h|AbFOZe?z6F!t5No7_D-8=ledl;S5sg_3Yz=)R}N z+t_AbNkf5z`>r#3QyQ&?uZ*N4l}V?5nB<0F-v3*E=fdrj8l?l3ideD^(x;Yhh%Crs eNXFti|GR&UvRoYtoE;lQsTrOH!?O@aDcQfwtAbwu literal 0 HcmV?d00001 diff --git a/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index 19a9fee85..257197bdf 100644 --- a/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -21,63 +21,63 @@ msgstr "" #: pydata_sphinx_theme/docs-navbar.html:9 msgid "Toggle navigation" -msgstr "" +msgstr "Basculer la navigation" #: pydata_sphinx_theme/icon-links.html:14 msgid "GitHub" -msgstr "" +msgstr "GitHub" #: pydata_sphinx_theme/icon-links.html:15 msgid "GitLab" -msgstr "" +msgstr "GitLab" #: pydata_sphinx_theme/icon-links.html:16 msgid "Bitbucket" -msgstr "" +msgstr "Bitbucket" #: pydata_sphinx_theme/icon-links.html:17 msgid "Twitter" -msgstr "" +msgstr "Twitter" #: pydata_sphinx_theme/layout.html:7 msgid "previous page" -msgstr "" +msgstr "page précédente" #: pydata_sphinx_theme/layout.html:10 msgid "next page" -msgstr "" +msgstr "page suivante" #: pydata_sphinx_theme/templates/copyright.html:3 #, python-format msgid "© Copyright %(copyright)s." -msgstr "" +msgstr "© Droit d'auteur %(copyright)s." #: pydata_sphinx_theme/templates/copyright.html:5 #, python-format msgid "© Copyright %(copyright)s." -msgstr "" +msgstr "© Droit d'auteur %(copyright)s." #: pydata_sphinx_theme/templates/edit-this-page.html:5 msgid "Edit this page" -msgstr "" +msgstr "Modifier cette page" #: pydata_sphinx_theme/templates/last-updated.html:2 #, python-format msgid "Last updated on %(last_updated)s." -msgstr "" +msgstr "Dernière mise à jour le %(last_updated)s." #: pydata_sphinx_theme/templates/page-toc.html:5 msgid "On this page" -msgstr "" +msgstr "Sur cette page" #: pydata_sphinx_theme/templates/sidebar-nav-bs.html:1 msgid "Main navigation" -msgstr "" +msgstr "Navigation principale" #: pydata_sphinx_theme/templates/sphinx-version.html:2 #, python-format msgid "" "Created using Sphinx " "%(sphinx_version)s." -msgstr "" - +msgstr "Créé à l'aide de Sphinx " +"%(sphinx_version)s." From 9bf81927b3f853ebb4e7f91cef971b4ae1a9b949 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 22 Apr 2021 21:32:41 -0400 Subject: [PATCH 10/17] i18n: Add page to user guide for internationalization --- docs/contributing.rst | 2 ++ docs/user_guide/i18n.rst | 61 +++++++++++++++++++++++++++++++++++++++ docs/user_guide/index.rst | 1 + 3 files changed, 64 insertions(+) create mode 100644 docs/user_guide/i18n.rst diff --git a/docs/contributing.rst b/docs/contributing.rst index bfc9e59f4..acc92387b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -284,6 +284,8 @@ 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 ===================== diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst new file mode 100644 index 000000000..f20539607 --- /dev/null +++ b/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 `__. To add another language, see :ref:`translating-the-theme`. + +The theme's :doc:`options` 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//", + "icon": "fab fa-github-square", + }, + ], + "external_links": [ + { + "name": _("link-one-name"), + "url": "https://", + }, + ], + } + + 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 diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index eeb675ce9..d6978a21c 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -10,3 +10,4 @@ User Guide configuring sections customizing + i18n From fb8f3c41a41d1bc244bc6efdb1d056f3df839c99 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Sat, 24 Apr 2021 16:30:30 -0400 Subject: [PATCH 11/17] Apply suggestions from code review Co-authored-by: Chris Holdgraf --- docs/user_guide/i18n.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index f20539607..e8fec733e 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -3,11 +3,11 @@ Internationalization This theme contains translatable strings. Most strings will automatically be translated if the language is `supported `__. To add another language, see :ref:`translating-the-theme`. -The theme's :doc:`options` 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. +The theme's :doc:`options` 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 of the message catalog for these strings. #. In your ``conf.py`` file: - .. code-block:: rst + .. code-block:: python import os.path from sphinx.locale import get_translation From ce6ddae5a768a01d215cd0984ad2dabfbfff4e49 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Sat, 24 Apr 2021 18:26:32 -0400 Subject: [PATCH 12/17] docs: Add to i18n contributing section --- docs/contributing.rst | 71 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 13 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index acc92387b..8527bfa8b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -284,30 +284,75 @@ 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: +Internationalization +==================== -Translating the theme -===================== +.. note:: -If any strings to be translated are added or changed, update the POT file: + Internationalization (I18N) and localization (L10N) is performed using `Gettext `__. Gettext reads a program's source and extracts text that has been marked as translatable, known as "source strings." Gettext uses three types of files: -.. code-block:: bash + PO file (``.po``) + A `Portable Object (PO) file `__ is made up of many entries, each entry holding the relation between a source string and its translation. The source string is introduced by the keyword ``msgid``, and the translation, by ``msgstr``. In a given PO file, all translations are expressed in a single target language. PO files are also known as message catalogs. + POT file (``.pot``) + A Portable Object Template (POT) file is the same as a PO file, except the translations are empty, so that it can be used as a template for new languages. + MO file (``.mo``) + A Machine Object (MO) file is a binary version of a PO file. PO files are compiled to MO files, which are required by Gettext. - python setup.py extract_messages + I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fulfill basics technical tasks. You might like: -and then update the PO files: + - `Internationalis(z)ing Code `__ by Computerphile on YouTube + - `Falsehoods Programmers Believe About Language `__ by Ben Hamill -.. code-block:: bash +.. _adding-natural-language-text: - python setup.py update_catalog +Adding natural language text +---------------------------- -To add a new language, add a PO file (replace ``LANGUAGE_CODE`` with the two-letter lowercase ISO 639-1 language code): +All natural language text must be marked as translatable, so that it can be extracted by Gettext and translated. -.. code-block:: bash +Jinja2 provides a ``trans`` block and a ``_()`` function to mark text as translatable. `Please refer to the Jinja2 documentation `__. Remember to `manually escape `__ variables if needed. + +Then, complete the steps for :ref:`changing-natural-language-text`. + +.. note:: + + When a variable is used in a source string (for example, ``{% trans %}Hello, {{ user }}!{% endtrans %}``), the value of the variable is not translated. If ``user`` is "John", it will be substituted as "John", not as "Иван" or "约翰". In other words, don't do ``{{ _(theme_search_bar_text) }}``. + +.. _changing-natural-language-text: + +Changing natural language text +------------------------------ + +#. Edit the natural language text as desired. + +#. Update the message catalog template (POT file): + + .. code-block:: bash + + python setup.py extract_messages + +#. Update the message catalogs (PO files): + + .. code-block:: bash + + python setup.py update_catalog + +.. _translating-the-theme: + +Translating the theme +--------------------- + +These steps use the Spanish language as an example. To translate the theme to another language, replace ``es`` with the language's two-letter lowercase `ISO 639-1 code `__. + +#. If the language's code matches no sub-directory of the `pydata_sphinx_theme/locale `__ directory, initialize the language's message catalog: + + .. code-block:: bash + + python setup.py init_catalog -l es - python setup.py init_catalog -l LANGUAGE_CODE +#. Edit the language's message catalog at ``pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po``. For each source string introduced by the ``msgid`` keyword, add its translation after the ``msgstr`` keyword. -If any PO files are updated, update the MO files: +#. Compile the message catalogs of every language: .. code-block:: bash From 069749d5b1f1a9ead7282c4e9a82ef15b33a7126 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 27 Apr 2021 15:22:37 -0400 Subject: [PATCH 13/17] docs: contributing: Remove paragraph that caused confusion --- docs/contributing.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 8527bfa8b..d0606ca82 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -314,10 +314,6 @@ Jinja2 provides a ``trans`` block and a ``_()`` function to mark text as transla Then, complete the steps for :ref:`changing-natural-language-text`. -.. note:: - - When a variable is used in a source string (for example, ``{% trans %}Hello, {{ user }}!{% endtrans %}``), the value of the variable is not translated. If ``user`` is "John", it will be substituted as "John", not as "Иван" or "约翰". In other words, don't do ``{{ _(theme_search_bar_text) }}``. - .. _changing-natural-language-text: Changing natural language text From ff6334b132211028870e58756767b0ba4d1f1231 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 27 Apr 2021 15:26:16 -0400 Subject: [PATCH 14/17] docs: contributing: Move i18n content out of note directive --- docs/contributing.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index d0606ca82..7c6c0e950 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -287,21 +287,19 @@ is required. The steps are roughly: Internationalization ==================== -.. note:: +Internationalization (I18N) and localization (L10N) is performed using `Gettext `__. Gettext reads a program's source and extracts text that has been marked as translatable, known as "source strings." Gettext uses three types of files: - Internationalization (I18N) and localization (L10N) is performed using `Gettext `__. Gettext reads a program's source and extracts text that has been marked as translatable, known as "source strings." Gettext uses three types of files: +PO file (``.po``) + A `Portable Object (PO) file `__ is made up of many entries, each entry holding the relation between a source string and its translation. The source string is introduced by the keyword ``msgid``, and the translation, by ``msgstr``. In a given PO file, all translations are expressed in a single target language. PO files are also known as message catalogs. +POT file (``.pot``) + A Portable Object Template (POT) file is the same as a PO file, except the translations are empty, so that it can be used as a template for new languages. +MO file (``.mo``) + A Machine Object (MO) file is a binary version of a PO file. PO files are compiled to MO files, which are required by Gettext. - PO file (``.po``) - A `Portable Object (PO) file `__ is made up of many entries, each entry holding the relation between a source string and its translation. The source string is introduced by the keyword ``msgid``, and the translation, by ``msgstr``. In a given PO file, all translations are expressed in a single target language. PO files are also known as message catalogs. - POT file (``.pot``) - A Portable Object Template (POT) file is the same as a PO file, except the translations are empty, so that it can be used as a template for new languages. - MO file (``.mo``) - A Machine Object (MO) file is a binary version of a PO file. PO files are compiled to MO files, which are required by Gettext. +I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fulfill basics technical tasks. You might like: - I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fulfill basics technical tasks. You might like: - - - `Internationalis(z)ing Code `__ by Computerphile on YouTube - - `Falsehoods Programmers Believe About Language `__ by Ben Hamill +- `Internationalis(z)ing Code `__ by Computerphile on YouTube +- `Falsehoods Programmers Believe About Language `__ by Ben Hamill .. _adding-natural-language-text: From df72f793c0a22404e8f2d64a118eeee1262e1be1 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 27 Apr 2021 15:26:50 -0400 Subject: [PATCH 15/17] docs: contributing: Clarify that compiling message catalogs is the same as creating MO files --- docs/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 7c6c0e950..73884eab8 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -338,7 +338,7 @@ Translating the theme These steps use the Spanish language as an example. To translate the theme to another language, replace ``es`` with the language's two-letter lowercase `ISO 639-1 code `__. -#. If the language's code matches no sub-directory of the `pydata_sphinx_theme/locale `__ directory, initialize the language's message catalog: +#. If the language's code matches no sub-directory of the `pydata_sphinx_theme/locale `__ directory, initialize the language's message catalog (PO file): .. code-block:: bash @@ -346,7 +346,7 @@ These steps use the Spanish language as an example. To translate the theme to an #. Edit the language's message catalog at ``pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po``. For each source string introduced by the ``msgid`` keyword, add its translation after the ``msgstr`` keyword. -#. Compile the message catalogs of every language: +#. Compile the message catalogs of every language. This creates or updates the MO files: .. code-block:: bash From 05d6effe93212f8b8143cd3b6dab75b9c400034c Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 27 Apr 2021 15:39:33 -0400 Subject: [PATCH 16/17] docs: contributing: Explain the comment lines in PO/POT files --- docs/contributing.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 73884eab8..079e85ab6 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -291,6 +291,8 @@ Internationalization (I18N) and localization (L10N) is performed using `Gettext PO file (``.po``) A `Portable Object (PO) file `__ is made up of many entries, each entry holding the relation between a source string and its translation. The source string is introduced by the keyword ``msgid``, and the translation, by ``msgstr``. In a given PO file, all translations are expressed in a single target language. PO files are also known as message catalogs. + + Entries begin with comments, on lines all starting with the character ``#``. Comments are created and maintained by Gettext. Comment lines starting with ``#:`` contain references to the program's source. These references allow a human translator to find the source strings in their original context. Comment lines starting with ``#,`` contain flags like ``python-format``, which indicates that the source string contains placeholders like ``%(copyright)s``. POT file (``.pot``) A Portable Object Template (POT) file is the same as a PO file, except the translations are empty, so that it can be used as a template for new languages. MO file (``.mo``) @@ -306,7 +308,7 @@ I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fu Adding natural language text ---------------------------- -All natural language text must be marked as translatable, so that it can be extracted by Gettext and translated. +All natural language text must be marked as translatable, so that it can be extracted by Gettext and translated by humans. Jinja2 provides a ``trans`` block and a ``_()`` function to mark text as translatable. `Please refer to the Jinja2 documentation `__. Remember to `manually escape `__ variables if needed. From babd3c39c55259aa0021115e54cd529d5baf37e3 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 27 Apr 2021 15:43:00 -0400 Subject: [PATCH 17/17] docs: contributing: Distinguish built-in and configurable strings Co-authored-by: Chris Holdgraf --- docs/user_guide/i18n.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index e8fec733e..e88fb9976 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -1,9 +1,17 @@ Internationalization ==================== -This theme contains translatable strings. Most strings will automatically be translated if the language is `supported `__. To add another language, see :ref:`translating-the-theme`. +This theme contains translatable strings. There are two kinds of strings contained in this theme, with slightly different steps to translate each. -The theme's :doc:`options` 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 of the message catalog for these strings. +**Built-in strings** are hard-coded in the theme's templates, and will automatically be translated if the language is `supported `__. To add another language, see :ref:`translating-the-theme`. + +**Configurable strings** are user-defined in ``html_theme_options`` (see :doc:`options` for examples). To translate these strings, see the section below. + +Translating configurable strings +-------------------------------- + +These are instructions for translating configurable strings (those that are customizable in ``html_theme_options``). +The 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 of the message catalog for these strings. #. In your ``conf.py`` file: