[33imattei33]

Finishes ECO-179. #23 already fixed the root redirect; this PR covers what was left.

Problem

buildDocs.sh built en plus every dir under docs/locales/. docs/locales/en is a catalog dir too, so English was built twice. The nine 0%-translated locales (ar bn de fr hi ja pt ru zh) were published as well. conf.py filled the language switcher with the same scan, so it linked to all of them.

Change

• docs/locales/PUBLISHED (new) lists the translated locales to publish. Today it holds es partial.
• docs/scripts/published_locales.py (new) turns that file into the language list, English first. buildDocs.sh builds exactly that list, read once on main the same way as switcher.json. conf.py renders the switcher from the same list. A typo, a duplicate, an unknown flag or a listed en fails the build.
• Partial locales: a partial locale shows as es (partial) in the switcher. Every page in it gets a "Partial translation" banner (theme announcement) that links to the English docs.
• CI:
  • The PR check unit-tests the helper (test_published_locales.py) and checks the switcher on the en build it already does (check_published_languages.py).
  • The deploy job asserts that the built site holds only the published languages, each with the right switcher and banner, before it uploads.
• Docs: AGENTS.md and CONTRIBUTING.md now say a new locale is published by listing it in PUBLISHED, not by its catalog dir existing.

Testing (local, on this branch)

• 12 unit tests pass.
• The PR check steps pass: sphinx-build -W with no warnings and 59 pages, the asset check, the redirect test and the switcher check.
• On the old conf.py, the switcher check fails for both en and es (11 languages listed, no banner). With the fix it passes for both, 59 pages each.
• I ran the real buildDocs.sh in a throwaway clone. The log shows Publishing languages: en es, with each language built once per version. The docroot holds only en/ and es/, and the new deploy step passes on it.
• The deploy step fails if a pt/ tree is added to the docroot, and if the banner is removed from one es page.

After merge

• Live check: the acceptance checks against the live site (/pt/main/ 404; /es/main/ 200 with the banner; en built once in the deploy log) need this change on main plus a Pages deploy.
• dev switcher: /*/dev/ pages are built by dev's own conf.py, so their switcher is correct once this is merged into dev.

🤖 Generated with Claude Code