Add localization metadata (#1681)

Author: TheTripleV

source/_extensions/localization.py

@@ -0,0 +1,47 @@
+from typing import Any, Dict
+
+import docutils.nodes as nodes
+from sphinx.application import Sphinx
+
+
+def make_tag(language: str, link: str) -> str:
+    return f'<link rel="alternate" hreflang="{language}" href="{link}" />'
+
+
+def html_page_context(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: Dict[str, Any],
+    doctree: nodes.document,
+) -> None:
+    if not doctree:
+        return
+    language = app.config.language or "en"
+    localization_languages = app.config.localization_languages
+
+    pageurl: str = context["pageurl"]
+
+    tags = []
+    for localization_language in localization_languages:
+        local_pageurl = pageurl.replace(
+            f"/{language}/", f"/{localization_language}/", 1
+        )
+
+        tags.append(make_tag(localization_language.replace("_", "-"), local_pageurl))
+
+        if localization_language == "en":
+            tags.append(make_tag("x-default", local_pageurl))
+
+    context["metatags"] += "\n" + "\n".join(tags)
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_config_value("localization_languages", [], "html")
+
+    app.connect("html-page-context", html_page_context)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

source/conf.py

@@ -57,6 +57,7 @@
 
 local_extensions = [
     "_extensions.post_process",
+    "_extensions.localization",
 ]
 
 extensions += local_extensions
@@ -76,6 +77,17 @@
 versionwarning_banner_title = "Warning!"
 versionwarning_body_selector = 'div[class="document"]'
 
+# List of languages that frc-docs supports
+localization_languages = [
+    "en",
+    "es",
+    "fr",
+    "he",
+    "pt",
+    "tr",
+    "zh_CN",
+]
+
 # Redirect branch
 rediraffe_branch = "origin/main"
 
@@ -89,7 +101,7 @@
 linkcheckdiff_branch = "origin/main"
 
 # Configure OpenGraph support
-ogp_site_url = "https://docs.wpilib.org/en/latest/"
+ogp_site_url = "https://docs.wpilib.org/en/stable/"
 ogp_site_name = "FIRST Robotics Competition Documentation"
 ogp_image = (
     "https://raw.githubusercontent.com/wpilibsuite/branding/main/png/wpilib-128.png"
@@ -184,7 +196,7 @@
 
 # Specify canonical root
 # This tells search engines that this domain is preferred
-html_baseurl = "https://docs.wpilib.org/"
+html_baseurl = "https://docs.wpilib.org/en/stable/"
 
 html_theme_options = {
     "collapse_navigation": True,