Site language selector

[vincentbesanceney]

From what I see in src/partials/header.html, the theme already supports this feature, but it doesn't seem to be configurable from theme options. I tested a change to the theme to make language selection available from customization, adding alternate languages just as it is done in the mkdocs material theme. Is this the way to go or do you favor another option?

[2bndy5]

I suppose we could add support for this in our config (html_theme_options['extra']['alternative']).

If you're using ReadTheDocs, then the language can be selected via the RTD floating drop-down menu: https://docs.readthedocs.io/en/stable/localization.html

[2bndy5]

I'm not particularly happy with the config html_theme_options['extra']['alternative'] as it isn't an obvious name for such an option. I would probably add a key named languages that takes a list of maps as similarly used upstream:

html_theme_options = {
    "languages": [
        {
            "name": "English",
            "lang": "en",
            "link": "en/",
        },
        {
            "name": "French",
            "lang": "fr",
            "link": "fr/",
        },
    ]
}

[2bndy5]

Customizing the icon should probably get a different key as well.

In upstream config

theme:
  icon:
    alternate: material/translate

In our config

html_theme_options = {
    "icon": {
        "languages": "material/translate",
    }
}

[2bndy5]

On second thought, It would be easier (for development) to customize the icon using the same key used upstream.

html_theme_options = {
    "icon": {
        "alternate": "material/translate",
    }
}

[2bndy5]

I started a branch called lang-drop-down that has the added config to support this, but it needs documentation. Initial attempt worked with the following config:

html_theme_options = {
    "languages": [
        {
            "name": "English",
            "lang": "en",
            "link": "en/",
        },
        {
            "name": "French",
            "lang": "fr",
            "link": "fr/",
        },
    ],
    "icon": {
        "alternate": "fontawesome/solid/language",
    }
}

[2bndy5]

This feature is available from nightly build on test-pypi. I will post again when we release to actual pypi index.

[2bndy5]

Feature available in v0.11.8.