Phase 4 — Internationalisation (language switcher + hreflang)

[mmcky]

Tracks Phase 4 — Internationalisation (language switcher + hreflang) of the book-theme parity effort.

📋 Detail & checkboxes: PLAN.md → Phase 4

Scope:

• languages config ({code, name, url} list) surfaced via the site-manifest loader.
• New LanguageSwitcher.tsx (Radix dropdown) in Toolbar.tsx / MobileActionsMenu.tsx, with keyboard nav + active-language marker.
• Inject hreflang alternates (+ x-default) in root.tsx.

Renders only with 2+ languages configured. Independent of Phases 1–3; commonly shipped with Phase 5 (#RTL).

PLAN.md is the source of truth; this issue tracks status/assignment/discussion. Close when Phase 4 lands.

[mmcky]

Per the #93 resolutions (2026-08-24, recorded in PR #145): the migration scope decision is all-or-nothing — every lecture series moves at once when feature parity is complete — so this phase is now a hard cutover blocker for the lecture-series migration, not optional polish. Build order per PLAN.md sequencing: 3 → (4 → 5) → 6, with Phases 4/5 needed for the translated series. Upstreaming any of this phase's work is deferred (local-first, #93 Q1); note candidates in UPSTREAM-CANDIDATES.yml as they land.

[mmcky]

Built as #174 (stacked on #171). languages / current_language site options, a globe-icon Radix dropdown at the far end of the toolbar at every width, and hreflang alternates with x-default from the page routes' meta.

One engine fact shaped the option: the CLI drops every site.options key the template does not declare and can declare only scalar types (#173), so languages is a YAML list written inside a block string; the theme parses it and accepts a real list too. Closes when #174 merges.

[mmcky]

Shipped in #174, released in v2.6.0 (2026-09-10)

Delivered. languages (a list of code, name, url) and current_language under site.options; with two or more editions the toolbar gains a globe-icon Radix dropdown linking to the same page in each edition, the current one marked with aria-current and a check, items as real anchors with hreflang; both page routes emit <link rel="alternate" hreflang> for every edition with the first as x-default. Covered by unit tests on the parsing and URL joining and by visual assertions on the switcher, the tags and keyboard focus return.

One deviation from the scope above. The switcher renders at the far end of the toolbar at every width, not inside MobileActionsMenu: it is the one action a reader of a translated edition reaches for, so it stays out of the overflow menu, as the book theme does.

Engine constraint that shaped the option. The MyST CLI drops every site.options key the template does not declare and can declare only scalar types, so languages is a YAML list inside a block string (a real list is accepted too). The other options the theme reads but never declared are #173.

Post-review fixes before release (8ab1141): the switcher's toolbar slot is hidden when it renders nothing, so single-edition sites carry no phantom gap, with a test on the single-edition fixture.

Not yet exercised by a consumer. lecture-python-programming#363 is pinned to v2.6.0 but sets no languages; the translated editions are the first real users of this option.