From 10548d24e720b3064e55a7b60908931535e190d9 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 8 Jul 2026 22:49:00 +0000
Subject: [PATCH] feat: improve language switcher accessibility and JS
 compatibility

- Add `lang` and `hreflang` attributes to the language switcher links.
- Add `data-lang` attribute to the language switcher links.
- Add `id="lang-toggle"` to the `<nav>` container for JS compatibility.
- Added a journal entry for the Palette persona documenting these findings.

Co-authored-by: divineforge <1146195+divineforge@users.noreply.github.com>
---
 .Jules/palette.md                  |  3 +++
 layouts/partials/header/basic.html | 28 +++++++++++++++++++++++-----
 2 files changed, 26 insertions(+), 5 deletions(-)
 create mode 100644 .Jules/palette.md

diff --git a/.Jules/palette.md b/.Jules/palette.md
new file mode 100644
index 0000000..35179af
--- /dev/null
+++ b/.Jules/palette.md
@@ -0,0 +1,3 @@
+## 2025-02-27 - Language Switcher Accessibility and JS Compatibility
+**Learning:** Multilingual websites must include `hreflang` and `lang` attributes on language switcher links. Without these, screen readers won't apply the correct pronunciation profiles for the target languages. Furthermore, the `static/js/language-toggle.js` script requires the container to have `id="lang-toggle"` and the links to have a `data-lang` attribute matching the language code (`{{ .Language.Lang }}`) to store and apply user language preferences.
+**Action:** When implementing or updating language toggle navigation, always verify that `lang`, `hreflang`, and `data-lang` attributes are present on the links, and the correct container `id` is applied to ensure both robust accessibility and script compatibility.
\ No newline at end of file
diff --git a/layouts/partials/header/basic.html b/layouts/partials/header/basic.html
index fef4c6c..817d7f4 100644
--- a/layouts/partials/header/basic.html
+++ b/layouts/partials/header/basic.html
@@ -6,6 +6,7 @@
   (dict "key" "library" "path" "library")
 }}
 
+
 <header class="gzen-header">
   <a class="gzen-brand" href="{{ "" | relLangURL }}" aria-label="{{ .Site.Title }}">
     <span class="gzen-brand-mark" aria-hidden="true">善</span>
@@ -24,15 +25,27 @@
         {{ i18n "nav_ecosystem" | default "生态" }} <span class="gzen-dropdown-arrow">▾</span>
       </button>
       <div class="gzen-nav-dropdown-menu" role="menu">
-        <a href="{{ .Site.Params.ecosystem.ki | default "https://ki.gzen.io" }}" target="_blank" rel="noopener" role="menuitem">
+        <a
+          href="{{ .Site.Params.ecosystem.ki | default "https://ki.gzen.io" }}"
+          target="_blank"
+          rel="noopener"
+          role="menuitem">
           <strong>ki.gzen.io</strong>
           <span>{{ i18n "ecosystem_ki_title" | default "机与器" }}</span>
         </a>
-        <a href="{{ .Site.Params.ecosystem.learn | default "https://learn.gzen.io" }}" target="_blank" rel="noopener" role="menuitem">
+        <a
+          href="{{ .Site.Params.ecosystem.learn | default "https://learn.gzen.io" }}"
+          target="_blank"
+          rel="noopener"
+          role="menuitem">
           <strong>learn.gzen.io</strong>
           <span>{{ i18n "ecosystem_learn_title" | default "知与学" }}</span>
         </a>
-        <a href="{{ .Site.Params.ecosystem.invest | default "https://invest.gzen.io" }}" target="_blank" rel="noopener" role="menuitem">
+        <a
+          href="{{ .Site.Params.ecosystem.invest | default "https://invest.gzen.io" }}"
+          target="_blank"
+          rel="noopener"
+          role="menuitem">
           <strong>invest.gzen.io</strong>
           <span>{{ i18n "ecosystem_invest_title" | default "资与财" }}</span>
         </a>
@@ -40,12 +53,17 @@
     </div>
   </nav>
 
-
   {{ if .IsTranslated }}
-    <nav class="gzen-languages" aria-label="{{ i18n "read_in" | default "Languages" }}">
+    <nav
+      class="gzen-languages"
+      id="lang-toggle"
+      aria-label="{{ i18n "read_in" | default "Languages" }}">
       {{ range sort .AllTranslations "Language.Weight" }}
         <a
           href="{{ .RelPermalink }}"
+          lang="{{ .Language.Lang }}"
+          hreflang="{{ .Language.Lang }}"
+          data-lang="{{ .Language.Lang }}"
           {{ if eq .Language.Lang $.Site.Language.Lang }}aria-current="page"{{ end }}>
           {{ .Language.Params.displayName | default .Language.LanguageName | default .Language.Lang }}
         </a>