Localization of PyO3 User Guide

[hwhsu1231]

Announcement

Hello, PyO3 Community,

I’m glad to announce that the 🎉 pyo3-guide-l10n 🎉 project is published now:

• 🚀 Preview: pyo3-guide-l10n
• 🌐 Crowdin: pyo3-guide-l10n
• 🐙 GitHub: pyo3-guide-l10n

The goal of this project is to translate the PyO3 User Guide into multiple languages. Translations are contributed via the Crowdin platform, automatically synchronized with the GitHub repository, and can be previewed on GitHub Pages.

If translators want to translate a language that is not yet supported, they just need to open a new issue to request the new language. Once the requested language is added, they can begin translating.

There is an existing issue (#5282) proposing the addition of Simplified Chinese for the PyO3 User Guide. And I believe the pyo3-guide-l10n project can fulfill this requirement.

How to Keep Translations Up-to-date?

Regarding the frequently asked question, "How to Keep Translations Up-to-date?", I would like to share my perspective on this matter.

First, I think the focus should not be on keeping the "translations" up-to-date, but rather on keeping the "translatable contents" in synchronization. The fundamental reason why so many translation projects eventually become unmaintained (especially those that rely on creating direct file copies of the original) is the lack of a mechanism to synchronize updates from the English source text. This forces translators to manually check "which parts are outdated" before contributing. Therefore, one of the core functions of the infrastructure (scripts and workflows) designed by the @localizethedocs organization is to "automate the task of synchronizing the latest changes of the English source text".

In the pyo3-guide-l10n repository, the ci-mdbook-update-pot.yml workflow is executed weekly to check the upstream project for any required updates to the document content, which in turn triggers the update of the .pot files. If an update is needed, a Pull Request (PR) is automatically created to merge into the l10n branch. For example:

• 🌐 pot(latest): update .pot from mdBook localizethedocs/pyo3-guide-l10n#2
• 🌐 pot(stable): update .pot from mdBook localizethedocs/pyo3-guide-l10n#3

Therefore, the core responsibility of the code maintainers, besides ensuring the stable operation of the scripts and workflows, is to regularly check whether there are any pending PRs that need to be merged.

How to Reuse Translations?

If the upstream project or anyone wants to reuse the translated .po files prepared by the pyo3-guide-l10n project, they can clone the .po files from the po/${VERSION} branch by using the following command:

git clone --depth=1 --branch=po/${VERSION} https://github.com/localizethedocs/pyo3-guide-l10n.git locale

Those po/${VERSION} branches are created to facilitate reusage by the upstream project. For instance, the zh_TW documentation for the latest version can be generated using the commands below:

BRANCH=main
VERSION=latest
LANGUAGE=zh_TW
RENDERER=html

# Prepare the repository and environment
git clone --branch=${BRANCH} --depth=1 https://github.com/PyO3/pyo3.git pyo3-guide
cd pyo3-guide
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install conda-forge::rust=1.90 conda-forge::dasel=2 conda-forge::python=3.12 --channel conda-forge --yes
export CARGO_INSTALL_ROOT=$(pwd)/.conda
export PYTHONNOUSERSITE=1
cargo install mdbook@^0.5 mdbook-i18n-helpers@^0.4 mdbook-tabs@^0.3

# Clone the .po files to the 'locale' directory
git clone --branch=po/${VERSION} --depth=1 https://github.com/localizethedocs/pyo3-guide-l10n.git guide/locale

# Build the documentation
export MDBOOK_BOOK__LANGUAGE=${LANGUAGE}
export MDBOOK_OUTPUT="{\"$RENDERER\":$(dasel -f guide/book.toml "output.$RENDERER" -w json)}"
export MDBOOK_PREPROCESSOR__GETTEXT=$(jq -n -c '{"after":["links"],"po-dir":"locale"}')
mdbook build guide --dest-dir $(pwd)/guide/book/${LANGUAGE}

# Preview the documentation
firefox $(pwd)/guide/book/${LANGUAGE}/index.html