i18n: Add full support

[jpmckinney]

resolves #257

• Translate PO files
• Generate MO files
• Test with another site

[jpmckinney]

This should work now. I'll test on my docs site.

[jpmckinney]

Okay, this is ready for review. It works!

[choldgraf]

Thanks for this! A few quick comments in there. Also a couple points that didn’t make sense for in line comments

• is there a natural way to test for this infrastructure? Do most packages include translation testing in their test suite? Ideally without complicating things much?
• We should add in a bit more explanation about how the translation infra works - I added a few suggestions in the review. In my experience people don’t know anything about Sphinx translation so this will help get oriented

Also feel like we should get sign off from @jorisvandenbossche to make sure he’s ok with this new infra setup

[choldgraf]

Flag for @jorisvandenbossche, any reason we wouldn’t want to use templates wo the underscore? I don’t think this would affect anything downstream

[jpmckinney]

It won't affect theme users. When theme users override a template, it's based on the file's basename, not on its path within a particular theme, to my knowledge.

[choldgraf]

We should link to a useful introduction for Sphinx translation, in my experience most users don’t know how this works so I think this would helo

[jpmckinney]

I don't know that any are especially helpful. See e.g. https://www.sphinx-doc.org/en/master/usage/advanced/intl.html

[jpmckinney]

I've updated contributing.rst and accepted the suggestions. Not clear what to change in i18n.rst.

[choldgraf]

Thanks for those edits, this is looking really good. A few more relatively small comments.

[jorisvandenbossche]

Quick comment: fully on board with improving the theme in this area, assuming we follow the sphinx standard practices (and @jpmckinney thanks a lot for working on this!)
Will try to take a more detailed look in one of the coming days

[jpmckinney]

is there a natural way to test for this infrastructure? Do most packages include translation testing in their test suite? Ideally without complicating things much?

Different projects do different things.

• If you want every PR to always be 100% translated, you can add a test using pocount --incomplete *.po to ensure there are no untranslated strings.
• If you want to ensure the POT file is up-to-date, you can have the tests run python setup.py extract_messages --omit-header --no-location and check for changes. Without --omit-header, the POT-Creation-Date will be updated by the test, causing a failure. Without --no-location, whenever lines are added to templates before translatable strings, the #: source code reference lines in the POT file will go out of date, causing a failure.
• If you want to ensure the PO files are up-to-date, you can have the tests run python setup.py update_catalog --omit-header and check for changes.

Alternately, you can decide to do the translations steps before a release only.

[choldgraf]

Hey all - I think that this PR is an important improvement in the theme, and we don't want it to go unresolved indefinitely. Since we've already got a lot of iteration here, and since @jpmckinney has put a lot of time into this already. I suggest we go with the following steps:

1. @jpmckinney rebases and resolves merge conflicts.
2. We leave this PR open for 48 hours to see if there are any objections to merging it.
3. We merge the PR and spot-check other i18n improvements in other issues.

@jpmckinney would you be willing to do no. 1? Sorry that this one has gone stale!

[jpmckinney]

Restarted at #1192.