[GH-2867] Replace EN/中文 pill with 文A icon dropdown in header#2923
Merged
jiayuasu merged 3 commits intoapache:masterfrom May 8, 2026
Merged
[GH-2867] Replace EN/中文 pill with 文A icon dropdown in header#2923jiayuasu merged 3 commits intoapache:masterfrom
jiayuasu merged 3 commits intoapache:masterfrom
Conversation
Follow-up polish to the i18n scaffolding (apache#2920) and landing-pages translation (apache#2922). The earlier inline pill switcher visually crowded mike's version dropdown rendered into the header title. Move the language selector to a single trigger in the right-part of the header that, on click, opens a small native <details> popover listing the available locales. - The trigger is a typographic glyph: literal `文` next to a smaller superscript `A`, set in the system Han + Latin font stack so it scales cleanly at any size and never depends on rasterized icon weights. - The popover is white-on-shadow with the active locale (auto-detected via mkdocs-static-i18n's `config.theme.language`) highlighted in brand red. - Each menu link keeps `target="_self"` so mkdocs-material's navigation.instant skips it and the full page reloads (which is required for the active-state highlight in the dropdown to repaint). - Locale `name` shortened from "English" to "EN" so both menu items read as locale codes / native script ("EN" and "中文") rather than a mix of language names and codes. - The right-part location keeps the switch clear of the left-part's site title + mike version dropdown at every viewport width. The CSS-only `<details>` element gives keyboard, screen-reader, and click-outside-to-close behavior for free with no JS.
Now that the trigger is an icon rather than a text label, the menu items can be the readable language names instead of the locale code. Restore the `English` name; `中文` already uses native script.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the documentation site header language selector for the mkdocs-material + mkdocs-static-i18n setup by replacing the inline EN | 中文 “pill” with a compact 文A trigger that opens a <details>-based dropdown, reducing header crowding at narrow widths.
Changes:
- Shorten the English locale display name from
EnglishtoENinmkdocs.yml. - Reposition the language selector into the header’s right-side control group.
- Replace the inline language links with a
<details>/<summary>dropdown and update styling accordingly.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| mkdocs.yml | Changes the English locale label to EN so the switcher displays compact codes. |
| docs-overrides/partials/header.html | Moves the language selector include into the right-side header container. |
| docs-overrides/partials/alternate.html | Implements the new <details> dropdown trigger and menu markup for locale links. |
| docs-overrides/assets/stylesheets/components/_lang-switch.scss | Restyles the language switcher to match the new dropdown interaction and glyph trigger. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+6
to
+19
| <ul class="sd-lang-switch__menu" role="menu"> | ||
| {% for alt in config.extra.alternate %} | ||
| {%- set is_active = (alt.lang == config.theme.language) -%} | ||
| <li role="none"> | ||
| <a | ||
| href="{{ alt.link | url }}" | ||
| hreflang="{{ alt.lang }}" | ||
| lang="{{ alt.lang }}" | ||
| target="_self" | ||
| role="menuitem" | ||
| class="sd-lang-switch__link{% if is_active %} sd-lang-switch__link--active{% endif %}" | ||
| {% if is_active %}aria-current="true"{% endif %} | ||
| >{{ alt.name }}</a> | ||
| </li> |
Comment on lines
+96
to
+98
| // Close the dropdown when clicking outside — relies on the click-away | ||
| // hint via `tabindex` on the body and `:focus-within`. Native <details> | ||
| // stays open until summary is clicked again, which is acceptable. |
- Drop role="menu" / role="menuitem" from the dropdown markup. The list is a small set of plain navigation links, not a true menu widget, and the ARIA menu role implies arrow-key handling we don't implement. Native <a> + <li> semantics are correct here. - Rewrite the trailing comment in _lang-switch.scss to describe what actually happens (native <details> stays open until summary is toggled, which is acceptable) instead of referring to a click-away implementation that doesn't exist.
Member
Author
|
Addressed in dcc13f3:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Did you read the Contributor Guide?
Is this PR related to a ticket?
[GH-XXX] my subject. Follow-up polish to EPIC Add Chinese version of the documentation #2867 (after [GH-2867] Wire mkdocs-static-i18n for Chinese documentation #2920 / [GH-2909] Translate documentation landing pages to Chinese #2922).What changes were proposed in this PR?
The pill switcher introduced in #2922 (
EN | 中文rendered inline in the header) visually crowded the mike version dropdown rendered into the site title at narrower viewport widths. This PR moves the language selector to a single trigger in the right-part of the header that, on click, opens a small native<details>popover listing the available locales.文next to a smaller superscriptA, set in the system Han + Latin font stack so it scales cleanly at any size and never depends on rasterized icon weights.config.theme.language) highlighted in brand red.target="_self"so mkdocs-material'snavigation.instantskips it and the full page reloads — required for the active-state highlight in the dropdown to repaint after the user clicks across locales.nameshortened from "English" to "EN" inmkdocs.ymlso both menu items read as locale codes / native script (ENand中文) rather than a mix of language names and codes.The CSS-only
<details>element gives keyboard, screen-reader, and click-outside-to-close behavior for free with no JS dependency.How was this patch tested?
Built and served the docs locally with
npx --prefix docs-overrides gulp build && uv run mkdocs serve. Verified:文Atrigger appears in the right-part of the header on every page in both/and/zh/builds.ENand中文; the active locale is highlighted in red.target="_self"); the highlight repaints correctly in both directions (/↔/zh/)..md-header__topicat any viewport width tested (down to ~360px).Did this PR include necessary documentation updates?