From f0f71d28242b12b7ba0c39d03266495efa17deab Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 16 Aug 2024 18:51:16 +0100 Subject: [PATCH 01/39] Add I18n commands to tox.ini --- tox.ini | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index b675d5a9a..602fba74d 100644 --- a/tox.ini +++ b/tox.ini @@ -129,4 +129,18 @@ deps = set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 commands = pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx - stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db \ No newline at end of file + stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db + +[testenv:i18n-extract] +description = "Extract translatable messages from the source code and generate a POT file" +extras = i18n +package = editable +commands = + pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/messages.pot --project=pydata-sphinx-theme --copyright-holder="PyData" + +[testenv:i18n-new-locale] +description = "Create a new locale based on our catalog template, e.g. `tox -e i18n-new-locale -- ss`" +extras = i18n +package = editable +commands = + pybabel init -i src/pydata_sphinx_theme/locale/messages.pot -d src/pydata_sphinx_theme/locale -l {posargs} \ No newline at end of file From d95545f9d56cb91ca9758d22b070331bc6e5b0c9 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 14:54:05 +0100 Subject: [PATCH 02/39] Add translation commands to tox.ini --- tox.ini | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/tox.ini b/tox.ini index 602fba74d..29203efd1 100644 --- a/tox.ini +++ b/tox.ini @@ -135,12 +135,40 @@ commands = description = "Extract translatable messages from the source code and generate a POT file" extras = i18n package = editable -commands = - pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/messages.pot --project=pydata-sphinx-theme --copyright-holder="PyData" +allowlist_externals = bash +commands = + # explicitly pass this as a bash command to set PST_VERSION + bash -c "PST_VERSION=$(pip show pydata-sphinx-theme | grep Version | awk -F': ' '{print $2}') && \ + pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --project=pydata-sphinx-theme --copyright-holder='PyData' --version=$PST_VERSION" +# add a new locale for translations based on the catalog template +# the locale needs to be given in the format of the language code +# --update-header-comment +# for example: `tox -e i18n-new-locale -- ss` [testenv:i18n-new-locale] -description = "Create a new locale based on our catalog template, e.g. `tox -e i18n-new-locale -- ss`" +description = "Create a new locale based on our catalog template" +extras = i18n +package = editable +commands = + pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs} + + +# update locales translation catalogues based on a POT template, if passed without +# arguments it will update all locales tox run -e i18n-update +# to update a single locale you can pass the locale code, for example: +# tox run -e i18n-update -- --locale=es +[testenv:i18n-update] +description = "Update the translations based on the latest POT file" +extras = i18n +package = editable +commands = + pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale --update-header-comment -D sphinx {posargs} + +# compile translation catalogs to binary MO files +# tox run -e i18n-compile +[testenv:i18n-compile] +description = "Compile translation catalogs to binary MO files" extras = i18n package = editable commands = - pybabel init -i src/pydata_sphinx_theme/locale/messages.pot -d src/pydata_sphinx_theme/locale -l {posargs} \ No newline at end of file + pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx \ No newline at end of file From 9e412fbf30f3fc2abf65266d383f22ffb3782b45 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:19:59 +0100 Subject: [PATCH 03/39] Remove gettext install --- .github/workflows/publish.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index f0f2999bc..032a15696 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -35,10 +35,6 @@ jobs: python-version: "3.9" pandoc: "False" - - name: "Install gettext for translations 🌐" - run: | - sudo apt-get install gettext - - name: "Build and inspect package 📦" uses: hynek/build-and-inspect-python-package@v2 id: baipp From 7dd05ed8fdae605b0a3a3fa7bcaf651dcfb04ff9 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:20:24 +0100 Subject: [PATCH 04/39] Update contribution guide - translation --- docs/community/topics/i18n.rst | 187 ++++++++++++++++++--------------- tox.ini | 1 + 2 files changed, 105 insertions(+), 83 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 68a8d0da7..d7a332cda 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -1,120 +1,110 @@ Internationalization ==================== -.. warning:: +We use `Gettext `__ message catalogs for the theme's internationalization (I18N) and localization (L10N) and `pybabel `__ to work with them. - This theme is still in the process of setting up internationalization. - Some of the text below may not yet be correct (for example, we do not yet have a ``locales/`` directory). - Follow these issues to track progress: +This section covers how to mark text as translatable, how to extract translatable text, and how to translate the theme. - - https://github.com/pydata/pydata-sphinx-theme/issues/1162 - - https://github.com/pydata/pydata-sphinx-theme/issues/257 +The general process for internationalizing and localizing the theme is as follows: -Internationalization (I18N) and localization (L10N) is performed using `Gettext `__. +#. Mark natural language text as translatable. +#. Extract translatable text to a message catalog template ``POT`` (``PO`` template file). +#. Make a copy of the ``POT`` file for each language (locale) you want to translate (or update existing templates). +#. Compile the message catalogs to binary ``MO`` files. +#. Translate the message catalogs. -Types of files --------------- -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: +.. _adding-translatable-text: -PO file (``.po``) - A `Portable Object (PO) file `__ is made up of many entries. - Each entry holds the relation between a source string and its translation. - ``msgid`` contains the **source string**, and ``msgstr`` contains the **translation**. - In a given PO file, all translations are expressed in a single target language. - PO files are also known as "message catalogs". +Marking natural language text as translatable +----------------------------------------------- - Entries begin with comments, on lines 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``) - 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. +All natural language text in the theme's components and layouts must be marked as translatable so that it can be extracted and translated. +For example, if you add a button with the text "Next page", you will need to mark this text as translatable. -.. _adding-natural-language-text: +To do so, you can use the Jinja2 ``trans`` block and/or a ``_()`` function to mark text as translatable in corresponding ``HTML`` templates (located in the ``src/pydata_sphinx_theme/theme/`` directory). +`Please refer to the Jinja2 documentation `__. +Remember to `manually escape variables `__ if needed. -Mark natural language text as translateable -------------------------------------------- +For example, to mark the text "Next page" as translatable, you would write: -All natural language text must be marked as translatable, so that it can be extracted by Gettext and translated by humans. +.. code-block:: jinja + + -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. -Any text that is marked in this way will be discoverable by ``gettext`` and used to generate ``.po`` files (see below for information). -Once you've marked text as translateable, complete the steps for :ref:`changing-natural-language-text`. +Any text that is marked in this way will be discoverable by ``pybabel`` and used to generate the ``PO`` files. +Once you've marked the text as translatable, complete the steps outlined in :ref:`changing-natural-language-text`. .. _changing-natural-language-text: -Add or change natural language text ------------------------------------ +Adding or changing natural language text +----------------------------------------- -These steps cover how to add or change text that has been marked as translateable. +If you add or change natural language text in the theme, you must update the message catalogs to include the new or updated text. Follow these steps: -#. Edit the natural language text as desired. - Ensure that it is {ref}`marked as translateable `. +#. Edit the natural language text and ensure it is :ref:`marked as translatable `. -#. Generate/update the message catalog template (``POT`` file) with `the PyBabel extract command `__: +#. Generate/update the message catalog template (``POT`` file): .. code-block:: bash + + tox run -e i18n-extract - pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot -k '_ __ l_ lazy_gettext' - - **To run this in ``.nox``**: ``nox -s translate -- extract``. - -#. Update the message catalogs (``PO`` files) with `the PyBabel update command `__: +#. Update the message catalogs (``PO`` files) for the existing locales: .. code-block:: bash - pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx - - **To run this in ``.nox``**: ``nox -s translate -- update``. + tox run -e i18n-update +This will update the translation files with new information about the position and text of the language you have modified. -This will update these files with new information about the position and text of the language you have modified. +If you *only* change non-translatable text (like HTML markup), the ``extract`` and ``update`` commands will only update the +positions (line numbers) of the translatable strings. +Updating positions is optional - the line numbers are to inform the human translator, not to perform the translation. -If you *only* change non-translatable text (like HTML markup), the `extract` and `update` commands will only update the positions (line numbers) of the translatable strings. Updating positions is optional - the line numbers are to inform the human translator, not to perform the translation. +If you change translatable strings, the ``extract`` command will extract the new or updated strings to the ``POT`` file, +and the ``update`` command will try to fuzzy match the new or updated strings with existing translations in the ``PO`` files. +If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry. +Otherwise, it will add a new translation entry. -If you change translatable strings, the `extract` command will extract the new or updated strings to the POT file, and the `update` command will try to fuzzy match the new or updated strings with existing translations in the PO files. -If there is a fuzzy match, a comment like `#, fuzzy` is added before the matched entry. -Otherwise, a new entry is added and needs to be translated. +.. _adding-new-language: +Adding a new language +---------------------- -.. _translating-the-theme: +The list of currently supported languages is available in the ``src/pydata_sphinx_theme/locale`` directory. -Add translations to translateable text --------------------------------------- +To add a new language, follow these steps: -Once text has been marked as translateable, and ``PO`` files have been generated for it, we may add translations for new languages for the phrase. -This section covers how to do so. +#. Identify the `ISO 639-1 code `__ for the new language. -.. note:: - - 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 (PO file) with `PyBabel init `__: +#. Make a copy of the ``POT`` file for this new language: .. code-block:: bash + + # for example, to add Quechua (ISO 639-1 code: qu) + tox -e i18n-new-locale -- qu - pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx -l es - **To run this in ``.nox``**: ``nox -s translate -- init es`` +.. _translating-the-theme: -#. 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. +Translating the theme +--------------------- -#. Compile the message catalogs of every language. This creates or updates the MO files with `PyBabel compile `__: +We manage translations on the `PyData Sphinx Theme project on Transifex `__. - .. code-block:: bash +To contribute translations, follow these steps: - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx +#. Sign up for a `Transifex account `__. +#. Join the `PyData Sphinx Theme project `__. +#. Select the language you want to translate. If the language you are looking for is not listed, you can `open an issue + on GitHub to request it `__. +#. Now you are ready to start translating the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. - **To run this in ``.nox``**: ``nox -s translate -- compile``. +Once you have completed your translation, the PyData Sphinx Theme maintainers will review and approve it. Translation tips ---------------- @@ -125,26 +115,57 @@ Translate phrases, not words Full sentences and clauses must always be a single translatable string. Otherwise, you can get ``next page`` translated as ``suivant page`` instead of as ``page suivante``, etc. -Deal with variables and markup in translations +Dealing with variables and markup in translations ````````````````````````````````````````````````````````````` If a variable (like the ``edit_page_provider_name`` theme option) is used as part of a phrase, it must be included within the translatable string. -Otherwise, the word order in other languages can be incorrect. -In a Jinja template, simply surround the translatable string with ``{% trans variable=variable %}`` and ``{% endtrans %}}`. -For example: ``{% trans provider=provider %}Edit on {{ provider }}{% endtrans %}`` -The translatable string is extracted as the Python format string ``Edit on %(provider)s``. -This is so that the same translatable string can be used in both Python code and Jinja templates. -It is the translator's responsibility to use ``%(provider)s`` verbatim in the translation. - -If a non-translatable word or token (like HTML markup) is used as part of a phrase, it must also be included within the translatable string. -For example: ``{% trans theme_version=theme_version|e %}Built with the PyData Sphinx Theme {{ theme_version }}.{% endtrans %}`` +Otherwise, the word order in other languages can be incorrect. In a Jinja template, simply surround the translatable string with ``{% trans variable=variable %}`` and ``{% endtrans %}}``. For example: + +.. code-block:: jinja + + {% trans provider=provider %}Edit on {{ provider }}{% endtrans %} + +The translatable string is extracted as the Python format string ``Edit on %(provider)s``. This is so that the same translatable string can be used in both Python code and Jinja templates. It is the translator's responsibility to use ``%(provider)s`` verbatim in the translation. + +If a non-translatable word or token (like HTML markup) is used as part of a phrase, it must also be included within the translatable string. For example: + +.. code-block:: jinja + + {% trans theme_version=theme_version|e %} + Built with the PyData Sphinx Theme {{ theme_version }}. + {% endtrans %} + It is the translator's responsibility to use the HTML markup verbatim in the translation. +Translation files +------------------ + +Gettext and pybabel read a program's source and extract text that has been marked as translatable, known as "source strings". + +There are three types of files used in the translation process: + +PO file (``.po``) + A `Portable Object (PO) file `__ which contains all the translatable entries. + Each entry holds the relation between a source string and its translation. + ``msgid`` contains the **source string**, and ``msgstr`` contains the **translation**. + 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 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 that 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 into MO files. + References ---------- -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 basic technical tasks. You might like: - `Internationalis(z)ing Code `__ by Computerphile on YouTube - `Falsehoods Programmers Believe About Language `__ by Ben Hamill diff --git a/tox.ini b/tox.ini index 29203efd1..258e7317e 100644 --- a/tox.ini +++ b/tox.ini @@ -131,6 +131,7 @@ commands = pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db +# tox run -e i18n-extract [testenv:i18n-extract] description = "Extract translatable messages from the source code and generate a POT file" extras = i18n From 0677b17b1a4e4695c575bf8ea61ef10ecc0c641a Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:20:31 +0100 Subject: [PATCH 05/39] Update user guide - translation --- docs/user_guide/i18n.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 7d6756aef..a4b935046 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -4,19 +4,19 @@ Internationalization This theme contains translatable strings. There are two kinds of strings in this theme, with different steps to translate each. -**Built-in strings** are hard-coded in the theme's templates. -They will automatically be translated if the language is `supported `__. -To add another language, see :ref:`translating-the-theme`. +* **Built-in strings** are hard-coded in the theme's templates. They will be automatically translated if the language is `supported `__. To add another language, refer to the :ref:`translating-the-theme` and :ref:`adding-new-language` sections in the documentation. -**Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples). -To translate these strings, see the section below. +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). Translating configurable strings -------------------------------- -These instructions are for translating configurable strings (those that are customizable in ``html_theme_options``). +These instructions are for translating configurable strings (those that are customizable in ``html_theme_options`` within +the `config.py` file). -These 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. +These instructions assume that you store your translations in a ``locale`` directory under your documentation directory and that you want to use ``messages`` as the name of the message catalog for these strings. + +Note you will also need to install `pybabel `__ to handle your documentation translations. #. In your ``conf.py`` file: @@ -25,7 +25,7 @@ These instructions assume that you store your translations in a ``locale`` direc import os.path from sphinx.locale import get_translation - catalog = "theme" + catalog = "messages" _ = get_translation(catalog) html_theme_options = { @@ -57,13 +57,15 @@ These instructions assume that you store your translations in a ``locale`` direc .. code-block:: bash - pybabel extract . -o locale/theme.pot + pybabel extract . -o locale/messages.pot -#. Create a message catalog (changing the ``--locale`` option as desired): +#. Create a message catalog by specifying the `ISO 639-1 code `__ for the new language (using the ``--locale`` flag): .. code-block:: bash - pybabel init --input-file=locale/theme.pot --domain=theme --output-dir=locale --locale=fr + # for example, to add French (ISO 639-1 code: fr) + pybabel init --input-file=locale/messages.pot --domain=messages --output-dir=locale --locale=fr + #. Translate the message catalog by editing the file. @@ -71,4 +73,4 @@ These instructions assume that you store your translations in a ``locale`` direc .. code-block:: bash - pybabel compile --directory=locale --domain=theme + pybabel compile --directory=locale --domain=messages From 256bcd055def4a484b7d5eee78a2e5eb66b0a695 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:21:13 +0100 Subject: [PATCH 06/39] :fire: Remove noxfile --- noxfile.py | 239 ----------------------------------------------------- 1 file changed, 239 deletions(-) delete mode 100644 noxfile.py diff --git a/noxfile.py b/noxfile.py deleted file mode 100644 index c4b2b0fdf..000000000 --- a/noxfile.py +++ /dev/null @@ -1,239 +0,0 @@ -"""Automatically build our documentation or run tests. - -Environments are re-used by default. -Re-install the environment from scratch: - - nox -s docs -- -r -""" - -import os -import shutil as sh -import tempfile -from pathlib import Path -from shlex import split -from textwrap import dedent - -import nox - -nox.options.reuse_existing_virtualenvs = True -ROOT = Path(__file__).parent - - -def _should_install(session: nox.Session) -> bool: - """Decide if we should install an environment or if it already exists. - - This speeds up the local install considerably because building the wheel - for this package takes some time. - - We assume that if `sphinx-build` is in the bin/ path, the environment is - installed. - - Parameter: - session: the current nox session - """ - if session.bin_paths is None: - session.log("Running with `--no-venv` so don't install anything...") - return False - bin_files = list(Path(session.bin).glob("*")) - sphinx_is_installed = any("sphinx-build" in ii.name for ii in bin_files) - force_reinstall = "reinstall" in session.posargs or "-r" in session.posargs - should_install = not sphinx_is_installed or force_reinstall - if should_install: - session.log("Installing fresh environment...") - else: - session.log("Skipping environment install...") - return should_install - - -@nox.session(reuse_venv=True) -def lint(session: nox.Session) -> None: - """Check the themes pre-commit before any other session.""" - session.install("pre-commit") - session.run("pre-commit", "run", "-a") - - -@nox.session() -def compile(session: nox.Session) -> None: - """Compile the theme's web assets with sphinx-theme-builder.""" - if _should_install(session): - session.install("-e", ".") - session.install("sphinx-theme-builder[cli]") - - session.run("stb", "compile") - - -@nox.session() -def docs(session: nox.Session) -> None: - """Build the documentation and place in docs/_build/html. Use --no-compile to skip compilation.""" - if _should_install(session): - session.install("-e", ".[doc]") - session.install("sphinx-theme-builder[cli]") - if "no-compile" not in session.posargs: - session.run("stb", "compile") - session.run( - "sphinx-build", - "-b=html", - "docs/", - "docs/_build/html", - "-v", - "-w", - "warnings.txt", - # suppress Py3.11's new "can't debug frozen modules" warning - env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"), - ) - session.run("python", "tests/utils/check_warnings.py") - - -@nox.session(name="docs-live") -def docs_live(session: nox.Session) -> None: - """Build the docs with a live server that re-loads as you make changes.""" - session.run(*split("pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx")) - if _should_install(session): - session.install("-e", ".[doc]") - # quick hack to get the patched version of stb - need to remove once a stb release is cut - session.install( - "sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b" - ) - session.run( - "stb", - "serve", - "docs", - "--open-browser", - r"--re-ignore=locale|api|_build|\.jupyterlite\.doit\.db", - # suppress Py3.11's new "can't debug frozen modules" warning - env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"), - ) - - -@nox.session() -def test(session: nox.Session) -> None: - """Run the test suite.""" - if _should_install(session): - session.install("-e", ".[test]") - session.run(*split("pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx")) - session.run("pytest", "-m", "not a11y", *session.posargs) - - -@nox.session() -def a11y(session: nox.Session) -> None: - """Run the accessibility test suite only.""" - if _should_install(session): - session.install("-e", ".[test, a11y]") - # Install the drivers that Playwright needs to control the browsers. - if os.environ.get("CI") or os.environ.get("GITPOD_WORKSPACE_ID"): - # CI and other cloud environments are potentially missing system - # dependencies, so we tell Playwright to also install the system - # dependencies - session.run("playwright", "install", "--with-deps") - else: - # But most dev environments have the needed system dependencies - session.run("playwright", "install") - # Build the docs so we can run accessibility tests against them. - session.run("nox", "-s", "docs") - # The next step would be to open a server to the docs for Playwright, but - # that is done in the test file, along with the accessibility checks. - session.run("pytest", "-m", "a11y", *session.posargs) - - -@nox.session(name="test-sphinx") -@nox.parametrize("sphinx", ["4", "5", "6"]) -def test_sphinx(session: nox.Session, sphinx: int) -> None: - """Run the test suite with a specific version of Sphinx.""" - if _should_install(session): - session.install("-e", ".[test]") - session.install(f"sphinx=={sphinx}") - session.run("pytest", *session.posargs) - - -@nox.session() -def translate(session: nox.Session) -> None: - """Translation commands. Available commands after `--` : extract, update, compile, init.""" - # get the command from posargs, default to "update" - pybabel_cmd, found = ("update", False) - for c in ["extract", "update", "compile", "init"]: - if c in session.posargs: - pybabel_cmd, found = (c, True) - - if found is False: - print( - "No translate command found. Use like: `nox -s translate -- COMMAND`." - "\ndefaulting to `update`" - "\nAvailable commands: extract, update, compile, init" - ) - - # get the language from parameters default to en. - # it can be deceiving but we don't have a table of accepted languages yet - lan = "en" if len(session.posargs) < 2 else session.posargs[-1] - - # get the path to the differnet local related pieces - locale_dir = str(ROOT / "src" / "pydata_sphinx_theme" / "locale") - babel_cfg = str(ROOT / "babel.cfg") - pot_file = str(locale_dir / "sphinx.pot") - - # install deps - session.install("Babel") - - # build the command from the parameters - cmd = ["pybabel", pybabel_cmd] - - if pybabel_cmd == "extract": - cmd += [ROOT, "-F", babel_cfg, "-o", pot_file, "-k", "_ __ l_ lazy_gettext"] - - elif pybabel_cmd == "update": - cmd += ["-i", pot_file, "-d", locale_dir, "-D", "sphinx"] - - elif pybabel_cmd == "compile": - cmd += ["-d", locale_dir, "-D", "sphinx"] - - elif pybabel_cmd == "init": - cmd += ["-i", pot_file, "-d", locale_dir, "-D", "sphinx", "-l", lan] - - session.run(cmd) - - -@nox.session() -def profile(session: nox.Session) -> None: - """Generate a profile chart with py-spy. The chart will be placed at profile.svg.""" - if _should_install(session): - session.install("-e", ".[test]") - session.install("py-spy") - - with tempfile.TemporaryDirectory() as tmpdir: - # Copy over our base test site to the temporary folder - path_base = Path("tests/sites/base/") - path_tmp = Path(tmpdir) / path_base - sh.copytree(path_base, path_tmp) - - # Add a bunch of extra files to increase the build length - index = path_tmp / "index.rst" - text = index.read_text() - text += dedent( - """ - .. toctree:: - :glob: - - many/* - """ - ) - index.write_text(text) - (path_tmp / "many").mkdir() - - # Create a bunch of empty pages to slow the build - n_extra_pages = 50 - for ii in range(n_extra_pages): - (path_tmp / "many" / f"{ii}.rst").write_text("Test\n====\n\nbody\n") - - if "-o" in session.posargs: - output = session.posargs[session.posargs.index("-o") + 1] - else: - output = "profile.svg" - - # Specify our output directory - path_tmp_out = path_tmp / "_build" - - # Profile the build - print(f"Profiling build with {n_extra_pages} pages with py-spy...") - session.run( - *f"py-spy record -o {output} -- sphinx-build {path_tmp} {path_tmp_out}".split() - ) - print(f"py-spy profiler output at this file: {output}") From 16543a27e4a3bf26a1edbc8468c3ef928960a195 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:23:56 +0100 Subject: [PATCH 07/39] :fire: Remove nox docs --- docs/community/topics/nox.md | 36 ------------------------------------ 1 file changed, 36 deletions(-) delete mode 100644 docs/community/topics/nox.md diff --git a/docs/community/topics/nox.md b/docs/community/topics/nox.md deleted file mode 100644 index d62e5be57..000000000 --- a/docs/community/topics/nox.md +++ /dev/null @@ -1,36 +0,0 @@ -# Using `nox` - -Here are a few extra tips for using `nox`. - -:::{seealso} -The [`nox` command line documentation](https://nox.thea.codes/en/stable/usage.html) has a lot of helpful tips for extra functionality you can enable with the CLI. -::: - -## Re-install dependencies - -To re-execute the installation commands, use this pattern: - -```console -$ nox -s docs -- reinstall -``` - -Or to completely remove the environment generated by `nox` and start from scratch: - -```console -$ rm -rf .nox/docs -``` - -## Use `nox` with your global environment - -If you'd like to use `nox` with your **global** environment (the one from which you are calling `nox`), you can do so with: - -```console -$ nox --force-venv-backend none - -# alternatively: -$ nox --no-venv -``` - -Using `none` will re-use your current global environment. -See -[the nox documentation](https://nox.thea.codes/en/stable/usage.html#forcing-the-sessions-backend) for more details. From 54449320c9fdcb97c0446597140735d8a299350b Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:26:03 +0100 Subject: [PATCH 08/39] Update theme's POT file --- src/pydata_sphinx_theme/locale/sphinx.pot | 35 ++++++++++++----------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/sphinx.pot b/src/pydata_sphinx_theme/locale/sphinx.pot index 11c7f142d..d35cde673 100644 --- a/src/pydata_sphinx_theme/locale/sphinx.pot +++ b/src/pydata_sphinx_theme/locale/sphinx.pot @@ -1,41 +1,42 @@ -# Translations template for PROJECT. -# Copyright (C) 2024 ORGANIZATION -# This file is distributed under the same license as the PROJECT project. +# Translations template for pydata-sphinx-theme. +# Copyright (C) 2024 PyData +# This file is distributed under the same license as the pydata-sphinx-theme +# project. # FIRST AUTHOR , 2024. # #, fuzzy msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" +"Project-Id-Version: pydata-sphinx-theme 0.15.4.dev0\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-05-10 18:43+0200\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\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.13.0\n" +"Generated-By: Babel 2.16.0\n" -#: docs/conf.py:94 +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -49,17 +50,17 @@ msgstr "" msgid "Please activate JavaScript to enable the search functionality." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 @@ -134,7 +135,7 @@ msgid "" "%(sphinx_version)s." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "" From e9b8d72b6d2d9412f878d3ffd10915a0d23f9e65 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 17:34:40 +0100 Subject: [PATCH 09/39] Update locale files --- .../locale/ca/LC_MESSAGES/sphinx.po | 56 ++++++++++------- .../locale/cs/LC_MESSAGES/sphinx.po | 52 ++++++++++------ .../locale/en/LC_MESSAGES/sphinx.po | 44 +++++++++----- .../locale/es/LC_MESSAGES/sphinx.po | 60 +++++++++++-------- .../locale/fr/LC_MESSAGES/sphinx.po | 56 ++++++++++------- .../locale/it/LC_MESSAGES/sphinx.po | 58 +++++++++++------- .../locale/ru/LC_MESSAGES/sphinx.po | 53 ++++++++++------ .../locale/zh/LC_MESSAGES/sphinx.po | 58 +++++++++++------- tox.ini | 48 +++++++-------- 9 files changed, 300 insertions(+), 185 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po index 7c70e77c1..801b78ae8 100644 --- a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po @@ -1,34 +1,44 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Catalan translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. -# -# Translators: -# Cristhian Rivera, 2024 -# Oriol Abril-Pla , 2024 -# +# FIRST AUTHOR , 2024. +# +#, fuzzy msgid "" msgstr "" - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ca\n" +"Language-Team: ca \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.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "Fes clic per a desplegar" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Fes clic per a replegar" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Salta al contingut principal" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Torna a l'inici" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -42,18 +52,18 @@ msgstr "Error" msgid "Please activate JavaScript to enable the search functionality." msgstr "Activeu JavaScript per habilitar la funcionalitat de cerca." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Ruta de navegació" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Inici" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -129,7 +139,7 @@ msgstr "" "Creada amb Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "clar/fosc" @@ -173,3 +183,7 @@ msgstr "Navegació del lloc" #~ msgid "Site Navigation" #~ msgstr "Navegació del lloc" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index 91690218d..88a4ed473 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -1,33 +1,44 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Czech translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. +# FIRST AUTHOR , 2024. # -# Translators: -# Jan Breuer , 2024 +#, fuzzy msgid "" msgstr "" - - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: cs\n" +"Language-Team: cs \n" +"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Přejít k hlavnímu obsahu" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Zpět na začátek" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,18 +52,18 @@ msgstr "Chyba" msgid "Please activate JavaScript to enable the search functionality." msgstr "Aktivujte prosím JavaScript, abyste umožnili vyhledávání." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Struktura" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Domů" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -128,7 +139,7 @@ msgstr "" "Vytvořeno pomocí Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "světlý/tmavý" @@ -171,3 +182,6 @@ msgstr "Navigace na stránce" #~ msgid "Twitter" #~ msgstr "Twitter" +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po index 093a8c841..4ebdd38fd 100644 --- a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po @@ -1,31 +1,44 @@ # English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. +# FIRST AUTHOR , 2024. # +#, fuzzy msgid "" msgstr "" - - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: en\n" +"Language-Team: en \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.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -39,17 +52,17 @@ msgstr "" msgid "Please activate JavaScript to enable the search functionality." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 #, python-format -msgid "© Copyright %(copyright)s." +msgid "Copyright %(copyright)s" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 @@ -124,7 +137,7 @@ msgid "" "%(sphinx_version)s." msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "" @@ -166,3 +179,6 @@ msgstr "" #~ msgid "Site Navigation" #~ msgstr "" +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "" + diff --git a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po index 045c3d408..962974642 100644 --- a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po @@ -1,35 +1,44 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Spanish translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. -# -# Translators: -# Rambaud Pierrick , 2023 -# Cristhian Rivera, 2024 -# Felipe Moreno, 2024 -# +# FIRST AUTHOR , 2024. +# +#, fuzzy msgid "" msgstr "" - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "Haga clic para ampliar" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Haga clic para colapsar" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Saltar al contenido principal" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Volver arriba" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,21 +50,20 @@ msgstr "Error" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:9 msgid "Please activate JavaScript to enable the search functionality." -msgstr "" -"Por favor, active JavaScript para habilitar la funcionalidad de búsqueda." +msgstr "Por favor, active JavaScript para habilitar la funcionalidad de búsqueda." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Miga de pan" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Inicio" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -131,7 +139,7 @@ msgstr "" "Creado usando Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "claro/oscuro" @@ -175,3 +183,7 @@ msgstr "Navegación del sitio" #~ msgid "Site Navigation" #~ msgstr "Navegación del sitio" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index edc7cd46f..60cd6aa48 100644 --- a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -1,34 +1,44 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# French translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. -# -# Translators: -# Denis Bitouzé , 2024 -# Rambaud Pierrick , 2024 -# +# FIRST AUTHOR , 2024. +# +#, fuzzy msgid "" msgstr "" - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "Cliquez pour développer" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Cliquer pour réduire" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Passer au contenu principal" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Haut de page" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -42,18 +52,18 @@ msgstr "Erreur" msgid "Please activate JavaScript to enable the search functionality." msgstr "Veuillez activer le JavaScript pour que la recherche fonctionne." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Fil d'Ariane" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Accueil" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -129,7 +139,7 @@ msgstr "" "Créé en utilisant Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "clair/sombre" @@ -173,3 +183,7 @@ msgstr "Navigation dans le site" #~ msgid "Site Navigation" #~ msgstr "Navigation du site" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index e3727f43b..eea3daeda 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -1,33 +1,44 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Italian translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. -# -# Translators: -# Stefano David, 2024 -# +# FIRST AUTHOR , 2024. +# +#, fuzzy msgid "" msgstr "" - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: it\n" +"Language-Team: it \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.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "Fai click per espandere" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "Fai click per nascondere" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Passa ai contenuti principali" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "Torna in alto" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -39,21 +50,20 @@ msgstr "Errore" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:9 msgid "Please activate JavaScript to enable the search functionality." -msgstr "" -"Per favore attiva JavaScpript per abilitare la funzionalità di ricerca." +msgstr "Per favore attiva JavaScpript per abilitare la funzionalità di ricerca." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Breadcrumb" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Pagina iniziale" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -129,7 +139,7 @@ msgstr "" "Creato con Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "chiaro/scuro" @@ -173,3 +183,7 @@ msgstr "Navigazione del sito" #~ msgid "Site Navigation" #~ msgstr "Navigazione del sito" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po index de1ba6d09..1bf8e4f82 100644 --- a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po @@ -1,33 +1,45 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Russian translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. +# FIRST AUTHOR , 2024. # -# Translators: -# Rambaud Pierrick , 2023 +#, fuzzy msgid "" msgstr "" - - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ru\n" +"Language-Team: ru \n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "Перейти к основному содержанию" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,18 +53,18 @@ msgstr "Ошибка" msgid "Please activate JavaScript to enable the search functionality." msgstr "Активируйте JavaScript, чтобы включить функцию поиска." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Хлебная крошка" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "Главная" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Копирайт %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Копирайт %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -128,7 +140,7 @@ msgstr "" "Создано с помощью Sphinx " "%(sphinx_version)s." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "светлая/темная" @@ -171,3 +183,6 @@ msgstr "Навигация по сайту" #~ msgid "Twitter" #~ msgstr "Twitter" +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Копирайт %(copyright)s." + diff --git a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po index 45326b86d..818ed4f61 100644 --- a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po @@ -1,33 +1,44 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2023 PyData developers +# Chinese translations for pydata-sphinx-theme. +# Copyright (C) 2024 PyData # This file is distributed under the same license as the pydata-sphinx-theme # project. -# -# Translators: -# 温欣, 2024 -# +# FIRST AUTHOR , 2024. +# +#, fuzzy msgid "" msgstr "" - -#: docs/conf.py:94 +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh\n" +"Language-Team: zh \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + +#: docs/conf.py:108 msgid "Click to expand" msgstr "展开" -#: docs/conf.py:95 +#: docs/conf.py:109 msgid "Click to collapse" msgstr "收缩" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:39 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:48 msgid "Skip to main content" msgstr "跳转至主要内容" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:51 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html:60 msgid "Back to top" msgstr "回到顶部" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:5 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:7 -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:6 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html:8 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html:3 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:5 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:28 msgid "Search" @@ -41,18 +52,18 @@ msgstr "错误" msgid "Please activate JavaScript to enable the search functionality." msgstr "请启用 JavaScript 以启用搜索功能。" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:13 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6 msgid "Breadcrumb" msgstr "Breadcrumb" -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:17 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:10 msgid "Home" msgstr "初始页面" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, python-format -msgid "© Copyright %(copyright)s." -msgstr "© Copyright %(copyright)s." +#, fuzzy, python-format +msgid "Copyright %(copyright)s" +msgstr "© Copyright %(copyright)s." #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:8 #, python-format @@ -125,9 +136,10 @@ msgid "" "Created using Sphinx " "%(sphinx_version)s." msgstr "" -"使用 Sphinx %(sphinx_version)s创建." +"使用 Sphinx " +"%(sphinx_version)s创建." -#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:5 +#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html:3 msgid "light/dark" msgstr "亮色/暗色" @@ -171,3 +183,7 @@ msgstr "网页导航" #~ msgid "Site Navigation" #~ msgstr "网址导航" + +#~ msgid "© Copyright %(copyright)s." +#~ msgstr "© Copyright %(copyright)s." + diff --git a/tox.ini b/tox.ini index 258e7317e..4aed4abd8 100644 --- a/tox.ini +++ b/tox.ini @@ -10,10 +10,10 @@ env_list = py312-tests, a11y-tests -# convenience label for running tests with a given Python version, aimed at +# convenience label for running tests with a given Python version, aimed at # helping contributors run tests locally # tox run -m tests -labels = +labels = tests = compile, py312-tests a11y = compile, py312-docs, a11y-tests @@ -25,14 +25,14 @@ deps = lint: pre-commit compile: sphinx-theme-builder[cli] profile-docs: py-spy -extras = +extras = {docs-no-checks, docs-linkcheck, profile-docs}: doc -skip_install = +skip_install = lint: true # do not need to install to lint profile-docs: true # avoids issues with py-spy and setting the git repo compile: false package = editable -commands = +commands = lint: pre-commit run -a compile: stb compile # can substitute the target directory @@ -41,12 +41,12 @@ commands = # example tox run -e py39-profile-docs -- -o profile.svg -n 100 profile-docs: python ./tools/profile.py {posargs} -# tests can be ran with or without coverage (see examples below), -# it is recommended to run compile before running tests (see examples below), -# tox run -e compile,py39-tests -# if you want to skip the assets compilation step you can run the tests without +# tests can be ran with or without coverage (see examples below), +# it is recommended to run compile before running tests (see examples below), +# tox run -e compile,py39-tests +# if you want to skip the assets compilation step you can run the tests without #`compile`, for example: -# tox run -e py39-tests +# tox run -e py39-tests # run tests with a specific Sphinx version # tox run -e compile,py39-sphinx61-tests # run tests without coverage @@ -57,12 +57,12 @@ description = "Run tests Python and Sphinx versions. If a Sphinx version is spec package = editable extras = test # install dependencies - defined in pyproject.toml -deps = +deps = coverage[toml] py39-sphinx61-tests: sphinx~=6.1.0 py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master depends = compile -commands = +commands = py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs} py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs} @@ -73,16 +73,16 @@ commands = description = run accessibility tests with Playwright and axe-core base_python = py312 # keep in sync with tests.yml pass_env = GITHUB_ACTIONS # so we can check if this is run on GitHub Actions -extras = +extras = test a11y -depends = - compile, +depends = + compile, py312-docs allowlist_externals= playwright bash -commands = +commands = bash -c 'if [[ "{env:GITHUB_ACTIONS:}" == "true" ]]; then playwright install --with-deps; else playwright install; fi' pytest -m "a11y" {posargs} @@ -96,7 +96,7 @@ description = build the documentation and place in docs/_build/html set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 # keep this in sync across all docs environments extras = {[testenv:docs-no-checks]extras} -deps = +deps = py39-sphinx61-docs: sphinx~=6.1.0 commands = sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} @@ -119,15 +119,15 @@ commands = [testenv:docs-live] description = "Build and serve the documentation with live-reload" -extras = +extras = dev i18n package = editable -deps = +deps = sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b # suppress Py3.11's new "can't debug frozen modules" warning set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 -commands = +commands = pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db @@ -150,7 +150,7 @@ commands = description = "Create a new locale based on our catalog template" extras = i18n package = editable -commands = +commands = pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs} @@ -162,8 +162,8 @@ commands = description = "Update the translations based on the latest POT file" extras = i18n package = editable -commands = - pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale --update-header-comment -D sphinx {posargs} +commands = + pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs} # compile translation catalogs to binary MO files # tox run -e i18n-compile @@ -171,5 +171,5 @@ commands = description = "Compile translation catalogs to binary MO files" extras = i18n package = editable -commands = +commands = pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx \ No newline at end of file From 8e61d5ccd23c8aab38988df50fc1a399dd5907a6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:42:31 +0000 Subject: [PATCH 10/39] [pre-commit.ci] Automatic linting and formatting fixes --- .../locale/ca/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/en/LC_MESSAGES/sphinx.po | 12 ------------ 2 files changed, 24 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po index 801b78ae8..aa671f9c2 100644 --- a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po @@ -7,18 +7,6 @@ #, fuzzy msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ca\n" -"Language-Team: ca \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po index 4ebdd38fd..f23de4e42 100644 --- a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po @@ -7,18 +7,6 @@ #, fuzzy msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: en\n" -"Language-Team: en \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" From da59b0cbf33de2f5e773ce40427d29f5ab442478 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 19 Aug 2024 18:11:56 +0100 Subject: [PATCH 11/39] Update locale files --- src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po | 2 +- src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po | 2 +- src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po | 2 +- src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po | 2 +- src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po | 2 +- src/pydata_sphinx_theme/locale/sphinx.pot | 2 +- src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index 88a4ed473..98dbff157 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: cs\n" diff --git a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po index 962974642..a8f373e4e 100644 --- a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: es\n" diff --git a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index 60cd6aa48..f67a3f74f 100644 --- a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: fr\n" diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index eea3daeda..2d4e653ab 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: it\n" diff --git a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po index 1bf8e4f82..ac1645c62 100644 --- a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: ru\n" diff --git a/src/pydata_sphinx_theme/locale/sphinx.pot b/src/pydata_sphinx_theme/locale/sphinx.pot index d35cde673..61162fac6 100644 --- a/src/pydata_sphinx_theme/locale/sphinx.pot +++ b/src/pydata_sphinx_theme/locale/sphinx.pot @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: pydata-sphinx-theme 0.15.4.dev0\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" diff --git a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po index 818ed4f61..52bd28db1 100644 --- a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 17:24+0100\n" +"POT-Creation-Date: 2024-08-19 18:04+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: zh\n" From 151811c8a1135abb37372997871bf3fbde8f9aaf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 19 Aug 2024 17:12:22 +0000 Subject: [PATCH 12/39] [pre-commit.ci] Automatic linting and formatting fixes --- .../locale/cs/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/it/LC_MESSAGES/sphinx.po | 12 ------------ 2 files changed, 24 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index 98dbff157..ac9223cf8 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -7,18 +7,6 @@ #, fuzzy msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: cs\n" -"Language-Team: cs \n" -"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index 2d4e653ab..f24bb07d8 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -7,18 +7,6 @@ #, fuzzy msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: it\n" -"Language-Team: it \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" From b2eacdecf53b2ae21e6d2625fac3fcee2d7ce1a1 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 12:24:45 +0100 Subject: [PATCH 13/39] Update tox file - separate assets and translations compilation --- tox.ini | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/tox.ini b/tox.ini index 4aed4abd8..322da8103 100644 --- a/tox.ini +++ b/tox.ini @@ -5,7 +5,7 @@ min_version = 4 # .github/actions/set-dev-env/action.yml (default Python version) env_list = lint, - compile, + compile-assets, py312-docs, py312-tests, a11y-tests @@ -14,8 +14,8 @@ env_list = # helping contributors run tests locally # tox run -m tests labels = - tests = compile, py312-tests - a11y = compile, py312-docs, a11y-tests + tests = compile-assets, py312-tests + a11y = compile-assets, py312-docs, a11y-tests # general tox env configuration # these can be run with any py3{9,12} version @@ -23,18 +23,18 @@ labels = [testenv] deps = lint: pre-commit - compile: sphinx-theme-builder[cli] + compile-assets: sphinx-theme-builder[cli] profile-docs: py-spy extras = {docs-no-checks, docs-linkcheck, profile-docs}: doc skip_install = lint: true # do not need to install to lint profile-docs: true # avoids issues with py-spy and setting the git repo - compile: false + compile-assets: false package = editable commands = lint: pre-commit run -a - compile: stb compile + compile-assets: stb compile # compile JS assets # can substitute the target directory docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going @@ -42,15 +42,16 @@ commands = profile-docs: python ./tools/profile.py {posargs} # tests can be ran with or without coverage (see examples below), -# it is recommended to run compile before running tests (see examples below), -# tox run -e compile,py39-tests -# if you want to skip the assets compilation step you can run the tests without -#`compile`, for example: +# it is recommended to run compile-assets and i18n-compile before running tests +# (see examples below), +# tox run -e compile-assets,i18n-compile,py39-tests +# if you want to skip the assets and translations compilation step you can run +# the tests without `compile-assets,i18n-compile`, for example: # tox run -e py39-tests # run tests with a specific Sphinx version -# tox run -e compile,py39-sphinx61-tests +# tox run -e compile-assets,i18n-compile,py39-sphinx61-tests # run tests without coverage -# tox run -e compile,py39-tests-no-cov +# tox run -e compile-assets,i18n-compile,py39-tests-no-cov [testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}] description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml" # need to ensure the package is installed in editable mode @@ -61,7 +62,7 @@ deps = coverage[toml] py39-sphinx61-tests: sphinx~=6.1.0 py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master -depends = compile +depends = compile-assets,i18n-compile commands = py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs} py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs} @@ -77,7 +78,7 @@ extras = test a11y depends = - compile, + compile-assets, py312-docs allowlist_externals= playwright @@ -140,7 +141,7 @@ allowlist_externals = bash commands = # explicitly pass this as a bash command to set PST_VERSION bash -c "PST_VERSION=$(pip show pydata-sphinx-theme | grep Version | awk -F': ' '{print $2}') && \ - pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --project=pydata-sphinx-theme --copyright-holder='PyData' --version=$PST_VERSION" + pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --project=pydata-sphinx-theme --copyright-holder='PyData developers' --version=$PST_VERSION" # add a new locale for translations based on the catalog template # the locale needs to be given in the format of the language code @@ -148,7 +149,7 @@ commands = # for example: `tox -e i18n-new-locale -- ss` [testenv:i18n-new-locale] description = "Create a new locale based on our catalog template" -extras = i18n +extras = {[testenv:i18n-extract]extras} package = editable commands = pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs} @@ -160,16 +161,17 @@ commands = # tox run -e i18n-update -- --locale=es [testenv:i18n-update] description = "Update the translations based on the latest POT file" -extras = i18n +extras = {[testenv:i18n-extract]extras} package = editable commands = - pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs} + pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx --omit-header {posargs} # compile translation catalogs to binary MO files # tox run -e i18n-compile +# tox run -e i18n-compile -- --use-fuzzy [testenv:i18n-compile] description = "Compile translation catalogs to binary MO files" -extras = i18n +extras = {[testenv:i18n-extract]extras} package = editable commands = - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx \ No newline at end of file + pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx {posargs} \ No newline at end of file From c7854b6ce72291c1c0413acf0b47b9719edeb356 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 12:35:44 +0100 Subject: [PATCH 14/39] Remove fuzzy comments from catalogues --- .../locale/ca/LC_MESSAGES/sphinx.po | 12 +-------- .../locale/cs/LC_MESSAGES/sphinx.po | 13 +--------- .../locale/en/LC_MESSAGES/sphinx.po | 10 ------- .../locale/es/LC_MESSAGES/sphinx.po | 24 +---------------- .../locale/fr/LC_MESSAGES/sphinx.po | 24 +---------------- .../locale/it/LC_MESSAGES/sphinx.po | 12 +-------- .../locale/ru/LC_MESSAGES/sphinx.po | 26 +------------------ .../locale/zh/LC_MESSAGES/sphinx.po | 24 +---------------- 8 files changed, 7 insertions(+), 138 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po index aa671f9c2..4006eba48 100644 --- a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po @@ -1,13 +1,3 @@ -# Catalan translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" - #: docs/conf.py:108 msgid "Click to expand" msgstr "Fes clic per a desplegar" @@ -49,7 +39,7 @@ msgid "Home" msgstr "Inici" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Copyright %(copyright)s." diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index ac9223cf8..9e787613a 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -1,13 +1,3 @@ -# Czech translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" - #: docs/conf.py:108 msgid "Click to expand" msgstr "" @@ -49,7 +39,7 @@ msgid "Home" msgstr "Domů" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Copyright %(copyright)s." @@ -151,7 +141,6 @@ msgid "Announcement" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html:3 -#, fuzzy msgid "Site navigation" msgstr "Navigace na stránce" diff --git a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po index f23de4e42..317917a80 100644 --- a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po @@ -1,13 +1,3 @@ -# English translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" - #: docs/conf.py:108 msgid "Click to expand" msgstr "" diff --git a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po index a8f373e4e..112e249d0 100644 --- a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po @@ -1,25 +1,3 @@ -# Spanish translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" - #: docs/conf.py:108 msgid "Click to expand" msgstr "Haga clic para ampliar" @@ -61,7 +39,7 @@ msgid "Home" msgstr "Inicio" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Copyright %(copyright)s." diff --git a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index f67a3f74f..6ce7671b5 100644 --- a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -1,25 +1,3 @@ -# French translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" - #: docs/conf.py:108 msgid "Click to expand" msgstr "Cliquez pour développer" @@ -61,7 +39,7 @@ msgid "Home" msgstr "Accueil" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Copyright %(copyright)s." diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index f24bb07d8..bd9daea75 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -1,13 +1,3 @@ -# Italian translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" - #: docs/conf.py:108 msgid "Click to expand" msgstr "Fai click per espandere" @@ -49,7 +39,7 @@ msgid "Home" msgstr "Pagina iniziale" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Copyright %(copyright)s." diff --git a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po index ac1645c62..fd6639fbd 100644 --- a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po @@ -1,26 +1,3 @@ -# Russian translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ru\n" -"Language-Team: ru \n" -"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " -"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" - #: docs/conf.py:108 msgid "Click to expand" msgstr "" @@ -62,7 +39,7 @@ msgid "Home" msgstr "Главная" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Копирайт %(copyright)s." @@ -164,7 +141,6 @@ msgid "Announcement" msgstr "" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html:3 -#, fuzzy msgid "Site navigation" msgstr "Навигация по сайту" diff --git a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po index 52bd28db1..8a124ed7b 100644 --- a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po @@ -1,25 +1,3 @@ -# Chinese translations for pydata-sphinx-theme. -# Copyright (C) 2024 PyData -# This file is distributed under the same license as the pydata-sphinx-theme -# project. -# FIRST AUTHOR , 2024. -# -#, fuzzy -msgid "" -msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: zh\n" -"Language-Team: zh \n" -"Plural-Forms: nplurals=1; plural=0;\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" - #: docs/conf.py:108 msgid "Click to expand" msgstr "展开" @@ -61,7 +39,7 @@ msgid "Home" msgstr "初始页面" #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html:5 -#, fuzzy, python-format +#, python-format msgid "Copyright %(copyright)s" msgstr "© Copyright %(copyright)s." From d0a9dba71904cede65e41eee34adf19e8f231a4e Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 12:38:55 +0100 Subject: [PATCH 15/39] Update translations docs - fuzzy comments --- docs/community/topics/i18n.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index d7a332cda..783790cf6 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -66,8 +66,10 @@ positions (line numbers) of the translatable strings. Updating positions is optional - the line numbers are to inform the human translator, not to perform the translation. If you change translatable strings, the ``extract`` command will extract the new or updated strings to the ``POT`` file, -and the ``update`` command will try to fuzzy match the new or updated strings with existing translations in the ``PO`` files. -If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry. +and the ``update`` command will try to perform a fuzzy match between the new or updated strings and existing translations in the ``PO`` files. +If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry, +this means that the translation needs to be manually reviewed and possibly updated. +If after reviewing the translation you decide to keep the existing translation, you can remove the ``#, fuzzy`` comment from the entry. Otherwise, it will add a new translation entry. .. _adding-new-language: From b50baf6209bec5bcc3fc3d50f31fde130bb3d6e2 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 13:13:15 +0100 Subject: [PATCH 16/39] Remove PO compilation from webpack.config --- .github/workflows/CI.yml | 6 ++--- src/pydata_sphinx_theme/locale/sphinx.pot | 5 ++-- tox.ini | 1 - webpack.config.js | 33 +++++++++-------------- 4 files changed, 18 insertions(+), 27 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 0eef947b2..17092de2b 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -74,15 +74,15 @@ jobs: - name: "Run tests ✅" shell: bash run: | - # this will compile the assets then run the tests + # this will compile the assets and translations then run the tests # check if there is a specific Sphinx version to test with # example substitution: tox run -e compile,py39-sphinx61-tests if [ -n "${{matrix.sphinx-version}}" ]; then - python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests + python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests # if not we use the default version # example substitution: tox run -e compile,py39-tests else - python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests + python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests fi - name: "Upload coverage data to GH artifacts 📤" if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev' diff --git a/src/pydata_sphinx_theme/locale/sphinx.pot b/src/pydata_sphinx_theme/locale/sphinx.pot index 61162fac6..9b4b240c3 100644 --- a/src/pydata_sphinx_theme/locale/sphinx.pot +++ b/src/pydata_sphinx_theme/locale/sphinx.pot @@ -1,15 +1,14 @@ # Translations template for pydata-sphinx-theme. -# Copyright (C) 2024 PyData +# Copyright (C) 2024 PyData developers # This file is distributed under the same license as the pydata-sphinx-theme # project. # FIRST AUTHOR , 2024. # -#, fuzzy msgid "" msgstr "" "Project-Id-Version: pydata-sphinx-theme 0.15.4.dev0\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-19 18:04+0100\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" diff --git a/tox.ini b/tox.ini index 322da8103..bd05629b9 100644 --- a/tox.ini +++ b/tox.ini @@ -154,7 +154,6 @@ package = editable commands = pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs} - # update locales translation catalogues based on a POT template, if passed without # arguments it will update all locales tox run -e i18n-update # to update a single locale you can pass the locale code, for example: diff --git a/webpack.config.js b/webpack.config.js index ff56828ec..21d25a02d 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -18,23 +18,16 @@ const CssMinimizerPlugin = require("css-minimizer-webpack-plugin"); const dedent = require("dedent"); const { Compilation } = require("webpack"); -/******************************************************************************* - * Compile our translation files - */ -const { exec } = require("child_process"); -const localePath = resolve(__dirname, "src/pydata_sphinx_theme/locale"); -exec(`pybabel compile -d ${localePath} -D sphinx`); - /******************************************************************************* * Paths for various assets (sources and destinations) */ -const vendorVersions = {fontAwesome: require("@fortawesome/fontawesome-free/package.json").version}; +const vendorVersions = { fontAwesome: require("@fortawesome/fontawesome-free/package.json").version }; const scriptPath = resolve(__dirname, "src/pydata_sphinx_theme/assets/scripts"); -const staticPath = resolve(__dirname,"src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static"); +const staticPath = resolve(__dirname, "src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static"); const vendorPath = resolve(staticPath, "vendor"); -const faPath = {fontAwesome: resolve(vendorPath, "fontawesome", vendorVersions.fontAwesome)}; +const faPath = { fontAwesome: resolve(vendorPath, "fontawesome", vendorVersions.fontAwesome) }; /******************************************************************************* * functions to load the assets in the html head @@ -42,15 +35,15 @@ const faPath = {fontAwesome: resolve(vendorPath, "fontawesome", vendorVersions.f * the fonts are loaded from vendors */ -function stylesheet(css){ return ``;} -function preload(js){ return ``;} -function script(js){ return ``;} -function font(woff2){ return ``;} +function stylesheet(css) { return ``; } +function preload(js) { return ``; } +function script(js) { return ``; } +function font(woff2) { return ``; } /******************************************************************************* * the assets to load in the macro */ - const theme_stylesheets = [ +const theme_stylesheets = [ "styles/theme.css", // basic sphinx css "styles/bootstrap.css", // all bootstrap 5 css with variable adjustments "styles/pydata-sphinx-theme.css", // all the css created for this specific theme @@ -152,15 +145,15 @@ module.exports = { "pydata-sphinx-theme": resolve(scriptPath, "pydata-sphinx-theme.js"), "bootstrap": resolve(scriptPath, "bootstrap.js"), }, - output: {filename: "scripts/[name].js", path: staticPath}, - optimization: {minimizer: ['...', new CssMinimizerPlugin()]}, + output: { filename: "scripts/[name].js", path: staticPath }, + optimization: { minimizer: ['...', new CssMinimizerPlugin()] }, module: { rules: [{ test: /\.scss$/, use: [ - {loader: MiniCssExtractPlugin.loader}, - {loader: "css-loader", options: { url: false }}, - {loader: "sass-loader",}, + { loader: MiniCssExtractPlugin.loader }, + { loader: "css-loader", options: { url: false } }, + { loader: "sass-loader", }, ], }], }, From 7b8282f6624e5581d24cda02996cbee6b7e60674 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 13:32:55 +0100 Subject: [PATCH 17/39] Add note about internationalisation --- docs/community/topics/i18n.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 783790cf6..c0fb7244b 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -3,7 +3,11 @@ Internationalization We use `Gettext `__ message catalogs for the theme's internationalization (I18N) and localization (L10N) and `pybabel `__ to work with them. -This section covers how to mark text as translatable, how to extract translatable text, and how to translate the theme. +User-facing strings in the theme should be internationalized, so that they can be translated into other languages. +This section covers how to mark text as translatable and how to translate the theme. + +..Note + Internationalization (or i18n) is the process of marking strings for translation so that the strings can be extracted from the source code and given to translators. Localization (l10n) is the process of translating the marked strings into different languages. The general process for internationalizing and localizing the theme is as follows: @@ -16,8 +20,8 @@ The general process for internationalizing and localizing the theme is as follow .. _adding-translatable-text: -Marking natural language text as translatable ------------------------------------------------ +Marking strings as translatable (internationalization) +------------------------------------------------------ All natural language text in the theme's components and layouts must be marked as translatable so that it can be extracted and translated. For example, if you add a button with the text "Next page", you will need to mark this text as translatable. From caa761e1ef4b9d47eddcda34fcd417168dbdc291 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 16:57:51 +0100 Subject: [PATCH 18/39] Remove fuzzy strings --- .../locale/ca/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ .../locale/cs/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ .../locale/en/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ .../locale/es/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ .../locale/fr/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ .../locale/it/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ .../locale/ru/LC_MESSAGES/sphinx.po | 21 +++++++++++++++++++ .../locale/zh/LC_MESSAGES/sphinx.po | 20 ++++++++++++++++++ tox.ini | 2 +- 9 files changed, 162 insertions(+), 1 deletion(-) diff --git a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po index 4006eba48..e46cd87d0 100644 --- a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# Catalan translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ca\n" +"Language-Team: ca \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.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "Fes clic per a desplegar" diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index 9e787613a..3b9ccb38d 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# Czech translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: cs\n" +"Language-Team: cs \n" +"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "" diff --git a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po index 317917a80..2c056db37 100644 --- a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# English translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: en\n" +"Language-Team: en \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.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "" diff --git a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po index 112e249d0..a79d0bc86 100644 --- a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# Spanish translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "Haga clic para ampliar" diff --git a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index 6ce7671b5..9afd01318 100644 --- a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# French translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "Cliquez pour développer" diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index bd9daea75..b4c74a2f0 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# Italian translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: it\n" +"Language-Team: it \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.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "Fai click per espandere" diff --git a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po index fd6639fbd..22644e097 100644 --- a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po @@ -1,3 +1,24 @@ +# Russian translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ru\n" +"Language-Team: ru \n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "" diff --git a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po index 8a124ed7b..23318dc0d 100644 --- a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po @@ -1,3 +1,23 @@ +# Chinese translations for PROJECT. +# Copyright (C) 2024 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR , 2024. +# +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2024-08-20 12:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh\n" +"Language-Team: zh \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + #: docs/conf.py:108 msgid "Click to expand" msgstr "展开" diff --git a/tox.ini b/tox.ini index bd05629b9..144c4628c 100644 --- a/tox.ini +++ b/tox.ini @@ -163,7 +163,7 @@ description = "Update the translations based on the latest POT file" extras = {[testenv:i18n-extract]extras} package = editable commands = - pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx --omit-header {posargs} + pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs} # compile translation catalogs to binary MO files # tox run -e i18n-compile From a1608e7ff4afd16166403457c617ac1ffff926b3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 20 Aug 2024 16:39:51 +0000 Subject: [PATCH 19/39] [pre-commit.ci] Automatic linting and formatting fixes --- .../locale/ca/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/en/LC_MESSAGES/sphinx.po | 12 ------------ 2 files changed, 24 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po index e46cd87d0..47f917c06 100644 --- a/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ca\n" -"Language-Team: ca \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po index 2c056db37..4e0a2ac2b 100644 --- a/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: en\n" -"Language-Team: en \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" From cebb954b21065c6570ce559ef4feaafc9ea5aa9c Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 20 Aug 2024 17:48:08 +0100 Subject: [PATCH 20/39] Apply suggestions from code review Co-authored-by: Daniel McCloy --- docs/community/topics/i18n.rst | 10 ++++++---- docs/user_guide/i18n.rst | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index c0fb7244b..05797ccdb 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -44,10 +44,10 @@ Once you've marked the text as translatable, complete the steps outlined in :ref .. _changing-natural-language-text: -Adding or changing natural language text +Updating the translation catalogs ----------------------------------------- -If you add or change natural language text in the theme, you must update the message catalogs to include the new or updated text. Follow these steps: +When you add or change natural language text in the theme, you must update the message catalogs to include the new or updated text. Follow these steps: #. Edit the natural language text and ensure it is :ref:`marked as translatable `. @@ -81,7 +81,7 @@ Otherwise, it will add a new translation entry. Adding a new language ---------------------- -The list of currently supported languages is available in the ``src/pydata_sphinx_theme/locale`` directory. +The list of languages with existing (possibly incomplete) translations is available in the ``src/pydata_sphinx_theme/locale`` directory. To add a new language, follow these steps: @@ -94,6 +94,8 @@ To add a new language, follow these steps: # for example, to add Quechua (ISO 639-1 code: qu) tox -e i18n-new-locale -- qu +#. Start translating the theme's text into the newly added language (see :ref:`translating-the-theme`). + .. _translating-the-theme: @@ -125,7 +127,7 @@ Dealing with variables and markup in translations ````````````````````````````````````````````````````````````` If a variable (like the ``edit_page_provider_name`` theme option) is used as part of a phrase, it must be included within the translatable string. -Otherwise, the word order in other languages can be incorrect. In a Jinja template, simply surround the translatable string with ``{% trans variable=variable %}`` and ``{% endtrans %}}``. For example: +Otherwise, the word order in other languages can be incorrect. In a Jinja template, surround the translatable string with ``{% trans variable=variable %}`` and ``{% endtrans %}``. For example: .. code-block:: jinja diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index a4b935046..0b9695c57 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -12,7 +12,7 @@ Translating configurable strings -------------------------------- These instructions are for translating configurable strings (those that are customizable in ``html_theme_options`` within -the `config.py` file). +the `conf.py` file). These instructions assume that you store your translations in a ``locale`` directory under your documentation directory and that you want to use ``messages`` as the name of the message catalog for these strings. From c7e03ec2bf357a16784d70769c097dcb6b7e6a09 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 20 Aug 2024 16:48:27 +0000 Subject: [PATCH 21/39] [pre-commit.ci] Automatic linting and formatting fixes --- .../locale/cs/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/it/LC_MESSAGES/sphinx.po | 12 ------------ 2 files changed, 24 deletions(-) diff --git a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po index 3b9ccb38d..531811dbc 100644 --- a/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: cs\n" -"Language-Team: cs \n" -"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index b4c74a2f0..e17f311c3 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: it\n" -"Language-Team: it \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" From 9128e7940e86424ec4e3cb57d178fda23af43d31 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 20 Aug 2024 16:48:27 +0000 Subject: [PATCH 22/39] [pre-commit.ci] Automatic linting and formatting fixes --- docs/community/topics/i18n.rst | 10 +++++----- docs/user_guide/i18n.rst | 2 +- .../locale/cs/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/es/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/fr/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/it/LC_MESSAGES/sphinx.po | 12 ------------ .../locale/ru/LC_MESSAGES/sphinx.po | 13 ------------- .../locale/zh/LC_MESSAGES/sphinx.po | 12 ------------ 8 files changed, 6 insertions(+), 79 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 05797ccdb..e702d9b74 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -33,7 +33,7 @@ Remember to `manually escape variables {{- _("Next page") -}} @@ -54,7 +54,7 @@ When you add or change natural language text in the theme, you must update the m #. Generate/update the message catalog template (``POT`` file): .. code-block:: bash - + tox run -e i18n-extract #. Update the message catalogs (``PO`` files) for the existing locales: @@ -90,7 +90,7 @@ To add a new language, follow these steps: #. Make a copy of the ``POT`` file for this new language: .. code-block:: bash - + # for example, to add Quechua (ISO 639-1 code: qu) tox -e i18n-new-locale -- qu @@ -108,7 +108,7 @@ To contribute translations, follow these steps: #. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. -#. Select the language you want to translate. If the language you are looking for is not listed, you can `open an issue +#. Select the language you want to translate. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. #. Now you are ready to start translating the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. @@ -132,7 +132,7 @@ Otherwise, the word order in other languages can be incorrect. In a Jinja templa .. code-block:: jinja {% trans provider=provider %}Edit on {{ provider }}{% endtrans %} - + The translatable string is extracted as the Python format string ``Edit on %(provider)s``. This is so that the same translatable string can be used in both Python code and Jinja templates. It is the translator's responsibility to use ``%(provider)s`` verbatim in the translation. If a non-translatable word or token (like HTML markup) is used as part of a phrase, it must also be included within the translatable string. For example: diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 0b9695c57..88bb1ad9a 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -65,7 +65,7 @@ Note you will also need to install `pybabel \n" -"Language: cs\n" -"Language-Team: cs \n" -"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po index a79d0bc86..6f7616a65 100644 --- a/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po index 9afd01318..ef498653a 100644 --- a/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po index b4c74a2f0..e17f311c3 100644 --- a/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: it\n" -"Language-Team: it \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.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po index 22644e097..33c1c9097 100644 --- a/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po @@ -5,19 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ru\n" -"Language-Team: ru \n" -"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " -"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" #: docs/conf.py:108 msgid "Click to expand" diff --git a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po index 23318dc0d..25ed5b963 100644 --- a/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po +++ b/src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po @@ -5,18 +5,6 @@ # msgid "" msgstr "" -"Project-Id-Version: PROJECT VERSION\n" -"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2024-08-20 12:53+0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: zh\n" -"Language-Team: zh \n" -"Plural-Forms: nplurals=1; plural=0;\n" -"MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" -"Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.16.0\n" #: docs/conf.py:108 msgid "Click to expand" From f283fb8da0254b5126b5bea3a68f4a664ed3c87c Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 29 Aug 2024 12:18:51 +0100 Subject: [PATCH 23/39] Apply suggestions from code review Co-authored-by: gabalafou --- .github/workflows/CI.yml | 2 +- docs/user_guide/i18n.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 17092de2b..5e4765775 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -78,7 +78,7 @@ jobs: # check if there is a specific Sphinx version to test with # example substitution: tox run -e compile,py39-sphinx61-tests if [ -n "${{matrix.sphinx-version}}" ]; then - python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests + python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests # if not we use the default version # example substitution: tox run -e compile,py39-tests else diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 88bb1ad9a..7ed1c6c8c 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -4,9 +4,9 @@ Internationalization This theme contains translatable strings. There are two kinds of strings in this theme, with different steps to translate each. -* **Built-in strings** are hard-coded in the theme's templates. They will be automatically translated if the language is `supported `__. To add another language, refer to the :ref:`translating-the-theme` and :ref:`adding-new-language` sections in the documentation. +* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. To add another language, refer to the :ref:`translating-the-theme` and :ref:`adding-new-language` sections in the documentation. -* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`Translating configurable strings`. Translating configurable strings -------------------------------- From 4a38eee57e027972ba0e1ab9a95b66556be33d25 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 29 Aug 2024 12:23:28 +0100 Subject: [PATCH 24/39] Apply suggestions from code review Co-authored-by: gabalafou --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 144c4628c..fa28d3bca 100644 --- a/tox.ini +++ b/tox.ini @@ -34,7 +34,7 @@ skip_install = package = editable commands = lint: pre-commit run -a - compile-assets: stb compile # compile JS assets + compile-assets: stb compile # bundle JavaScript and Sass # can substitute the target directory docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going From 4209a742e2c3223974fd8341c760dba9baf20ba0 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 29 Aug 2024 12:39:30 +0100 Subject: [PATCH 25/39] Update tox.ini - comments and cleanup --- tox.ini | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/tox.ini b/tox.ini index fa28d3bca..e56f1e612 100644 --- a/tox.ini +++ b/tox.ini @@ -6,19 +6,21 @@ min_version = 4 env_list = lint, compile-assets, + i18n-compile, py312-docs, py312-tests, a11y-tests # convenience label for running tests with a given Python version, aimed at -# helping contributors run tests locally -# tox run -m tests +# helping contributors run common tasks without needing to call all the steps +# For example to run the tests: tox run -m tests labels = - tests = compile-assets, py312-tests - a11y = compile-assets, py312-docs, a11y-tests + tests = compile-assets, i18n-compile, py312-tests + a11y = compile-assets, i18n-compile, py312-docs, a11y-tests + translations = i18n-extract, i18n-update, i18n-compile # general tox env configuration -# these can be run with any py3{9,12} version +# these can be run with any py3{9,12} version, for example: # tox run -e py39-lint [testenv] deps = @@ -35,14 +37,16 @@ package = editable commands = lint: pre-commit run -a compile-assets: stb compile # bundle JavaScript and Sass - # can substitute the target directory + # can substitute the target directory with any other directory by calling: + # tox run -e docs-no-checks -- path/to/other/directory docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going # example tox run -e py39-profile-docs -- -o profile.svg -n 100 profile-docs: python ./tools/profile.py {posargs} # tests can be ran with or without coverage (see examples below), -# it is recommended to run compile-assets and i18n-compile before running tests +# it is recommended to run compile-assets before running tests +# i18n-compile MUST be run before running tests # (see examples below), # tox run -e compile-assets,i18n-compile,py39-tests # if you want to skip the assets and translations compilation step you can run @@ -62,7 +66,9 @@ deps = coverage[toml] py39-sphinx61-tests: sphinx~=6.1.0 py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master -depends = compile-assets,i18n-compile +depends = + compile-assets, + i18n-compile commands = py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs} py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs} @@ -79,6 +85,7 @@ extras = a11y depends = compile-assets, + i18n-compile py312-docs allowlist_externals= playwright @@ -145,7 +152,6 @@ commands = # add a new locale for translations based on the catalog template # the locale needs to be given in the format of the language code -# --update-header-comment # for example: `tox -e i18n-new-locale -- ss` [testenv:i18n-new-locale] description = "Create a new locale based on our catalog template" @@ -173,4 +179,4 @@ description = "Compile translation catalogs to binary MO files" extras = {[testenv:i18n-extract]extras} package = editable commands = - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx {posargs} \ No newline at end of file + pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx {posargs} From 9e54b3f7fb76e0ee70648d9f96349f000aee1154 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 29 Aug 2024 12:39:44 +0100 Subject: [PATCH 26/39] Update translation docs --- docs/community/topics/i18n.rst | 5 +++-- docs/user_guide/i18n.rst | 4 +++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index e702d9b74..96bf2d8ac 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -1,7 +1,8 @@ Internationalization ==================== -We use `Gettext `__ message catalogs for the theme's internationalization (I18N) and localization (L10N) and `pybabel `__ to work with them. +We use `GNU Gettext `__ theme's internationalization (I18N) and localization (L10N) and `pybabel `__ to keep the catalogs up to date. +Crowd-sourced localizations are managed on `Transifex `__. User-facing strings in the theme should be internationalized, so that they can be translated into other languages. This section covers how to mark text as translatable and how to translate the theme. @@ -11,7 +12,7 @@ This section covers how to mark text as translatable and how to translate the th The general process for internationalizing and localizing the theme is as follows: -#. Mark natural language text as translatable. +#. Mark strings in the theme as translatable. #. Extract translatable text to a message catalog template ``POT`` (``PO`` template file). #. Make a copy of the ``POT`` file for each language (locale) you want to translate (or update existing templates). #. Compile the message catalogs to binary ``MO`` files. diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 7ed1c6c8c..87906ebc7 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -6,7 +6,9 @@ There are two kinds of strings in this theme, with different steps to translate * **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. To add another language, refer to the :ref:`translating-the-theme` and :ref:`adding-new-language` sections in the documentation. -* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`Translating configurable strings`. +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`translating-configurable-strings`. + +.. _translating-configurable-strings: Translating configurable strings -------------------------------- From c143597d820244a9a55640f03d0d723460e144e7 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 11:12:22 +0100 Subject: [PATCH 27/39] :wrench: Update tox.ini file - simplify translations --- tox.ini | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/tox.ini b/tox.ini index e56f1e612..6a5510f82 100644 --- a/tox.ini +++ b/tox.ini @@ -17,7 +17,7 @@ env_list = labels = tests = compile-assets, i18n-compile, py312-tests a11y = compile-assets, i18n-compile, py312-docs, a11y-tests - translations = i18n-extract, i18n-update, i18n-compile + translations = i18n-extract, i18n-compile # general tox env configuration # these can be run with any py3{9,12} version, for example: @@ -139,9 +139,13 @@ commands = pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db +# extract translatable files into the POT file and update locale PO files # tox run -e i18n-extract +# this will update all locales, to update a single locale you can +# pass the locale code, for example to update the Spanish locale only: +# tox run -e i18n-extract -- --locale=es [testenv:i18n-extract] -description = "Extract translatable messages from the source code and generate a POT file" +description = "Extract translatable messages from the source code and update locale files" extras = i18n package = editable allowlist_externals = bash @@ -149,6 +153,7 @@ commands = # explicitly pass this as a bash command to set PST_VERSION bash -c "PST_VERSION=$(pip show pydata-sphinx-theme | grep Version | awk -F': ' '{print $2}') && \ pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --project=pydata-sphinx-theme --copyright-holder='PyData developers' --version=$PST_VERSION" + pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs} # add a new locale for translations based on the catalog template # the locale needs to be given in the format of the language code @@ -160,17 +165,6 @@ package = editable commands = pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs} -# update locales translation catalogues based on a POT template, if passed without -# arguments it will update all locales tox run -e i18n-update -# to update a single locale you can pass the locale code, for example: -# tox run -e i18n-update -- --locale=es -[testenv:i18n-update] -description = "Update the translations based on the latest POT file" -extras = {[testenv:i18n-extract]extras} -package = editable -commands = - pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs} - # compile translation catalogs to binary MO files # tox run -e i18n-compile # tox run -e i18n-compile -- --use-fuzzy From c51f2084c9cf234c6f12b8949847c83396ab8f28 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 11:16:46 +0100 Subject: [PATCH 28/39] :recycle: Update all references to compile to compile-assets --- .github/workflows/CI.yml | 4 ++-- .github/workflows/prerelease.yml | 2 +- docs/community/setup.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 5e4765775..cfb76d9fd 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -76,11 +76,11 @@ jobs: run: | # this will compile the assets and translations then run the tests # check if there is a specific Sphinx version to test with - # example substitution: tox run -e compile,py39-sphinx61-tests + # example substitution: tox run -e compile-assets,i18n-compile,py39-sphinx61-tests if [ -n "${{matrix.sphinx-version}}" ]; then python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests # if not we use the default version - # example substitution: tox run -e compile,py39-tests + # example substitution: tox run -e compile-assets,i18n-compile,py39-tests else python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests fi diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml index f6e84b69b..41ba3736a 100644 --- a/.github/workflows/prerelease.yml +++ b/.github/workflows/prerelease.yml @@ -37,7 +37,7 @@ jobs: - name: "Run tests ✅ (no coverage)" run: | # this will compile the assets then run the tests - python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov + python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV # If either the docs build or the tests resulted in an error, create an issue to note it diff --git a/docs/community/setup.md b/docs/community/setup.md index 9e397bbcb..d7a5e5a4f 100644 --- a/docs/community/setup.md +++ b/docs/community/setup.md @@ -162,7 +162,7 @@ These are then built and bundled with the theme (e.g., `scss` is turned into `cs To compile the CSS/JS assets with `tox`, run the following command: ```console -$ tox run -e compile +$ tox run -e compile-assets ``` This will compile all assets and place them in the appropriate folder to be used with documentation builds. From f39c8d4cd20404d95fc49b54a7fd0c8b68e507d4 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 13:09:30 +0100 Subject: [PATCH 29/39] Update localization docs --- docs/community/topics/i18n.rst | 178 +++++++++++++++++++++------------ docs/user_guide/i18n.rst | 4 +- 2 files changed, 118 insertions(+), 64 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 96bf2d8ac..abbb04af0 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -1,37 +1,47 @@ Internationalization ==================== -We use `GNU Gettext `__ theme's internationalization (I18N) and localization (L10N) and `pybabel `__ to keep the catalogs up to date. +This section covers how to internationalize (i18n) and localize (l10n) the PyData Sphinx Theme. +For details on how to translate the configuration options in your Sphinx project, see the User guide section on :ref:`user-guide-i18n`. + +The PyData Sphinx Theme i18n/i10n workflows are based on `GNU Gettext `__ +and `pybabel `__ is used to keep the catalogs up to date. Crowd-sourced localizations are managed on `Transifex `__. -User-facing strings in the theme should be internationalized, so that they can be translated into other languages. -This section covers how to mark text as translatable and how to translate the theme. +.. note:: + **Internationalization** (or i18n) is the process of making a program or application aware of and able to support multiple + languages. + + **Localization** (l10n) is the process of translating localized programs or applications into different languages while + ensuring that the translations are correct for some native language and cultural habits. + + The formal description of specific set of cultural habits for some country, together with all associated translations + targeted to the same native language, is called the *locale* for this language or country. + For more information about localization and internationalization see `GNU gettext concepts `__. -..Note - Internationalization (or i18n) is the process of marking strings for translation so that the strings can be extracted from the source code and given to translators. Localization (l10n) is the process of translating the marked strings into different languages. The general process for internationalizing and localizing the theme is as follows: -#. Mark strings in the theme as translatable. -#. Extract translatable text to a message catalog template ``POT`` (``PO`` template file). -#. Make a copy of the ``POT`` file for each language (locale) you want to translate (or update existing templates). -#. Compile the message catalogs to binary ``MO`` files. -#. Translate the message catalogs. +#. :ref:`Mark strings in the theme as localizable `. +#. :ref:`Extract localizable strings ` to a message catalog template ``POT`` (``PO`` template file). +#. Make a copy of the ``POT`` file for :ref:`a new language (locale) you want to localize ` + (or :ref:`update existing localization files `). +#. :ref:`Compile the message catalogs ` to binary ``MO`` files. +#. :ref:`Localize the theme `. -.. _adding-translatable-text: +.. _adding-localizable-text: -Marking strings as translatable (internationalization) ------------------------------------------------------- +Marking strings as localizable +------------------------------ -All natural language text in the theme's components and layouts must be marked as translatable so that it can be extracted and translated. -For example, if you add a button with the text "Next page", you will need to mark this text as translatable. +All natural language text in the theme's components and layouts must be marked as localizable so that they can be later translated (or localized) into other languages. +For example, if you add a button with the text **Next page**, you will need to mark this text as localizable. -To do so, you can use the Jinja2 ``trans`` block and/or a ``_()`` function to mark text as translatable in corresponding ``HTML`` templates (located in the ``src/pydata_sphinx_theme/theme/`` directory). -`Please refer to the Jinja2 documentation `__. -Remember to `manually escape variables `__ if needed. +``HTML`` templates (located in the ``src/pydata_sphinx_theme/theme/`` directory). +To do so, you can use the Jinja2 ``trans`` block and/or a ``_()`` function to mark text as localizable in the corresponding -For example, to mark the text "Next page" as translatable, you would write: +For example, to mark the text **Next page** as localizable, you would write: .. code-block:: jinja @@ -39,43 +49,80 @@ For example, to mark the text "Next page" as translatable, you would write: {{- _("Next page") -}} +L10n comments need to be Jinja2 comments: + +.. code-block:: jinja + + {# L10n: Navigation button at the bottom of the page #} + -Any text that is marked in this way will be discoverable by ``pybabel`` and used to generate the ``PO`` files. -Once you've marked the text as translatable, complete the steps outlined in :ref:`changing-natural-language-text`. +Any text that is marked in this way will be discoverable by ``pybabel`` and used to generate the localization files +(``PO`` files). -.. _changing-natural-language-text: +Once you've marked the text as localizable, complete the steps outlined in the :ref:`updating-localization-files` +section of this documentation. -Updating the translation catalogs ------------------------------------------ +For more details on marking strings as localizable in jinja templates visit `the Jinja2 documentation `__. -When you add or change natural language text in the theme, you must update the message catalogs to include the new or updated text. Follow these steps: +.. tip:: + Remember to `manually escape variables `__ if needed. -#. Edit the natural language text and ensure it is :ref:`marked as translatable `. +.. _updating-localization-files: -#. Generate/update the message catalog template (``POT`` file): +Updating the localization files +----------------------------------- - .. code-block:: bash +When you add or change natural language text in the theme, you must update the message catalogs to include the new or +updated text. Follow these steps: - tox run -e i18n-extract +#. Edit the natural language text and ensure it is :ref:`marked as translatable `. -#. Update the message catalogs (``PO`` files) for the existing locales: +#. Extract the strings and update the localization files (``POT`` file): .. code-block:: bash - tox run -e i18n-update + # note this will by default update all the localization files for all the supported locales + tox run -e i18n-extract -This will update the translation files with new information about the position and text of the language you have modified. +This will update the localization files with new information about the position and text of the language you have modified. -If you *only* change non-translatable text (like HTML markup), the ``extract`` and ``update`` commands will only update the -positions (line numbers) of the translatable strings. +If you *only* change non-translatable text (like HTML markup), the ``extract`` command will only update the +positions (line numbers) of the localizable strings. Updating positions is optional - the line numbers are to inform the human translator, not to perform the translation. +But it is best practice to keep the positions up to date. + +If you change localizable strings, the above command will extract the new or updated strings to localization template +file (``POT``) and perform a fuzzy match between the new or updated strings and existing translations in the +localization files. +If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry, this means that the +translation needs to be manually reviewed and possibly updated. +If after reviewing the translation you decide to keep the existing translation, you can remove the ``#, fuzzy`` +comment from the entry. +If there is no fuzzy match, it will add a new translation entry. -If you change translatable strings, the ``extract`` command will extract the new or updated strings to the ``POT`` file, -and the ``update`` command will try to perform a fuzzy match between the new or updated strings and existing translations in the ``PO`` files. -If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry, -this means that the translation needs to be manually reviewed and possibly updated. -If after reviewing the translation you decide to keep the existing translation, you can remove the ``#, fuzzy`` comment from the entry. -Otherwise, it will add a new translation entry. +.. _compiling-localization-files: + +Compiling the localization files +-------------------------------- + +Gettext doesn't parse any text files, it reads a binary format for faster performance. To compile the latest PO files in +the repository run: + +.. code-block:: bash + + tox run -e i18n-compile + +You can also run the extract, update and compile commands in one go: + +.. code-block:: bash + + tox run -m translations + +This will update the localization files and compile them into binary ``MO`` files in a single step. +However, if there are fuzzy matches needing review, the compilation will fail, and you will need to review the translations manually. +Then compile the files again. .. _adding-new-language: @@ -95,58 +142,63 @@ To add a new language, follow these steps: # for example, to add Quechua (ISO 639-1 code: qu) tox -e i18n-new-locale -- qu -#. Start translating the theme's text into the newly added language (see :ref:`translating-the-theme`). - +#. Update and compile the localization files as described in the :ref:`updating-localization-files` and + :ref:`compiling-localization-files` sections. +#. Localize the theme's into the newly added language (see :ref:`localizing-the-theme``). -.. _translating-the-theme: +.. _localizing-the-theme: -Translating the theme +Localizing the theme --------------------- -We manage translations on the `PyData Sphinx Theme project on Transifex `__. +We manage localizations on the `PyData Sphinx Theme project on Transifex `__. -To contribute translations, follow these steps: +To contribute localization, follow these steps: #. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. -#. Select the language you want to translate. If the language you are looking for is not listed, you can `open an issue - on GitHub to request it `__. +#. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue + on GitHub to request it `__. Then you can open a pull request + to add the new language following the . #. Now you are ready to start translating the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. Once you have completed your translation, the PyData Sphinx Theme maintainers will review and approve it. -Translation tips +Localization tips ---------------- -Translate phrases, not words +Localize phrases, not words ```````````````````````````` -Full sentences and clauses must always be a single translatable string. +Full sentences and clauses must always be a single localizable string. Otherwise, you can get ``next page`` translated as ``suivant page`` instead of as ``page suivante``, etc. -Dealing with variables and markup in translations -````````````````````````````````````````````````````````````` +Dealing with variables and markup in localizations +`````````````````````````````````````````````````` -If a variable (like the ``edit_page_provider_name`` theme option) is used as part of a phrase, it must be included within the translatable string. -Otherwise, the word order in other languages can be incorrect. In a Jinja template, surround the translatable string with ``{% trans variable=variable %}`` and ``{% endtrans %}``. For example: +A localizable string can be a combination of a fixed string and a variable, for example, ``Welcome to the Spanish version of the site`` +is a combination of the fixed parts ``Welcome to the`` and ``version of the site`` and the variable part ``Spanish``. .. code-block:: jinja - {% trans provider=provider %}Edit on {{ provider }}{% endtrans %} + {% trans language=language %} + Welcome to the {{ language }} version of the site + {% endtrans %} -The translatable string is extracted as the Python format string ``Edit on %(provider)s``. This is so that the same translatable string can be used in both Python code and Jinja templates. It is the translator's responsibility to use ``%(provider)s`` verbatim in the translation. +Binding the variable as ``language=language`` ensures the string can be properly localized, especially as the word order +may vary across locales. +The above string will be extracted as ``Welcome to the %(language) version of the site``. +The translator must use ``%(language)`` verbatim while localizing the theme. -If a non-translatable word or token (like HTML markup) is used as part of a phrase, it must also be included within the translatable string. For example: +When a block contains HTML with attributes, those which don't need to be localized should be passed as arguments. +This ensures strings won't need to be re-localized if those attributes change: .. code-block:: jinja - {% trans theme_version=theme_version|e %} - Built with the PyData Sphinx Theme {{ theme_version }}. + {% trans url="https://pydata.org/" %} + Please visit the PyData website for more information. {% endtrans %} -It is the translator's responsibility to use the HTML markup verbatim in the translation. - - Translation files ------------------ diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 87906ebc7..d6c6497bd 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -1,3 +1,5 @@ +.. _user-guide-i18n: + Internationalization ==================== @@ -6,7 +8,7 @@ There are two kinds of strings in this theme, with different steps to translate * **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. To add another language, refer to the :ref:`translating-the-theme` and :ref:`adding-new-language` sections in the documentation. -* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`translating-configurable-strings`. +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`translating-config`. .. _translating-configurable-strings: From 369e3a0aec088ec41576c9bbccb5793ddd7c0975 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 14:25:03 +0100 Subject: [PATCH 30/39] :pencil2: Fix references in docs --- docs/community/topics/i18n.rst | 4 ++-- docs/user_guide/i18n.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index abbb04af0..1b4d4025f 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -144,7 +144,7 @@ To add a new language, follow these steps: #. Update and compile the localization files as described in the :ref:`updating-localization-files` and :ref:`compiling-localization-files` sections. -#. Localize the theme's into the newly added language (see :ref:`localizing-the-theme``). +#. Localize the theme's into the newly added language (see :ref:`localizing-the-theme`). .. _localizing-the-theme: @@ -165,7 +165,7 @@ To contribute localization, follow these steps: Once you have completed your translation, the PyData Sphinx Theme maintainers will review and approve it. Localization tips ----------------- +----------------- Localize phrases, not words ```````````````````````````` diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index d6c6497bd..6fb8535fb 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -6,9 +6,9 @@ Internationalization This theme contains translatable strings. There are two kinds of strings in this theme, with different steps to translate each. -* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. To add another language, refer to the :ref:`translating-the-theme` and :ref:`adding-new-language` sections in the documentation. +* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. To add another language, refer to the :ref:`localizing-the-theme` and :ref:`adding-new-language` sections in the documentation. -* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`translating-config`. +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`translating-configurable-strings`. .. _translating-configurable-strings: From c0083449aa2fff0be72e50107664e379923e536b Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 14:25:56 +0100 Subject: [PATCH 31/39] Update a11y tests call in CI --- .github/workflows/CI.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index cfb76d9fd..62e77c7f2 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -107,7 +107,7 @@ jobs: graphviz: true - name: "Run accessibility tests with playwright 🎭" # build PST, build docs, then run a11y-tests - run: python -Im tox run -e py312-docs,a11y-tests + run: python -Im tox run -m a11y # Build our docs (PST) on major OSes and check for warnings build-site: From acf54a69c7b78c982f19a373e4a6696c8cd28409 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 17:08:06 +0100 Subject: [PATCH 32/39] Update translation docs --- docs/community/topics/i18n.rst | 105 ++++++++++++++++----------------- docs/user_guide/i18n.rst | 24 +++++--- 2 files changed, 67 insertions(+), 62 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 1b4d4025f..b7aea6da3 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -1,18 +1,19 @@ Internationalization ==================== -This section covers how to internationalize (i18n) and localize (l10n) the PyData Sphinx Theme. -For details on how to translate the configuration options in your Sphinx project, see the User guide section on :ref:`user-guide-i18n`. +This section covers how to internationalize (I18n) and localize (L10n) the PyData Sphinx Theme. +For details on how to localize the configurable strings in your Sphinx project, see the +:ref:`User guide section on internationalization `. -The PyData Sphinx Theme i18n/i10n workflows are based on `GNU Gettext `__ +The PyData Sphinx Theme I18n/i10n workflows are based on `GNU Gettext `__ and `pybabel `__ is used to keep the catalogs up to date. Crowd-sourced localizations are managed on `Transifex `__. .. note:: - **Internationalization** (or i18n) is the process of making a program or application aware of and able to support multiple + **Internationalization** (or I18n) is the process of making a program or application aware of and able to support multiple languages. - **Localization** (l10n) is the process of translating localized programs or applications into different languages while + **Localization** (L10n) is the process of translating localized programs or applications into different languages while ensuring that the translations are correct for some native language and cultural habits. The formal description of specific set of cultural habits for some country, together with all associated translations @@ -24,11 +25,23 @@ The general process for internationalizing and localizing the theme is as follow #. :ref:`Mark strings in the theme as localizable `. #. :ref:`Extract localizable strings ` to a message catalog template ``POT`` (``PO`` template file). -#. Make a copy of the ``POT`` file for :ref:`a new language (locale) you want to localize ` +#. Generare a ``PO`` file from the ``POT`` file for :ref:`a new language (locale) you want to localize ` (or :ref:`update existing localization files `). #. :ref:`Compile the message catalogs ` to binary ``MO`` files. #. :ref:`Localize the theme `. +Localization files +------------------- + +There are three types of files used in the localization process: + +#. `PO files `__ ( Portable Object, also known as message catalogs) + associate each original, translatable string (defined in ``msgid``) of a given program with its translation in a + particular target language (defined in ``msgstr`` fields). A single PO file is dedicated to a single target language. +#. ``MO`` (Machine Object) files are a binary version of a PO file. +#. ``POT`` (Portable Object Template) files are similar to PO files, but with empty translations. + They are used as a template for new languages. + .. _adding-localizable-text: @@ -49,15 +62,6 @@ For example, to mark the text **Next page** as localizable, you would write: {{- _("Next page") -}} -L10n comments need to be Jinja2 comments: - -.. code-block:: jinja - - {# L10n: Navigation button at the bottom of the page #} - - Any text that is marked in this way will be discoverable by ``pybabel`` and used to generate the localization files (``PO`` files). @@ -69,6 +73,18 @@ For more details on marking strings as localizable in jinja templates visit `the .. tip:: Remember to `manually escape variables `__ if needed. +Sometimes, it can help localizers to describe where a string comes from or whether it refers to a noun or verb, +particularly if it can be difficult to find in the theme, or if the string itself is not very self-descriptive (for example, very short strings). +If you immediately precede the string with a comment that starts with ``L10n:``, the comment will be added to the PO +file, and visible to localizers. For example: + +.. code-block:: jinja + + {# L10n: Navigation button at the bottom of the page #} + + .. _updating-localization-files: Updating the localization files @@ -77,7 +93,7 @@ Updating the localization files When you add or change natural language text in the theme, you must update the message catalogs to include the new or updated text. Follow these steps: -#. Edit the natural language text and ensure it is :ref:`marked as translatable `. +#. Edit the natural language text and ensure it is :ref:`marked as localizable `. #. Extract the strings and update the localization files (``POT`` file): @@ -88,19 +104,20 @@ updated text. Follow these steps: This will update the localization files with new information about the position and text of the language you have modified. -If you *only* change non-translatable text (like HTML markup), the ``extract`` command will only update the +If you *only* change non-localizable text (like HTML markup), the ``extract`` command will only update the positions (line numbers) of the localizable strings. -Updating positions is optional - the line numbers are to inform the human translator, not to perform the translation. +Updating positions is optional - the line numbers are to inform the human translator, not to perform the localization. But it is best practice to keep the positions up to date. If you change localizable strings, the above command will extract the new or updated strings to localization template -file (``POT``) and perform a fuzzy match between the new or updated strings and existing translations in the +file (``POT``) and perform a fuzzy match between the new or updated strings and existing localizations in the localization files. If there is a fuzzy match, a comment like ``#, fuzzy`` is added before the matched entry, this means that the -translation needs to be manually reviewed and possibly updated. -If after reviewing the translation you decide to keep the existing translation, you can remove the ``#, fuzzy`` +localization needs to be manually reviewed and possibly updated. +If after reviewing the localization you decide to keep the existing localization, you can remove the ``#, fuzzy`` comment from the entry. -If there is no fuzzy match, it will add a new translation entry. +If there is no fuzzy match, it will add a new localization entry. +You can learn more about fuzzy entries in the `GNU gettext manual `__. .. _compiling-localization-files: @@ -118,10 +135,11 @@ You can also run the extract, update and compile commands in one go: .. code-block:: bash - tox run -m translations + tox run -m i18n This will update the localization files and compile them into binary ``MO`` files in a single step. -However, if there are fuzzy matches needing review, the compilation will fail, and you will need to review the translations manually. +However, if there are fuzzy matches needing review, the compilation will fail, and you will need to review the +localizations manually. Then compile the files again. .. _adding-new-language: @@ -129,13 +147,14 @@ Then compile the files again. Adding a new language ---------------------- -The list of languages with existing (possibly incomplete) translations is available in the ``src/pydata_sphinx_theme/locale`` directory. +The list of languages with existing (possibly incomplete) localizations is available in the +``src/pydata_sphinx_theme/locale`` directory. To add a new language, follow these steps: #. Identify the `ISO 639-1 code `__ for the new language. -#. Make a copy of the ``POT`` file for this new language: +#. Generate a ``PO`` file based on ``POT`` file for this new language: .. code-block:: bash @@ -143,7 +162,7 @@ To add a new language, follow these steps: tox -e i18n-new-locale -- qu #. Update and compile the localization files as described in the :ref:`updating-localization-files` and - :ref:`compiling-localization-files` sections. + :ref:`compiling-localization-files` sections. Then commit the changes. #. Localize the theme's into the newly added language (see :ref:`localizing-the-theme`). .. _localizing-the-theme: @@ -159,10 +178,11 @@ To contribute localization, follow these steps: #. Join the `PyData Sphinx Theme project `__. #. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request - to add the new language following the . -#. Now you are ready to start translating the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. + to add the new language following the steps outlined in :ref:`adding-a-new-language. +#. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the + `Transifex documentation `__ for more information. -Once you have completed your translation, the PyData Sphinx Theme maintainers will review and approve it. +Once you have completed your localization, the PyData Sphinx Theme maintainers will review and approve it. Localization tips ----------------- @@ -171,7 +191,7 @@ Localize phrases, not words ```````````````````````````` Full sentences and clauses must always be a single localizable string. -Otherwise, you can get ``next page`` translated as ``suivant page`` instead of as ``page suivante``, etc. +Otherwise, you can get ``next page`` localizated as ``suivant page`` instead of as ``page suivante``, etc. Dealing with variables and markup in localizations `````````````````````````````````````````````````` @@ -199,29 +219,6 @@ This ensures strings won't need to be re-localized if those attributes change: Please visit the PyData website for more information. {% endtrans %} -Translation files ------------------- - -Gettext and pybabel read a program's source and extract text that has been marked as translatable, known as "source strings". - -There are three types of files used in the translation process: - -PO file (``.po``) - A `Portable Object (PO) file `__ which contains all the translatable entries. - Each entry holds the relation between a source string and its translation. - ``msgid`` contains the **source string**, and ``msgstr`` contains the **translation**. - 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 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 that 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 into MO files. References ---------- diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 6fb8535fb..66ca42d3e 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -3,12 +3,15 @@ Internationalization ==================== -This theme contains translatable strings. -There are two kinds of strings in this theme, with different steps to translate each. +This theme contains localizable (translatable) strings. +There are two kinds of strings in this theme, with different steps to translate each: -* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. To add another language, refer to the :ref:`localizing-the-theme` and :ref:`adding-new-language` sections in the documentation. +* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported `__. + To add another language, refer to the :ref:`localizing-the-theme` and :ref:`adding-new-language` sections in the documentation. -* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other sections in :doc:`the user guide` for examples of these configurable strings). To translate these strings, see :ref:`translating-configurable-strings`. +* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other + sections in :doc:`the user guide ` for examples of these configurable strings). + To translate these strings, see the :ref:`translating-configurable-strings` section in this page. .. _translating-configurable-strings: @@ -16,11 +19,14 @@ Translating configurable strings -------------------------------- These instructions are for translating configurable strings (those that are customizable in ``html_theme_options`` within -the `conf.py` file). +the ``conf.py`` file). -These instructions assume that you store your translations in a ``locale`` directory under your documentation directory and that you want to use ``messages`` as the name of the message catalog for these strings. +These instructions assume that you store your translations in a ``locale`` directory under your documentation directory +and that you want to use ``messages`` as the name of the message catalog for these strings (you can change this name if +needed). -Note you will also need to install `pybabel `__ to handle your documentation translations. +Note you will also need to install `pybabel `__ to handle your +documentation translations. #. In your ``conf.py`` file: @@ -57,7 +63,7 @@ Note you will also need to install `pybabel Date: Fri, 30 Aug 2024 17:13:40 +0100 Subject: [PATCH 33/39] Update docs and command regardin docs-live --- docs/community/setup.md | 22 +++++++++++++++------- tox.ini | 16 ++++++++++------ 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/docs/community/setup.md b/docs/community/setup.md index d7a5e5a4f..36cc9ae8c 100644 --- a/docs/community/setup.md +++ b/docs/community/setup.md @@ -7,9 +7,8 @@ If you are comfortable with and prefer a more manual setup refer to the [](topic ## Testing pre-release and nightly -You can test the alpha, beta -and release candidates of pydata sphinx theme on your your projects. To do so -simply install with pip using the `--pre` flag: +You can test the alpha, beta and release candidates of the PyData Sphinx theme on your projects. +To do so install with pip using the `--pre` flag: ```console $ pip install --pre pydata-sphinx-theme @@ -20,9 +19,9 @@ If an `alpha`, `beta` or `rc` is available, pip will install it. You can use the `--pre` flag in your project's continuous integration test suite to catch regressions or bugs before their release. -If you are even more adventurous pydata-sphinx-theme has nightly builds, you can try following the +If you are even more adventurous `pydata-sphinx-theme` has nightly builds, you can try following the instructions provided [on the scientific-python/upload-nightly-action -Readme](https://github.com/scientific-python/upload-nightly-action?tab=readme-ov-file#using-nightly-builds-in-ci) +README](https://github.com/scientific-python/upload-nightly-action?tab=readme-ov-file#using-nightly-builds-in-ci) on installing nightly wheels. Installing nightly wheels in your project's CI jobs is a great way to help theme developers catch bugs ahead of @@ -145,6 +144,14 @@ $ python -m http.server -d docs/_build/html/ This will print a local URL that you can open in a browser to explore the HTML files. +You can also serve the documentation with live-reload using the following command: + +```console +$ tox run -e docs-live +``` + +This command will build the documentation and watch for any changes to the `doc` folder and rebuild the documentation automatically. + ### Change content and re-build Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds. @@ -174,12 +181,13 @@ The `sphinx-theme-builder` will bundle these assets automatically when we make a ## Run a development server -You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. +You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that +changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. To run the development server with `tox`, run the following command: ```console -$ tox run -e docs-live +$ tox run -e docs-live-theme ``` When working on the theme, making changes to any of these directories: diff --git a/tox.ini b/tox.ini index 6a5510f82..2d6bdd5a8 100644 --- a/tox.ini +++ b/tox.ini @@ -17,7 +17,8 @@ env_list = labels = tests = compile-assets, i18n-compile, py312-tests a11y = compile-assets, i18n-compile, py312-docs, a11y-tests - translations = i18n-extract, i18n-compile + i18n = i18n-extract, i18n-compile + live-docs = compile-assets, i18n-compile, docs-live # general tox env configuration # these can be run with any py3{9,12} version, for example: @@ -124,20 +125,23 @@ commands = sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} python tests/utils/check_warnings.py - -[testenv:docs-live] +# build the docs with live-reload, if you are working on the docs only (no theme changes) the best option is to call +# tox run -e docs-live +# this will only watch the docs directory and rebuild the docs when changes are detected +# if you are working on the theme (HTML, jinja templates, JS, CSS) and the docs, you can call +# tox run -e docs-live-theme +[testenv:docs-live{,-theme}] description = "Build and serve the documentation with live-reload" extras = dev - i18n package = editable deps = sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b # suppress Py3.11's new "can't debug frozen modules" warning set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 commands = - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx - stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db + docs-live-theme: stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db + docs-live: sphinx-autobuild docs/ docs/_build/html --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db # extract translatable files into the POT file and update locale PO files # tox run -e i18n-extract From 15f8f05cc91cf727a1449f4eca8287d5f3b8ed68 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 17:17:14 +0100 Subject: [PATCH 34/39] Replace guide to use docs-live-server --- docs/community/setup.md | 3 ++- tox.ini | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/community/setup.md b/docs/community/setup.md index 36cc9ae8c..f14961070 100644 --- a/docs/community/setup.md +++ b/docs/community/setup.md @@ -187,7 +187,8 @@ changes to `src/` are automatically bundled with the package, and the documentat To run the development server with `tox`, run the following command: ```console -$ tox run -e docs-live-theme +# note the -m flag vs. other commands in this guide +$ tox run -m docs-live-server ``` When working on the theme, making changes to any of these directories: diff --git a/tox.ini b/tox.ini index 2d6bdd5a8..5e062a708 100644 --- a/tox.ini +++ b/tox.ini @@ -18,7 +18,7 @@ labels = tests = compile-assets, i18n-compile, py312-tests a11y = compile-assets, i18n-compile, py312-docs, a11y-tests i18n = i18n-extract, i18n-compile - live-docs = compile-assets, i18n-compile, docs-live + live-server = compile-assets, i18n-compile, docs-live # general tox env configuration # these can be run with any py3{9,12} version, for example: From 66e0f7138f7c887d16899356eb819670bf5a34f2 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 30 Aug 2024 17:25:19 +0100 Subject: [PATCH 35/39] :pencil2: Add missing ` --- docs/community/topics/i18n.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index b7aea6da3..8edd14f17 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -176,9 +176,8 @@ To contribute localization, follow these steps: #. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. -#. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue - on GitHub to request it `__. Then you can open a pull request - to add the new language following the steps outlined in :ref:`adding-a-new-language. +#. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request + to add the new language following the steps outlined in :ref:`adding-a-new-language`. #. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. From 10a1d773cc51cd88e0bb8a5dffea4768da44d0ca Mon Sep 17 00:00:00 2001 From: M Bussonnier Date: Mon, 2 Sep 2024 01:13:12 -0700 Subject: [PATCH 36/39] Update docs/community/topics/i18n.rst Co-authored-by: Daniel McCloy --- docs/community/topics/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 8edd14f17..769dc8ab3 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -177,7 +177,7 @@ To contribute localization, follow these steps: #. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. #. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request - to add the new language following the steps outlined in :ref:`adding-a-new-language`. + to add the new language following the steps outlined in :ref:`adding a new language`. #. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. From e63edde25446db1e9c0ffe290bdb82cb33b27bf1 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 12:29:45 +0100 Subject: [PATCH 37/39] Revert inline reference --- docs/community/topics/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 769dc8ab3..0a43edfd7 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -177,7 +177,7 @@ To contribute localization, follow these steps: #. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. #. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request - to add the new language following the steps outlined in :ref:`adding a new language`. + to add the new language following the steps outlined in :ref:`adding-new-language`. #. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. From b74c71f07bdd40be711ec14c4548c43627b18fa1 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 12:42:11 +0100 Subject: [PATCH 38/39] Update comments --- webpack.config.js | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/webpack.config.js b/webpack.config.js index 15df63dae..757d399f1 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -5,9 +5,8 @@ * * - Generates a `webpack-macros.html` file that defines macros used * to insert CSS / JS at various places in the main `layout.html` template. - * - Compiles our translation files into .mo files so they can be bundled with the theme * - Compiles our SCSS and JS and places them in the _static/ folder - * - Downloads and links FontAwesome and some JS libraries (Bootstrap, etc) + * - Vendors FontAwesome and some JS libraries (Bootstrap, etc) */ const { resolve } = require("path"); From bb7282c8679751de1fc018312aca4bf20c65b890 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 12:47:22 +0100 Subject: [PATCH 39/39] :rotating_light: Lint and format files --- docs/community/topics/i18n.rst | 32 ++++++++++++++++---------------- docs/user_guide/i18n.rst | 6 +++--- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index 0a43edfd7..8c1a2afd6 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -2,20 +2,20 @@ Internationalization ==================== This section covers how to internationalize (I18n) and localize (L10n) the PyData Sphinx Theme. -For details on how to localize the configurable strings in your Sphinx project, see the +For details on how to localize the configurable strings in your Sphinx project, see the :ref:`User guide section on internationalization `. The PyData Sphinx Theme I18n/i10n workflows are based on `GNU Gettext `__ -and `pybabel `__ is used to keep the catalogs up to date. +and `pybabel `__ is used to keep the catalogs up to date. Crowd-sourced localizations are managed on `Transifex `__. .. note:: **Internationalization** (or I18n) is the process of making a program or application aware of and able to support multiple - languages. + languages. **Localization** (L10n) is the process of translating localized programs or applications into different languages while ensuring that the translations are correct for some native language and cultural habits. - + The formal description of specific set of cultural habits for some country, together with all associated translations targeted to the same native language, is called the *locale* for this language or country. For more information about localization and internationalization see `GNU gettext concepts `__. @@ -35,11 +35,11 @@ Localization files There are three types of files used in the localization process: -#. `PO files `__ ( Portable Object, also known as message catalogs) +#. `PO files `__ ( Portable Object, also known as message catalogs) associate each original, translatable string (defined in ``msgid``) of a given program with its translation in a - particular target language (defined in ``msgstr`` fields). A single PO file is dedicated to a single target language. + particular target language (defined in ``msgstr`` fields). A single PO file is dedicated to a single target language. #. ``MO`` (Machine Object) files are a binary version of a PO file. -#. ``POT`` (Portable Object Template) files are similar to PO files, but with empty translations. +#. ``POT`` (Portable Object Template) files are similar to PO files, but with empty translations. They are used as a template for new languages. @@ -52,7 +52,7 @@ All natural language text in the theme's components and layouts must be marked a For example, if you add a button with the text **Next page**, you will need to mark this text as localizable. ``HTML`` templates (located in the ``src/pydata_sphinx_theme/theme/`` directory). -To do so, you can use the Jinja2 ``trans`` block and/or a ``_()`` function to mark text as localizable in the corresponding +To do so, you can use the Jinja2 ``trans`` block and/or a ``_()`` function to mark text as localizable in the corresponding For example, to mark the text **Next page** as localizable, you would write: @@ -74,8 +74,8 @@ For more details on marking strings as localizable in jinja templates visit `the Remember to `manually escape variables `__ if needed. Sometimes, it can help localizers to describe where a string comes from or whether it refers to a noun or verb, -particularly if it can be difficult to find in the theme, or if the string itself is not very self-descriptive (for example, very short strings). -If you immediately precede the string with a comment that starts with ``L10n:``, the comment will be added to the PO +particularly if it can be difficult to find in the theme, or if the string itself is not very self-descriptive (for example, very short strings). +If you immediately precede the string with a comment that starts with ``L10n:``, the comment will be added to the PO file, and visible to localizers. For example: .. code-block:: jinja @@ -147,7 +147,7 @@ Then compile the files again. Adding a new language ---------------------- -The list of languages with existing (possibly incomplete) localizations is available in the +The list of languages with existing (possibly incomplete) localizations is available in the ``src/pydata_sphinx_theme/locale`` directory. To add a new language, follow these steps: @@ -161,7 +161,7 @@ To add a new language, follow these steps: # for example, to add Quechua (ISO 639-1 code: qu) tox -e i18n-new-locale -- qu -#. Update and compile the localization files as described in the :ref:`updating-localization-files` and +#. Update and compile the localization files as described in the :ref:`updating-localization-files` and :ref:`compiling-localization-files` sections. Then commit the changes. #. Localize the theme's into the newly added language (see :ref:`localizing-the-theme`). @@ -176,9 +176,9 @@ To contribute localization, follow these steps: #. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. -#. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request +#. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request to add the new language following the steps outlined in :ref:`adding-new-language`. -#. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the +#. Now you are ready to start localizing the theme. If you are new to Transifex you can visit the `Transifex documentation `__ for more information. Once you have completed your localization, the PyData Sphinx Theme maintainers will review and approve it. @@ -206,10 +206,10 @@ is a combination of the fixed parts ``Welcome to the`` and ``version of the site Binding the variable as ``language=language`` ensures the string can be properly localized, especially as the word order may vary across locales. -The above string will be extracted as ``Welcome to the %(language) version of the site``. +The above string will be extracted as ``Welcome to the %(language) version of the site``. The translator must use ``%(language)`` verbatim while localizing the theme. -When a block contains HTML with attributes, those which don't need to be localized should be passed as arguments. +When a block contains HTML with attributes, those which don't need to be localized should be passed as arguments. This ensures strings won't need to be re-localized if those attributes change: .. code-block:: jinja diff --git a/docs/user_guide/i18n.rst b/docs/user_guide/i18n.rst index 66ca42d3e..db8c63664 100644 --- a/docs/user_guide/i18n.rst +++ b/docs/user_guide/i18n.rst @@ -21,11 +21,11 @@ Translating configurable strings These instructions are for translating configurable strings (those that are customizable in ``html_theme_options`` within the ``conf.py`` file). -These instructions assume that you store your translations in a ``locale`` directory under your documentation directory +These instructions assume that you store your translations in a ``locale`` directory under your documentation directory and that you want to use ``messages`` as the name of the message catalog for these strings (you can change this name if needed). -Note you will also need to install `pybabel `__ to handle your +Note you will also need to install `pybabel `__ to handle your documentation translations. #. In your ``conf.py`` file: @@ -85,4 +85,4 @@ documentation translations. pybabel compile --directory=locale --domain=messages -Done! Your configurable strings are now localized. \ No newline at end of file +Done! Your configurable strings are now localized.