Languages

Embrace global audiences with multilingual support.

---

Shibuya supports multilingual documentation, allowing you to provide content in multiple languages. You can configure the supported languages by using the html_context option in your Sphinx configuration file (conf.py).

Configuration

The html_context option allows you to define a list of languages, each represented by a tuple containing the language name, URL pattern, and locale code. Here’s an example configuration:

conf.py

html_context = {
    "languages": [
        ("English", "/en/%s/", "en"),
        ("中文", "/zh/%s/", "zh"),
    ]
}

You can add more languages by including additional tuples in the languages list.

Note

%s will be replaced by current page URL.

Examples

A real example: https://jose.authlib.org/en/dev/

Country flag in language name:

conf.py

html_context = {
    "languages": [
        ("🇺🇸 English", "/en/%s/", "en"),
        ("🇨🇳 中文", "/zh/%s/", "zh"),
    ]
}

Using full URL pattern:

conf.py

html_context = {
    "languages": [
        ("English", "https://en.example.com/%s/", "en"),
        ("中文", "https://zh.example.com/%s/", "zh"),
    ]
}

Using URL pattern endswith .html:

conf.py

html_context = {
    "languages": [
        ("English", "/en/%s.html", "en"),
        ("中文", "/zh/%s.html", "zh"),
    ]
}

If you prefer not to use a dynamic URL pattern and instead want to directly navigate users to the homepage of the specific language, you can configure the language settings as (Language Name, URL pattern):

conf.py

html_context = {
    "languages": [
        ("English", "/en/"),
        ("中文", "/zh/"),
    ]
}

This configuration simplifies the URL structure by removing the %s dynamic parameter and eliminates the inclusion of the locale code and alternative hreflang links.