liqiang
b119135836
Build latest book artifacts / build (push) Canceled after 0s
dependency resolution / resolve (3.11) (push) Canceled after 0s
dependency resolution / resolve (3.13) (push) Canceled after 0s
deploy-pages / build (push) Canceled after 0s
deploy-pages / deploy (push) Canceled after 0s
i18n consistency check / check (push) Canceled after 0s
provider adoption tests / test (chapter2/context-compression) (push) Canceled after 0s
provider adoption tests / test (chapter2/prompt-injection) (push) Canceled after 0s
provider adoption tests / test (chapter2/system-hint) (push) Canceled after 0s
provider adoption tests / test (chapter3/log-sanitization) (push) Canceled after 0s
web-search-agent tests / test (push) Canceled after 0s
web-search-agent tests / agentbook (push) Canceled after 0s
65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# 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.
|