Repository navigation
docs: publish a Traditional Chinese site as a Read the Docs translation - #146
Merged
Merged
Conversation
The Chinese README lived under docs/ and duplicated the English front page without being part of the site. Replace it with a separate zh-TW site built from zensical.zh-TW.toml out of i18n/zh-TW/docs/ (Zensical has no exclude_docs, so it cannot live under docs/), published as a Read the Docs translation project at /zh-tw/latest/. - Both sites get a language switcher (extra.alternate). - Every translated page carries a banner saying English is the source of truth, linking to the page's English original. - Untranslated guides are linked from the zh-TW navigation to the English site; later PRs swap them for translations. - The Docs workflow builds both sites strictly. - DEVELOPMENT.md and CONTRIBUTING.md describe the translation and its sync policy; i18n/zh-TW/GLOSSARY.md fixes the terminology. Part of #89
19 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #89 (PR 1 of 3: infrastructure).
What
zensical.zh-TW.tomlbuilds a separate zh-TW site fromi18n/zh-TW/docs/intosite-zh-TW/. The site usestheme.language = "zh-Hant"and the same markdown extensions as the English site, without mkdocstrings. Pages that aren't translated yet are linked from its navigation to the English site.i18n/zh-TW/and notdocs/zh-TW/: Zensical silently ignoresexclude_docs, so anything underdocs/would also be built into the English site.extra.alternate(English ↔ 繁體中文).i18n/zh-TW/overrides/main.htmlfills the theme'sannounceblock on every page. The banner links to the same page on the English site (config.extra.english_site + page.url). English is the source of truth.i18n/zh-TW/.readthedocs.yamlis the root config with-f zensical.zh-TW.tomlandsite-zh-TW/as the output.--strict, and its path filters includei18n/**andzensical.zh-TW.toml.i18n/zh-TW/docs/index.md: a translation of the current English README, which replaces the outdateddocs/README.zh-TW.md(deleted). The README's 繁體中文 link now points there.i18n/zh-TW/GLOSSARY.md: Taiwan terminology. Code, parameter and header names stay untranslated.docs/DEVELOPMENT.md(new "Traditional Chinese translation" section) anddocs/CONTRIBUTING.mdstate the sync policy: contributors update the English pages only, and the translation may lag.No CHANGELOG entry: nothing in the library changes.
Maintainer setup on Read the Docs (manual, after merge)
fastapi-cachex-zh-twfrom this repository.zh-tw).i18n/zh-TW/.readthedocs.yaml.fastapi-cachex-zh-tw. It will then be served athttps://fastapi-cachex.readthedocs.io/zh-tw/latest/.Until then the switcher's 繁體中文 entry leads to a 404.
Verified
zensical build --strictandzensical build --strict -f zensical.zh-TW.tomlboth report no issues.lang="zh-Hant", the banner and switcher links on every page, and the external nav entries.HTTP_CACHING.mdgot a banner linking to/en/latest/HTTP_CACHING/.