Add language switcher support for fa, fr and zh-cn editions by mmcky · Pull Request #490 · QuantEcon/lecture-python-programming

mmcky · 2026-03-23T04:17:54Z

Changes

Add the language switcher configuration to html_theme_options in lectures/_config.yml:

Code	Name	URL
`en`	English	https://python-programming.quantecon.org
`fa`	فارسی	https://quantecon.github.io/lecture-python-programming.fa
`fr`	Français	https://quantecon.github.io/lecture-python-programming.fr
`zh-cn`	中文	https://quantecon.github.io/lecture-python-programming.zh-cn

with current_language: en. This enables the language switcher globe icon in the bottom toolbar and injects SEO hreflang tags for all configured languages.

Languages are ordered alphabetically by code after English. English stays first because the theme uses languages[0] as the hreflang x-default target.

French

French was deliberately left out when this PR was first opened, because .fr had no published site and its URL would have been a guess. Both conditions have since been resolved: the .fr edition went live on 2026-07-17 at the default Pages URL with no custom domain, which settles the Deferred item on the rollout tracker QuantEcon/project-translation#3 — the one that said to decide the Pages URL before wiring the switcher. French is therefore included here rather than left to a follow-up.

No environment change needed

main already ships quantecon-book-theme==0.21.0 (bumped in #558), which provides the switcher. 0.21.0 is the latest release on both GitHub Releases and PyPI, so no theme upgrade is required. This branch has been rebased onto current main, so it remains a single-file _config.yml change.

Verification

Verified against quantecon-book-theme==0.21.0 with a local build using this file's html_theme_options parsed verbatim:

The switcher renders all four languages, with English carrying aria-current="true" and class="active".
The hreflang alternates inject on every page, including x-default → en.
The config keys match the theme's _process_languages(). Because the theme calls url.rstrip("/") and always appends {pagename}.html, a bare root URL is never emitted — this is why the configured URLs carry no trailing slash, per the Copilot review threads above.

Live URL checks: all four configured URLs return 200, and 26 of the 27 lecture pages resolve on each of the .fa, .fr and .zh-cn sites. The exception is polars, added recently in #408 and not yet synced to any translation edition; its switcher links and hreflang alternates will 404 until each edition picks it up.

Follow-up, not blocking

None of the .fa, .fr or .zh-cn sites currently emit a switcher or reciprocal hreflang, and all three serve <html lang="en">. hreflang annotations are most effective when bidirectional. Each of those repos already pins a theme version supporting the switcher (fa and fr on 0.21.0, zh-cn on 0.20.0), so each needs only the equivalent config block with its own current_language.

Ref: https://github.com/QuantEcon/quantecon-book-theme/releases/tag/v0.20.0

github-actions · 2026-03-23T04:25:52Z

🚀 Deployed on https://6a6fdc0f8b63b1d673c01caf--epic-agnesi-957267.netlify.app

Copilot

Pull request overview

Adds multi-language switcher configuration to the Jupyter Book theme settings so the site can link between the English, Farsi, and Simplified Chinese builds (and emit corresponding hreflang alternates).

Changes:

Adds languages entries (en, fa, zh-cn) under sphinx.config.html_theme_options.
Sets current_language: en to mark the English build as active.

mmcky · 2026-07-15T01:28:54Z

Heads-up: French now exists and this PR does not include it.

QuantEcon/lecture-python-programming.fr went live on 2026-07-15 — 26 lectures seeded, sync wired in #573. This PR was last updated 2026-06-17, before that, and its diff mentions fr zero times. Merging as-is would ship a language switcher offering Persian and Chinese but not the edition we just launched.

Not asking for a rewrite here — flagging it so the gap is a decision rather than an oversight. Two things worth knowing if French is added:

.fr has no published site yet. No cache.yml/ci.yml/publish.yml, and Pages 404s — deliberately deferred in QuantEcon/project-translation#3 pending the custom-domain question that bit .fa. So a switcher entry for French would have nowhere to point until that lands. That may be reason to keep this PR as-is and add French once the site exists.
The .fr URL will come out of that same deferred Pages/domain decision, so adding French now would mean guessing at it.

Tracked in QuantEcon/project-translation#3 (rollout) — happy to add French here once the site is published, or to leave it for a follow-up.

Add `languages` and `current_language` to `html_theme_options` to enable the language switcher (globe icon) and SEO hreflang tags provided by quantecon-book-theme. Main already ships the 0.21.0 theme, so no environment change is needed here. Languages: - English (en) — https://python-programming.quantecon.org - فارسی (fa) — https://quantecon.github.io/lecture-python-programming.fa - 中文 (zh-cn) — https://quantecon.github.io/lecture-python-programming.zh-cn Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The .fr edition went live on 2026-07-17 at the default Pages URL, with no custom domain to reconcile. That resolves the deferral recorded on this PR in July, when French was left out because the site was not yet published and its URL would have been a guess. See the rollout tracker QuantEcon/project-translation#3. Ordered alphabetically by code after English; English stays first because the theme uses languages[0] for the hreflang x-default. Verified with a local build against quantecon-book-theme 0.21.0: the switcher lists all four languages with English active, and the hreflang alternates — including x-default — inject on every page. All 26 shared lecture pages resolve on the .fr site; polars is not yet synced there, as is also the case for .fa and .zh-cn. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mmcky · 2026-08-03T00:10:47Z

French added, branch rebased, and re-validated against a fresh build.

Following up on the July heads-up above: the condition it named for deferring French no longer holds. .fr went live on 2026-07-17 at the default Pages URL with no custom domain, which settles the Deferred item on QuantEcon/project-translation#3 — the one that said to decide the Pages URL before wiring the switcher. So the URL is no longer a guess, and French is included here rather than split into a follow-up.

What changed

Rebased onto current main (it was 19 commits behind; still a clean single-file change) and added the fr entry, ordered alphabetically after fa. English stays first because the theme uses languages[0] as the hreflang x-default target.

No theme upgrade needed

main pins quantecon-book-theme==0.21.0, and that is the latest release on both GitHub Releases and PyPI. Nothing to bump.

Validation against the new preview

The previous Netlify preview had expired, so this was re-checked end to end on the rebuilt one. Every page carries the switcher and a complete set of five hreflang links — the four languages plus x-default → en — verified on intro, about_py, pandas, polars and status. The switcher menu lists all four languages with English marked aria-current="true" and class="active".

One detail worth recording: in the deployed build the English switcher link is post-processed to the extensionless form .../numpy, while the other three keep .html. Both forms return 200 on the live English site, so this is harmless — but it is only visible in a real build, not in an isolated theme render.

Live URL checks: all four configured URLs return 200. Of the 27 lecture pages, 26 resolve on each of .fa, .fr and .zh-cn. The exception is polars, added in #408 and not yet synced to any translation edition, so its switcher links and hreflang alternates will 404 until each edition picks it up. That resolves itself through the normal sync.

Follow-up, not blocking this PR

None of the three translation sites currently emit a switcher or reciprocal hreflang; all three serve <html lang="en">. hreflang is most effective when the annotations are bidirectional, so the switcher is one-directional until they reciprocate. Each of those repos already pins a theme version that supports it — .fa and .fr on 0.21.0, .zh-cn on 0.20.0 — so each needs only the equivalent config block with its own current_language.

mmcky · 2026-08-03T01:08:50Z

Correcting the polars note above. I wrote that polars was "not yet synced to any translation edition" and would "resolve itself through the normal sync." Both halves are wrong, and the correction changes what needs doing.

polars was synced the day it landed. The PRs merged into all three editions within an hour of each other on 2026-07-30 — .fa#144, .fr#20, .zh-cn#79 — and polars.md plus its _toc.yml entry are present in all four repositories now, English included.

The 404s are publish cadence. Every repo in this series publishes only when someone pushes a publish* tag, and none has been pushed since polars merged. The English source is 18 days stale (last tag 2026-07-16, with three lecture-affecting commits on main since), .fr 17 days, .fa and .zh-cn 45 days each. So python-programming.quantecon.org/polars.html 404s for the same reason the translated ones do — this is not a translation gap at all, and no amount of syncing fixes it.

Practical consequence for this PR: unchanged, still fine to merge. But the switcher will advertise polars in four languages and all four will 404 until publish tags go out — and the English one is the first that needs it, since it is the site the switcher is being added to.

Tracked as QuantEcon/action-translation#239, which asks for a scheduled check so this condition is detected rather than found by hand.

Mirrors QuantEcon/lecture-python-programming#490, which adds the same block to the English source. Lists all four editions with current_language set to fa so this edition renders as active, and injects the hreflang alternates for the set. English stays first in the list because the theme uses languages[0] as the hreflang x-default target. Verified with a local build against the theme: the switcher lists all four languages with fa active. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Mirrors QuantEcon/lecture-python-programming#490, which adds the same block to the English source. Lists all four editions with current_language set to fr so this edition renders as active, and injects the hreflang alternates for the set. English stays first in the list because the theme uses languages[0] as the hreflang x-default target. Verified with a local build against the theme: the switcher lists all four languages with fr active. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Mirrors QuantEcon/lecture-python-programming#490, which adds the same block to the English source. Lists all four editions with current_language set to zh-cn so this edition renders as active, and injects the hreflang alternates for the set. English stays first in the list because the theme uses languages[0] as the hreflang x-default target. Verified with a local build against the theme: the switcher lists all four languages with zh-cn active. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…fig (#80) * Enable the language switcher for the Chinese edition Mirrors QuantEcon/lecture-python-programming#490, which adds the same block to the English source. Lists all four editions with current_language set to zh-cn so this edition renders as active, and injects the hreflang alternates for the set. English stays first in the list because the theme uses languages[0] as the hreflang x-default target. Verified with a local build against the theme: the switcher lists all four languages with zh-cn active. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Point the site and repository URLs at this edition, not the English one Four settings were copied from the English config and never updated, so this edition advertised itself as the English site: - baseurl was https://python-programming.quantecon.org/, making every page emit a canonical and og:url declaring it a duplicate of the corresponding English page - repository_url sent "View Source" to the English repository - nb_repository_url pointed at the English notebooks - both tojupyter paths resolved notebook and image links to the English site baseurl and the tojupyter paths now use this edition's GitHub Pages address, which is where it is hosted while the broader URL structure is decided. repository_url points here. nb_repository_url is dropped rather than repointed, since no zh-cn notebooks repository exists; this mirrors the comment the fr edition already uses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Enable the language switcher for the Farsi edition Mirrors QuantEcon/lecture-python-programming#490, which adds the same block to the English source. Lists all four editions with current_language set to fa so this edition renders as active, and injects the hreflang alternates for the set. English stays first in the list because the theme uses languages[0] as the hreflang x-default target. Verified with a local build against the theme: the switcher lists all four languages with fa active. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Point the site URLs at the GitHub Pages address actually served baseurl claimed https://python-programming-fa.quantecon.org/, a host that does not resolve, so every page emitted a canonical and og:url to a dead address while the site serves from github.io. The two tojupyter paths carried the same dead host. This edition is hosted at its GitHub Pages URL while the broader URL structure is decided, so the config now says so. Also drops nb_repository_url, which pointed at lecture-python-programming.fa.notebooks — a repository that does not exist. Mirrors the comment the fr edition already uses; the theme skips notebook-launch links when the option is unset. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Mirrors QuantEcon/lecture-python-programming#490, which adds the same block to the English source. Lists all four editions with current_language set to fr so this edition renders as active, and injects the hreflang alternates for the set. English stays first in the list because the theme uses languages[0] as the hreflang x-default target. Verified with a local build against the theme: the switcher lists all four languages with fr active. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

mmcky added the testing label Mar 23, 2026

github-actions Bot temporarily deployed to pull request March 23, 2026 04:25 Inactive

github-actions Bot temporarily deployed to pull request March 25, 2026 03:59 Inactive

Copilot AI review requested due to automatic review settings June 17, 2026 02:05

mmcky force-pushed the add-language-switcher-fa-zh-cn branch from 4c4ed45 to 4d35290 Compare June 17, 2026 02:05

mmcky changed the title ~~[TEST] Add language switcher support for fa and zh-cn repositories~~ Add language switcher support for fa and zh-cn repositories Jun 17, 2026

Copilot started reviewing on behalf of mmcky June 17, 2026 02:06 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread lectures/_config.yml

Comment thread lectures/_config.yml

Comment thread lectures/_config.yml

github-actions Bot temporarily deployed to pull request June 17, 2026 03:28 Inactive

mmcky and others added 2 commits August 3, 2026 10:00

mmcky force-pushed the add-language-switcher-fa-zh-cn branch from 4d35290 to b5f3ad1 Compare August 3, 2026 00:01

mmcky changed the title ~~Add language switcher support for fa and zh-cn repositories~~ Add language switcher support for fa, fr and zh-cn editions Aug 3, 2026

github-actions Bot temporarily deployed to pull request August 3, 2026 00:08 Inactive

mmcky mentioned this pull request Aug 3, 2026

hreflang and switcher targets can 404 with nobody noticing — add a cross-edition reachability check QuantEcon/action-translation#239

Open

mmcky merged commit 9fd7b7d into main Aug 3, 2026
5 checks passed

mmcky deleted the add-language-switcher-fa-zh-cn branch August 3, 2026 01:59

mmcky mentioned this pull request Aug 3, 2026

Add a language-aware 404 page — the switcher can link to pages an edition does not have QuantEcon/quantecon-book-theme#421

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add language switcher support for fa, fr and zh-cn editions - #490

Add language switcher support for fa, fr and zh-cn editions#490
mmcky merged 2 commits into
mainfrom
add-language-switcher-fa-zh-cn

mmcky commented Mar 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmcky commented Jul 15, 2026

Uh oh!

mmcky commented Aug 3, 2026

Uh oh!

mmcky commented Aug 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

mmcky commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

French

No environment change needed

Verification

Follow-up, not blocking

Uh oh!

github-actions Bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmcky commented Jul 15, 2026

Uh oh!

mmcky commented Aug 3, 2026

What changed

No theme upgrade needed

Validation against the new preview

Follow-up, not blocking this PR

Uh oh!

mmcky commented Aug 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mmcky commented Mar 23, 2026 •

edited

Loading

github-actions Bot commented Mar 23, 2026 •

edited

Loading