ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

docs/STATIC_SITE_I18N.md

@@ -0,0 +1,64 @@
+# 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.