Multilingual websites

[Bisaloo]

Hi,

I'd like with this issue start a conversation about supporting pkgdown websites in multiple languages side-by-side. Last year, pkgdown has started to translate all the text it generates, making it easier to provide pkgdown website in languages other than English.

But providing documentation in more than one language remains challenging. Current attempts that I'm aware of hack their way around it by twisting the mode feature. It remains imperfect because the resulting sitemap is incomplete and language can't be automatically selected based on browser standard mechanisms.

Multilingual websites are available in other documentation generators such as mkdocs or readthedocs.

Here is some steps summarizing how multilingual sites could be achieved in pkgdown:

• render default website at the root of the docs/ folder
• render extra language websites in subfolders (es/, fr/, etc.)
• tweak the sitemap at the root of the site to indicate alternative versions of each page: https://developers.google.com/search/docs/specialty/international/localized-versions#sitemap
• add a switcher to allow users to manually change the page language

There should also be a mechanism to automatically detect which version of the README / vignettes should be rendered based on the value of lang. Other tools use a mechanism based on the detection of .fr.md, .es.md, etc. file extensions.

I've been considering whether this should be in pkgdown, or as an extension package but I became convinced it should be part of the main package because it will likely need to re-use some pkgdown internals, especially to create the modified sitemap.

I'm also not sure if all of this should be configured in _pkgdown.yml or if users who want a multilingual website should call a separate build_multilingual_site() wrapper function.