Language Switcher

[sneakers-the-rat]

Seems related to prior issues/prs:

• Put the ReadTheDocs version switcher in the header navbar #705
• extend version switcher to include language switching #507
• Add language and version switcher feature #2193

Opening this on request: @lwasser let me know that @trallard may be interested in using the language switch from pyopensci?

That's here: pyOpenSci/python-package-guide#394

and live at: https://www.pyopensci.org/python-package-guide/index.html#
(e.g. https://www.pyopensci.org/python-package-guide/ja/index.html# )

Our switcher was designed for our docs and their build process relatively specifically, but here is the strategy for the purposes of seeing what would need to be done to implement it here:

• There isn't a way to make a <select> element behave like a link with basic HTML5, so some javascript is needed to make it work
• However, to keep the JS light, I made most of the logic of the implementation happen at build time, where the URLs that correspond to the versions of the current page in different languages are embedded in the value attribute of the <option> elements.
• This value is computed from the html_baseurl - that is a little problematic in cases where e.g. preview copies of the docs are built that aren't located at that canonical location. For development, we just use / as the base, which makes it possible to work on all the languages equivalently.
• We have a distinction between "languages" and "release languages" in our docs, where the languages are all the languages that have any translations/have their .po files generated, and "release languages" are those that are public on the site. That's not a standard sphinx config variable and i am not sure if there is some existing standard way to define it.
• Then a lot of the build part takes place in our noxfile, so that would definitely need to be altered. The basic issue is that each language needs to be build separately, but all versions need to know about each of the other languages, and each needs to end up in the expected place. We have en as a special case in ours, since we already had the documentation online at pyopensci.org/python-package-guide we didn't want to break inbound links by putting it at pyopensci.org/python-package-guide/en/, but that does introduce a little bit of complexity where we can't just swap the language code in the url (hence why we use absolute URLs, since it otherwise would not be clear what the path segment would be for the page in another language).

We build our docs with gh actions and deploy to our own domain, but i also am not sure how this would work with the readthedocs language switcher. Presumably we would be able to detect when we are being built by rtd and thus be able to adapt to its url structure, but it would require a bit of tinkering i think.

Anyway, I don't claim that ours is the best possible implementation, but it does exist, and i'm happy to help adapt it to be more general and available. it seems like an odd gap in the i18n tech for sphinx. I also see @tkoyama010 mentioning mini18n which looks like it can do this already, which uses some sphinx template functions i wasn't aware of at the time, so we could also incorporate that too!

[lwasser]

Hey there @trallard this is the beginning of the discussion around the language selector that we are using in our packaging guide that @sneakers-the-rat created for us ✨

[trallard]

Thanks for opening this! I will need some time to review what is being done at PyOpenSci and in mini18n, as it seems there are two main things to be considered:

1. Adding the language switcher component (similar to the version switcher)
2. The build of the docs HTML per existing (or deployable) language (and therefore ensuring these are appropriately passed to/displayed on the language switcher (component)