search

pyOpenSci / python-package-guide

scientific Python package recommendations & guidance curated by pyOpenSci
https://www.pyopensci.org/python-package-guide/
Other
70 stars 43 forks source link

Translating the package guide to spanish 🚀 #287

Open flpm opened 1 month ago

flpm commented 1 month ago

Have you considered translating the Python Packaging Guide into other languages?

During PyCon US I got to help with translating Flask documentation into Spanish and had a chance to see how they use sphinx-intl to enable internationalization.

The process is quite simple and, as a test, I reproduced the setup and translated a few strings into Spanish. The 'docs-live' session in nox even updates the browser as you are translating so you can see the context around it.

Screenshot from 2024-05-30 15-50-51

I am happy to help with that if you think it is interesting. It requires some editorial process to be defined to make sure the translations are accurate (e.g. the Flask Community Working Group assigns a coordinator per language to review translation PRs, etc.) but it creates lots of beginner-friendly opportunities to contribute.

kierisi commented 1 month ago

@all-contributors add @flpm for review

allcontributors[bot] commented 1 month ago

@kierisi

I've put up a pull request to add @flpm! :tada:

flpm commented 4 weeks ago

After playing with nox a little more, here is a potential approach:

1) Create new nox session (e.g. nox --session update-translation-files) that will prepare the translation files for each language in a list (e.g., LANGUAGES = ['es', 'pt']) using sphinx and sphinx-intl. This would create the translation template files (./_build/gettext/*.pot) and the translation files for each language (e.g., ./locales/es/LC_MESSAGES/*.po for Spanish).

2) Translators work on these .po files, which map strings from the English version to their translated equivalents, and make a PR to update them.

3) An language editor/coordinator reviews the translation, request changes as needed, and merge the PR.

4) The current build sessions in nox (docs, docs-test and docs-live) would build the guide and the translations in the language list. The translations would be place in folders under the root of the guide (e.g., _build/html/es/ for Spanish) and would be accessed in the site in the same (https://www.pyopensci.org/python-package-guide/es/index.html)

As the guide evolves, the update-translation-files session will keep the translation files up to date with new strings and changes. To start translation into a new language, just add to the list and run the nox session to create the new translation files for that new language.

I was able to prototype this and I think it is very doable.

lwasser commented 3 weeks ago

this is incredible. i left a note on your pr. but i'm SOOO thrilled to see this is even possible with infrastructure support. i'm really sorry that i'm so behind on pr's @flpm i'm trying to chip away at everything. it is all so good!