Translating the package guide to spanish 🚀

[flpm]

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.

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]

@all-contributors add @flpm for review

[allcontributors]

@kierisi

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

[flpm]

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]

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!

[lwasser]

@flpm i am going through issues now - Given you have added the appropriate infrastructure to support this, can now close this issue in favor of #313 ?

[flpm]

Sure, the one can be closed

[lwasser]

great - thanks!! @flpm i invited a few folks to our slack who want to help with the spanish translation!! i met them in our packaging workshop :) i'll be sure to connect everyone!

in the meantime i'm closing this!!