fix(docs): sync i18n build infrastructure from es branch

Author: jiangjiawei

doc/build_i18n.py

@@ -10,6 +10,13 @@
 
 from i18n_locales import KNOWN_LOCALES, resolve_sphinx_language
 
+try:
+    import babel  # noqa: F401
+
+    HAS_BABEL = True
+except ImportError:
+    HAS_BABEL = False
+
 DOC_DIR = Path(__file__).resolve().parent
 LOCALE_DIR = DOC_DIR / "source" / "locale"
 
@@ -64,21 +71,6 @@ def _build_mo_with_sphinx_intl(locale: str) -> bool:
     return True
 
 
-def _babel_available() -> bool:
-    try:
-        import babel  # noqa: F401
-
-        return True
-    except ImportError:
-        return False
-
-
-def _build_locale(locale: str, *, has_babel: bool) -> bool:
-    if has_babel:
-        return build_mo(locale)
-    return _build_mo_with_sphinx_intl(locale)
-
-
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
@@ -93,25 +85,31 @@ def main(argv: list[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
 
-    has_babel = _babel_available()
-
     if args.all:
-        built: list[str] = []
-        for loc in KNOWN_LOCALES:
-            if not _messages_dir(loc).is_dir():
-                continue
-            if _build_locale(loc, has_babel=has_babel):
-                built.append(loc)
-        if not built:
-            print("[build_i18n] no locale directories found")
+        if HAS_BABEL:
+            built = [loc for loc in KNOWN_LOCALES if build_mo(loc)]
+            if not built:
+                print("[build_i18n] no locale directories found")
+        else:
+            print(
+                "[build_i18n] babel not installed, falling back to sphinx-intl "
+                "for all locales...",
+                flush=True,
+            )
+            for loc in KNOWN_LOCALES:
+                if _messages_dir(loc).is_dir():
+                    _build_mo_with_sphinx_intl(loc)
         return 0
 
     locale = resolve_sphinx_language(explicit=args.locale)
     if not locale:
         print("[build_i18n] English build; skipping mo compilation")
         return 0
 
-    _build_locale(locale, has_babel=has_babel)
+    if HAS_BABEL:
+        build_mo(locale)
+    else:
+        _build_mo_with_sphinx_intl(locale)
     return 0
 
 

doc/i18n_locales.py

@@ -29,9 +29,9 @@ def resolve_sphinx_language(
     explicit: str | None = None,
 ) -> str | None:
     """Return Sphinx ``language`` config value, or ``None`` for English."""
-    if explicit:
-        return explicit
-    slug = (rtd_language or os.environ.get("READTHEDOCS_LANGUAGE") or "").strip().lower()
-    if not slug or slug == "en":
+    slug = (
+        explicit or rtd_language or os.environ.get("READTHEDOCS_LANGUAGE") or ""
+    ).strip().lower()
+    if not slug or slug == "en" or slug.startswith(("en-", "en_")):
         return None
     return RTD_TO_SPHINX_LOCALE.get(slug, slug.replace("-", "_"))

doc/source/conf.py

@@ -149,17 +149,24 @@ def _compile_mo_catalog(locale: str) -> None:
     """Compile .po -> .mo when catalogs are missing or stale."""
     if not _locale_po_files(locale):
         return
-    subprocess.run(
-        [sys.executable, str(_doc_root / "build_i18n.py"), locale],
-        cwd=str(_doc_root),
-        check=True,
-    )
+    try:
+        subprocess.run(
+            [sys.executable, str(_doc_root / "build_i18n.py"), locale],
+            cwd=str(_doc_root),
+            check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as exc:
+        print(
+            f"[sphinx] warning: failed to compile locale/{locale} catalogs "
+            f"({exc}); continuing with existing .mo files if any",
+            flush=True,
+        )
 
 
 if _sphinx_language and _needs_mo_compile(_sphinx_language):
     _compile_mo_catalog(_sphinx_language)
 
-if version_match == "zh-cn" or _sphinx_language == "zh_CN":
+if version_match == 'zh-cn' or _sphinx_language == "zh_CN":
     tags.add("zh_cn")
 
 
@@ -205,20 +212,7 @@ def _resolve_switcher_version(app):
 }
 
 
-def _apply_switcher_theme_options(theme_options: dict, switcher_version: str) -> None:
-    """Apply locale-specific PyData theme options from one place."""
-    switcher = theme_options.setdefault("switcher", {})
-    switcher.setdefault("json_url", json_url)
-    switcher["version_match"] = switcher_version
-    theme_options["external_links"] = [
-        _EXTERNAL_LINKS_BY_LOCALE.get(switcher_version, _DEFAULT_EXTERNAL_LINK)
-    ]
-    theme_options["header_dropdown_text"] = _HEADER_DROPDOWN_TEXT_BY_LOCALE.get(
-        switcher_version, "More"
-    )
-
-
-if version_match != "zh-cn":
+if version_match != 'zh-cn':
     html_theme_options['icon_links'].extend([{
         "name": "Discord",
         "url": "https://discord.gg/Xw9tszSkr5",
@@ -240,16 +234,27 @@ def _apply_switcher_theme_options(theme_options: dict, switcher_version: str) ->
         "type": "fontawesome",
     }])
 
-_apply_switcher_theme_options(html_theme_options, version_match)
+html_theme_options["external_links"] = [
+    _EXTERNAL_LINKS_BY_LOCALE.get(version_match, _DEFAULT_EXTERNAL_LINK)
+]
+html_theme_options["header_dropdown_text"] = _HEADER_DROPDOWN_TEXT_BY_LOCALE.get(
+    version_match, "More"
+)
 
 html_favicon = "_static/xinference-favicon.png"
 
 
 def _apply_locale_theme_options(app, config):
     switcher_version = _resolve_switcher_version(app)
-    _apply_switcher_theme_options(config.html_theme_options, switcher_version)
+    config.html_theme_options.setdefault("switcher", {})["version_match"] = switcher_version
+    config.html_theme_options["external_links"] = [
+        _EXTERNAL_LINKS_BY_LOCALE.get(switcher_version, _DEFAULT_EXTERNAL_LINK)
+    ]
+    config.html_theme_options["header_dropdown_text"] = (
+        _HEADER_DROPDOWN_TEXT_BY_LOCALE.get(switcher_version, "More")
+    )
     if switcher_version == "zh-cn":
-        config.tags.add("zh_cn")
+        app.tags.add("zh_cn")
 
 
 def _remove_non_zh_cn_nodes(app, doctree, docname):