# Static-site navigation localization

The website publishes every book edition in one MkDocs build. Because
Material for MkDocs accepts only one `theme.language` for that build, the
canonical HTML chrome is generated in Chinese and localized in the browser for
translated book URLs.

## Sources of truth

- `mkdocs.yml` defines the available languages, URL prefixes, filename
  suffixes, and the canonical Chinese navigation tree.
- `extras/site-nav-i18n.json` translates that navigation tree plus the two
  custom controls (sidebar and color mode).
- Material for MkDocs supplies standard UI translations for search, page
  actions, table of contents, footer links, repository links, and revision
  labels. A language can correct an upstream value with `ui_overrides` in
  `extras/site-nav-i18n.json`.
- `scripts/site_i18n.py` validates and combines those sources. During a site
  build it generates `_web/extras/site-i18n.generated.js`; never edit that
  generated file.

`extras/lang-switcher.js` applies the resulting catalog to desktop and mobile
navigation, the right-hand table of contents, search (including results added
after page load), tooltips, page actions, footer controls, color-mode controls,
revision dates, accessibility labels, and right-to-left document direction.

## Adding or changing a language

1. Add or update the language entry under `extra.languages` in `mkdocs.yml`.
2. Ensure the translated book uses the URL contract represented by that entry:
   `introduction`, `chapter1` through `chapter10`, `afterword`, and
   `reference-answers`, with its configured filename suffix.
3. Add the same language code to `extras/site-nav-i18n.json`. Translate every
   key under `nav`, `sidebar`, and `palette`; set `material_locale` to a locale
   shipped by Material for MkDocs.
4. If translated `chapterN/README.<locale>.md` experiment indexes exist, set
   `readmeSuffix` in `mkdocs.yml`. Omit it while they do not exist: the site
   will hide that unavailable sub-navigation instead of creating a broken or
   wrong-language link.
5. Run the audit:

   ```bash
   pip install -r requirements-docs.txt
   python scripts/site_i18n.py
   ```

6. Assemble and build the site normally. The MkDocs hook runs the audit again
   and refuses to build if the catalog has drifted.

## What the audit prevents

The check automatically discovers languages and named navigation entries from
`mkdocs.yml`. It fails when:

- a configured language is absent from the UI catalog, or an obsolete catalog
  entry remains;
- any navigation or custom-control translation is missing or empty;
- Chinese text remains in a non-CJK custom catalog;
- the selected Material locale or a required Material UI string is missing;
- a book URL or translated experiment-index URL generated by the switcher has
  no corresponding Markdown source.

The `i18n consistency check` GitHub Actions workflow runs this audit whenever
site configuration, translated books, navigation code, or the catalog changes.