Max Isbey
5150037733
Ship preview translations of the docs in Simplified Chinese, Japanese, Korean and Brazilian Portuguese, served at /zh-CN/, /ja/, /ko/ and /pt-BR/ next to the English site (three pages each to start). English stays the single source of truth; everything else is generated and never hand-edited. scripts/docs/translations.py drives it (status / translate / stage / languages). `translate` re-translates only the `##` sections whose English changed and carries the rest of the page over byte-for-byte from the previous translation, then gates the result: heading anchors and code blocks are re-imposed from the English, the structure (sections, headings, fences, links, inline code, admonitions, glossary rules) is checked with the findings fed back for another attempt, and a stronger model reviews the meaning against the English. Per-language inputs — instructions.md (register, voice, typography) and glossary.json (termbase, keep-in-English list, banned renderings) — are the human-edited part; the pages and state.json under i18n/<code>/ are generated, so a correction goes into the inputs and holds across every future run. The build stages each language over the English tree (translations overlaid, notices stamped in — machine-translated, may be behind English, not translated — and links into the API reference pointed at the English one) and builds it strictly into site/<code>/. Heading ids are pinned into the translations from the ids the English site renders, so #fragment links resolve on every language site without touching the English pages. An outdated translation is served with a warning unless the English page's links or anchors moved under it, so an English edit can never break a language build. Every config carries the same language switcher.
22 lines
823 B
Bash
Executable File
22 lines
823 B
Bash
Executable File
#!/usr/bin/env bash
|
|
#
|
|
# Serve the v2 documentation locally with live reload (the English site only).
|
|
#
|
|
# Regenerates the API reference and the concrete Zensical config, then serves
|
|
# it. Re-run the script to pick up changes to `src/` (the API reference) or the
|
|
# nav; edits to prose pages under `docs/` are picked up by live reload. The
|
|
# translated sites under /<code>/ are never built here, so the language switcher
|
|
# offers only English (`--languages ""`) rather than linking to 404s.
|
|
#
|
|
# Usage:
|
|
# scripts/serve-docs.sh [<extra zensical serve args>...]
|
|
#
|
|
set -euo pipefail
|
|
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
|
cd "$REPO_ROOT"
|
|
|
|
uv run --frozen python scripts/docs/build_config.py --languages ""
|
|
exec uv run --frozen zensical serve -f mkdocs.gen.yml "$@"
|