docs: publish a Traditional Chinese site as a Read the Docs translation

.github/workflows/docs.yml

@@ -9,6 +9,8 @@ on:
       - 'README.md'
       - 'CHANGELOG.md'
       - 'zensical.toml'
+      - 'zensical.zh-TW.toml'
+      - 'i18n/**'
       - 'pyproject.toml'
       - 'uv.lock'
       - '.github/workflows/docs.yml'
@@ -20,6 +22,8 @@ on:
       - 'README.md'
       - 'CHANGELOG.md'
       - 'zensical.toml'
+      - 'zensical.zh-TW.toml'
+      - 'i18n/**'
       - 'pyproject.toml'
       - 'uv.lock'
       - '.github/workflows/docs.yml'
@@ -46,3 +50,6 @@ jobs:
 
     - name: Build (strict)
       run: uv run --no-sync zensical build --strict
+
+    - name: Build Traditional Chinese translation (strict)
+      run: uv run --no-sync zensical build --strict -f zensical.zh-TW.toml

.gitignore

@@ -307,6 +307,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/site-zh-TW
 
 # mypy
 .mypy_cache/

README.md

@@ -12,7 +12,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/README.zh-TW.md)
+[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/i18n/zh-TW/docs/index.md)
 
 A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
 

docs/CONTRIBUTING.md

@@ -29,7 +29,9 @@ Please refer to our [Development Guide](DEVELOPMENT.md) for detailed instruction
 
 ## Pull Request Process
 
-1. Update the matching guide under `docs/` (and the README if the change belongs on the front page) when you change the interface
+1. Update the matching guide under `docs/` (and the README if the change belongs on the front page) when you change the interface. Only the English
+   pages need updating: the [Traditional Chinese translation](DEVELOPMENT.md#traditional-chinese-translation)
+   is allowed to lag behind them
 2. Add an entry to the `## [Unreleased]` section of
    [CHANGELOG.md](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) if your change alters behaviour, adds public
    API, or fixes something a user could have hit. That section is what the

docs/DEVELOPMENT.md

@@ -204,6 +204,25 @@ The **Docs** workflow (`.github/workflows/docs.yml`) and Read the Docs
 (`.readthedocs.yaml`) both run `zensical build --strict`, so a broken link,
 snippet path or docstring reference fails the PR.
 
+### Traditional Chinese translation
+
+A Traditional Chinese (`zh-TW`) translation is published at
+<https://fastapi-cachex.readthedocs.io/zh-tw/latest/>. It is a separate Read the
+Docs translation project built from `zensical.zh-TW.toml` (build settings in
+`i18n/zh-TW/.readthedocs.yaml`), and its pages live in `i18n/zh-TW/docs/` — not
+under `docs/`, which would pull them into the English site.
+
+```bash
+uv run zensical serve -f zensical.zh-TW.toml
+uv run zensical build --strict -f zensical.zh-TW.toml  # also run by the Docs workflow
+```
+
+The English pages are the source of truth. The translation may lag behind
+them, and every translated page carries a banner saying so, with a link to the
+English original. Pages that are not translated yet are linked from the
+translation's navigation to the English site. When translating, follow the
+terms in [`i18n/zh-TW/GLOSSARY.md`](https://github.com/allen0099/FastAPI-CacheX/blob/master/i18n/zh-TW/GLOSSARY.md).
+
 ### Adding API reference pages
 
 API pages live under `docs/api/` and are generated from docstrings (Google

i18n/zh-TW/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs build of the Traditional Chinese translation:
+# https://fastapi-cachex.readthedocs.io/zh-tw/latest/
+# Same as the root .readthedocs.yaml, but built from zensical.zh-TW.toml. The
+# translation project points its "Build configuration file" setting here.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  jobs:
+    install:
+      - pip install uv
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --only-group docs --no-install-project
+    build:
+      html:
+        - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv run --no-sync zensical build --strict -f zensical.zh-TW.toml
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp -r site-zh-TW/* $READTHEDOCS_OUTPUT/html/