Include languages' translated names in the switcher (#245)

Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: Rafael Fontenelle <[email protected]>
Co-authored-by: W. H. Wang <[email protected]>

Author: 4 people

build_docs.py

@@ -196,6 +196,7 @@ def __gt__(self, other):
 class Language:
     iso639_tag: str
     name: str
+    translated_name: str
     in_prod: bool
     sphinxopts: tuple
     html_only: bool = False
@@ -204,6 +205,12 @@ class Language:
     def tag(self):
         return self.iso639_tag.replace("_", "-").lower()
 
+    @property
+    def switcher_label(self):
+        if self.translated_name:
+            return f"{self.name} | {self.translated_name}"
+        return self.name
+
     @staticmethod
     def filter(languages, language_tags=None):
         """Filter a sequence of languages according to --languages."""
@@ -388,7 +395,7 @@ def setup_switchers(
     - Cross-link various languages in a language switcher
     - Cross-link various versions in a version switcher
     """
-    language_pairs = sorted((l.tag, l.name) for l in languages if l.in_prod)
+    language_pairs = sorted((l.tag, l.switcher_label) for l in languages if l.in_prod)
     version_pairs = [(v.name, v.picker_label) for v in reversed(versions)]
 
     switchers_template_file = HERE / "templates" / "switchers.js"
@@ -1151,13 +1158,15 @@ def parse_languages_from_config() -> list[Language]:
     """Read config.toml to discover languages to build."""
     config = tomlkit.parse((HERE / "config.toml").read_text(encoding="UTF-8"))
     defaults = config["defaults"]
+    default_translated_name = defaults.get("translated_name", "")
     default_in_prod = defaults.get("in_prod", True)
     default_sphinxopts = defaults.get("sphinxopts", [])
     default_html_only = defaults.get("html_only", False)
     return [
         Language(
             iso639_tag=iso639_tag,
             name=section["name"],
+            translated_name=section.get("translated_name", default_translated_name),
             in_prod=section.get("in_prod", default_in_prod),
             sphinxopts=section.get("sphinxopts", default_sphinxopts),
             html_only=section.get("html_only", default_html_only),

config.toml

@@ -1,5 +1,12 @@
+# name:            the English name for the language.
+# translated_name: the 'local' name for the language.
+# in_prod:         If true, include in the language switcher.
+# html_only:       If true, only create HTML files.
+# sphinxopts:      Extra options to pass to SPHINXOPTS in the Makefile.
+
 [defaults]
 # name has no default, it is mandatory.
+translated_name = ""
 in_prod = true
 html_only = false
 sphinxopts = [
@@ -13,6 +20,7 @@ name = "English"
 
 [languages.es]
 name = "Spanish"
+translated_name = "español"
 sphinxopts = [
     '-D latex_engine=xelatex',
     '-D latex_elements.inputenc=',
@@ -21,6 +29,7 @@ sphinxopts = [
 
 [languages.fr]
 name = "French"
+translated_name = "français"
 sphinxopts = [
     '-D latex_engine=xelatex',
     '-D latex_elements.inputenc=',
@@ -29,13 +38,16 @@ sphinxopts = [
 
 [languages.id]
 name = "Indonesian"
+translated_name = "Indonesia"
 in_prod = false
 
 [languages.it]
 name = "Italian"
+translated_name = "italiano"
 
 [languages.ja]
 name = "Japanese"
+translated_name = "日本語"
 sphinxopts = [
     '-D latex_engine=lualatex',
     '-D latex_elements.inputenc=',
@@ -59,6 +71,7 @@ sphinxopts = [
 
 [languages.ko]
 name = "Korean"
+translated_name = "한국어"
 sphinxopts = [
     '-D latex_engine=xelatex',
     '-D latex_elements.inputenc=',
@@ -68,20 +81,25 @@ sphinxopts = [
 
 [languages.pl]
 name = "Polish"
+translated_name = "polski"
 
 [languages.pt_BR]
 name = "Brazilian Portuguese"
+translated_name = "Português brasileiro"
 
 [languages.tr]
 name = "Turkish"
+translated_name = "Türkçe"
 
 [languages.uk]
 name = "Ukrainian"
+translated_name = "українська"
 in_prod = false
 html_only = true
 
 [languages.zh_CN]
 name = "Simplified Chinese"
+translated_name = "简体中文"
 sphinxopts = [
     '-D latex_engine=xelatex',
     '-D latex_elements.inputenc=',
@@ -90,6 +108,7 @@ sphinxopts = [
 
 [languages.zh_TW]
 name = "Traditional Chinese"
+translated_name = "繁體中文"
 sphinxopts = [
     '-D latex_engine=xelatex',
     '-D latex_elements.inputenc=',