extend version switcher to include language switching

[drammock]

After #436 is merged, it would be nice if the theme also supported switching languages. The JSON file used for versions could naturally be extended to encode the info, e.g., each version entry could gain a new key like

"languages": {
    "en": "English",
    "fr": "français",
    "zh": "中文" 
}

to list which language(s) are available for that version of the docs (i.e., languages nested within versions). Alternatively the JSON could be restructured so that versions are nested within languages. Either way, the switcher dropdown will need to be adjusted to accommodate the new JSON structure and to display the version choices.

[JohnUW42]

Hi!

Could you please tell if that is correct.

Even though v0.13.0 release featured "full i18n support", there is no feature to switch from documentation prepared in one language to a documentation prepared in another language?

Does the i18n support in the v0.13.0 release only to translatable menu strings and I cannot have documentation in different languages ?

https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/i18n.html

I am looking for a solution to generate docs written in multiple languages and to switch between docs in multiple languages in their respective folders (/en/, /de/, /fr/, etc.).

Thank you!

[drammock]

there is no feature to switch from documentation prepared in one language to a documentation prepared in another language?

correct, so far nobody has found time to implement the language switcher

Does the i18n support in the v0.13.0 release only to translatable menu strings

See https://pydata-sphinx-theme.readthedocs.io/en/latest/community/topics/i18n.html

I am looking for a solution to generate docs written in multiple languages and to switch between docs in multiple languages in their respective folders

Currently this theme does not do that, although we want to support that use case. If you're interested to work on it we will happily review pull requests!

[JohnUW42]

Thank you for the response!

Sadly, I'm just an end-user, and not able to assist.

[Zc-1999]

Hello, I am currently using PyData Sphinx Theme version 0.13.3 for my Read the Docs project, which has both English and Chinese versions. I have successfully set up the Chinese version as a sub-project of the English version, but It appears that there is no translation button available. I am wondering if this issue is due to the version of the PyData Sphinx Theme that I am using. Could you please confirm whether PyData Sphinx Theme 0.13.3 supports the multi-language switch feature provided by Read the Docs? Any guidance or suggestions would be greatly appreciated. Thank you for your time and help.

[12rambau]

the switch is per se not available in the header navbar. Nevertheless it's still included in RDT flyout placed in the bottom of the left sidebar. I'm using it in this poject: https://docs.sepal.io/en/latest/setup/index.html

[CAM-Gerlach]

We're looking at getting a small chunk of NumFOCUS SDG funding to set up translation infrastructure and offer a Spanish translation of the Spyder documentation. Currently, we use a heavily customized but rather outdated fork of this theme, including our own mutli-version building and switching support (implemented prior to it being supported upstream here). While we could hack something in on top of that, for a while we've been wanting to re-baseline the site on the upstream theme with site-local customization, and upstream our custom improvements where practical and generally useful, which we're finally starting on now.

Therefore, as part of the translations project (assuming it gets funded), I'd help contribute what seems to be a pretty critical missing feature for usable translation support to this upstream theme, following the general model that was chosen here for implementing the version switcher (or whatever the maintainers advise). If funding comes in, I'd likely be able to work on this in the first trimester of next year, if it hasn't been implemented by then. I'd also look to help contribute other upstream fixes and improvements as they come up; one apparently limitation in the current version switcher vs what we'd cooked up is that it requires fully hardcoded URLs, which means it doesn't work (and cannot be tested) locally, and possibly in other deployment scenarios.

[drammock]

as part of the translations project (assuming it gets funded), I'd help contribute what seems to be a pretty critical missing feature for usable translation support to this upstream theme, following the general model that was chosen here for implementing the version switcher (or whatever the maintainers advise).

That would be wonderful. I don't think we have a consensus about how to structure the switcher (or even the underlying JSON data) to elegantly handle both languages and versions. Your (team's) input on that is welcome.

If funding comes in, I'd likely be able to work on this in the first trimester of next year, if it hasn't been implemented by then.

We're generally overstretched / short-handed, so it's likely that it will still be undone early next year.

I'd also look to help contribute other upstream fixes and improvements as they come up; one apparently limitation in the current version switcher vs what we'd cooked up is that it requires fully hardcoded URLs, which means it doesn't work (and cannot be tested) locally, and possibly in other deployment scenarios.

Well, local doc builds (via nox -s docs-live) do create a functioning version switcher, but all the links go out to the various versions of the deployed site out on the web. So I'd quibble with the phrasing "it doesn't work locally" but I get your meaning --- you can't build multiple versions locally and switch among them.

FYI we're also aware of at least one aspect of the version switcher doesn't work on PR builds: the functionality that checks whether the current page exists in the docs version you're trying to switch to. The different domains of PR builds vs the deployed site mean that CORS restrictions kick in, and any version switch initiated from a PR build site will always go to the homepage (not corresponding current page) of the selected docs version. Some users may be able to avoid this by editing their deploy-server's CORS same-origin policy (IIUC this cannot be done if deploying on RTD --- at least if it can, we haven't figured it out).

[trallard]

I am adding a note here to mention that @pradyunsg and I recently(ish) discussed translation/localisation and this item in particular.

We both want to work towards improving the whole translation story for doc sites so this might still take a while to materialise while we work on the rest of the pieces to make this happen.