Add support for internationalization to the guide

[flpm]

This PR adds support for internationalization to the Package Guide as described in issue #287.

See the translation guide in PR #304 for a description of the workflow.

What was done

• Documented and cleaned up the current nox sessions in noxfile.py to make it easier to maintain as the configuration becomes more complex
• Parameterized the nox configuration options as variables at the top of the file
• Added new sessions to Nox:
  • update-translations: create and update translations files for the languages defined in LANGUAGES
  • build-translations: build the guide in the languages defined in LANGUAGES
  • docs-live-lang: a convenience session to launch docs-live using a specific language build
  • build-translations-test: a convenience session to run docs-test using a specific language build
  • build-languages: a session used by build-translations to build a list of languages (will not be called directly)
• Modified the docs and docs-live sessions to build the language translations defined in RELEASE_LANGUAGES
• Updated pyproject.toml with dev dependencies for translation workflows
• Modified the pre-commit configuration for codespell to exclude the translation .po files

How to test

1. Check out the PR branch

git remote add flpm [email protected]:flpm/python-package-guide.git
git fetch flpm
git checkout -b issue-287-internationalization flpm/issue-287-internationalization

2. Create a new virtual environment and install the development dependencies

python -m venv .venv-test
source .venv-test/bin/activate
pip install -e .[dev]

3. nox -s docs and check that the build is clean
4. nox -s docs-test and check that the build is clean
5. nox -s docs-live and check that it works as expected by visiting http://localhost:8000
6. Check that these commands did not build the Spanish translation (_build/html/es folder does not exist)
7. nox docs-clean to delete the build files (check that _build/html is empty now)
8. Generate the translation files using nox -s build-translations
9. Check that this created a new folder locales/es/LC_MESSAGES/ and that this folder now has translation files (.po)
10. Open locales/es/LC_MESSAGES/index.po (the file that corresponds to the contents of the guide landing page). Replace the empty string in line 45 with "La guía de paquetes de Python de pyOpenSci". You just translated the title of the guide.
11. Build the translations using nox -s build-translations and verify it has no warnings or errors
12. Build the translations using nox -s build-translations-test (apply the parameters from docs-test to build-translations) and verify it has no warnings or errors
13. Open the translated guide in a local browser (`_build/html/es/index.html) and verify that the title is now in Spanish
14. Run the live version of the guide on the Spanish translation with nox -s docs-live-lang -- es and visit http://localhost:8000 to verify that the title is the Spanish title

[lwasser]

this is so cool @flpm

This is such a huge benefit to us and the community!

The one question I have about this is how we maintain when we update things / add new content (and then there are images).

On another note - can i invite you to our slack? you have contributed so much !! in case you want to engage there i'd love to invite you.

[flpm]

Sure, I am happy to join, you can send it to [email protected]

I imagine there will be lots of questions, I am happy to help with that.

I have the PR as a draft for now while I am sorting out a few last details.

[lwasser]

I have the PR as a draft for now while I am sorting out a few last details.

no problem! i just invited you to slack. and i'm sure this pr will take some time!! have a wonderful weekend and thank you again for all of the work youre doing to help pyOpenSci!! ✨

[flpm]

To make this PR easier for review, I will split it into two parts: this one focusing on the set up of the translation workflow, and a new one for the actual Spanish translation.

[lwasser]

@flpm i'm going to go ahead and merge this as i suspect your second pr will be the one that i can better see what's going on!! thank you for this!!