LE0-Lin · Oct 7, 2026 · Oct 7, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,9 @@
 
 ## Unreleased
 
-No changes yet.
+### Added
+
+- Optional Simplified/Traditional Chinese repository overviews, core user guides and limitation summaries, with reciprocal language links and an explicit source-revision/coverage note. Advanced references remain English; CLI messages, JSON fields, rule semantics and the published v0.23.0 distributions are unchanged.
 
 ## v0.23.0
 

diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # AgentConfigScore
 
+English | [简体中文](https://github.com/LE0-Lin/AgentConfigScore/blob/main/README.zh-CN.md) | [繁體中文](https://github.com/LE0-Lin/AgentConfigScore/blob/main/README.zh-TW.md)
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score.svg" alt="AgentConfigScore A 100" />
 </p>
@@ -610,13 +612,17 @@ The Action emits outputs before returning its final regression status. Use `if:
 - [x] source and installed-package gates before publication
 - [x] user guide, exit-code reference and troubleshooting
 - [x] versioned English core package with release notes and compatibility guidance
-- [ ] optional Simplified and Traditional Chinese documentation and README language switch
+- [x] optional Simplified and Traditional Chinese core documentation and README language switch
 - [ ] optional semantic contradiction plugin
 
 See [release readiness and the localization sequence](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/release-readiness.md).
 Semantic extensions are optional; they are not a prerequisite for the core
 deterministic CI checker.
 
+The localized core overview, user guide and limitations are available separately;
+advanced references and research documents remain English. See the
+[translation scope and maintenance note](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/translations.md).
+
 ## Development
 
 ```bash

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -0,0 +1,112 @@
+# AgentConfigScore
+
+[English](README.md) | 简体中文 | [繁體中文](README.zh-TW.md)
+
+为 AI 编程助手的指令文件提供本地检查与 PR 回归门禁。
+
+![AgentConfigScore 演示](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif)
+
+AgentConfigScore 检查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等配置，并比较改动前后的基线，回答一个具体问题：**这次改动是否引入了已知规则能检测到的风险？**
+
+它是确定性检查器，不是 AI 评委。**A 100 只表示没有命中生效的规则，不表示指令有用、语义完美或安全无误。** 中文文档也不意味着检测器已经能够理解任意中文指令。
+
+## 快速开始
+
+需要 Python 3.10+。`diff` 还需要 Git；普通目录扫描和两个目录之间的 `compare` 不需要 Git。
+
+```bash
+python -m pip install --upgrade agent-config-score
+agent-config-score --version
+agent-config-score init
+agent-config-score doctor
+agent-config-score diff
+```
+
+在自己的仓库目录中运行。`init` 会生成 `.agentconfigscore.json` 和 `.github/workflows/agent-config-score.yml`；检查后提交这两个文件，后续 PR 即可自动检查。它不会替你编写或重写指令文件，也不会默认覆盖冲突的已有配置。
+
+`acs` 是短命令别名。v0.23.0+ 还可以使用 `python -m agent_config_score`，避免终端 PATH 没有找到命令的问题。
+
+- [简体中文使用指南](docs/zh-CN/user-guide.md)：安装、基线、报告、退出码与排错。
+- [分数含义与限制](docs/zh-CN/limitations.md)：先了解什么能检出、什么仍可能漏掉。
+- [完整英文文档索引](docs/README.md)：进阶接口与研究资料。
+
+## 为什么采用回归检查
+
+现有仓库不必先达到 100 分才能接入。如果基线是 72 分，没有退步的改动可以通过；降低分数或引入新错误的改动则依据配置被拦截。
+
+初始化后的核心策略如下：
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/v0/schema/agentconfigscore.schema.json",
+  "version": 1,
+  "policy": {
+    "max_drop": 0,
+    "fail_on_new_errors": true
+  }
+}
+```
+
+比较时以**基线策略**为准：PR 不能通过放宽自己的阈值，或新增自己的豁免来批准自己。需要接受某项例外时，必须经过基线审核，填写规则 ID、原因和到期日期；被豁免的发现仍保留审计记录。
+
+普通扫描默认只报告发现，不因发现问题就自动失败。需要绝对分数门槛时显式设置：
+
+```bash
+agent-config-score . --fail-under 90
+```
+
+## 本地检查与报告
+
+```bash
+agent-config-score .
+agent-config-score rules curl-pipe-shell
+agent-config-score diff origin/main
+agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors
+agent-config-score . --json
+agent-config-score . --html .agent-config-score/report.html --sarif .agent-config-score/results.sarif
+```
+
+`diff` 包含未提交的工作区改动，自动基线检测不联网、不自动 fetch。找不到基线时，明确指定本地已有的默认分支引用。
+
+规则、行号和上下文比数字本身更重要。报告可能包含仓库路径和发现信息，公开分享前请检查。`feedback` 可生成隐私最小化的本地草稿，但不会上传，仍需自己审核。
+
+## 接入 GitHub Actions
+
+优先使用 `init` 生成工作流，也可以手工配置：
+
+```yaml
+name: agent-config-regression
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  regression:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: LE0-Lin/AgentConfigScore@v0.23.0
+```
+
+固定 `@v0.23.0` 有利于复现；`@v0` 是会随后续版本更新的滚动引用。PR 评论属于[可选集成（英文）](docs/pr-comments.md)，扫描器默认不替你发评论。
+
+## 支持的指令文件
+
+包括根目录和嵌套目录的 `AGENTS.md` / `AGENTS.override.md`、`CLAUDE.md`、`GEMINI.md`、Cursor 的 `.cursorrules` / `.cursor/rules/`、Copilot 的 `.github/copilot-instructions.md` / `.github/instructions/`，以及 `.claude/`、`.clinerules`、`.windsurfrules`。可使用 `.agentconfigscoreignore` 排除发现路径。
+
+准备自己的指令文件时，可参考[复制即用模板（英文）](examples/README.md)，并替换成仓库真正的命令和约束。不要为了得高分而复制空泛的“最佳实践”。
+
+## 可靠性与边界
+
+运行时没有第三方依赖；本地扫描不调用 AI API，也不执行指令文件中的命令。包安装需要访问所选软件包索引；GitHub Actions 是单独的 CI 环境，报告访问权限由你的工作流控制。
+
+跨平台测试、维护的规则用例和安装验收证明程序符合指定的工程预期，**不证明它比直接问 AI 更准，也不证明它已经有真实用户价值**。独立对照评测尚未完成，已知语义漏报仍保留。详见[限制说明](docs/zh-CN/limitations.md)与[评测资料（英文）](benchmarks/README.md)。
+
+本页是核心入门的中文概览，不是完整英文 README 的逐行翻译。使用指南和限制说明已提供中文；高级 Action 参数、规则语法细节、贡献及研究文档目前仍为英文。[翻译范围与维护说明](docs/translations.md)。命令、终端消息和 JSON 协议保持原样，English 仍是默认入口。
+
+项目采用 [MIT 协议](LICENSE)。[发布与升级说明](docs/releases/v0.23.0.md)目前为英文。
diff --git a/README.zh-TW.md b/README.zh-TW.md
@@ -0,0 +1,112 @@
+# AgentConfigScore
+
+[English](README.md) | [简体中文](README.zh-CN.md) | 繁體中文
+
+為 AI 程式開發助手的指令檔提供本機檢查與 PR 回歸檢查。
+
+![AgentConfigScore 示範](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif)
+
+AgentConfigScore 檢查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等設定，並與改動前的基準比較，回答一個具體問題：**這次改動是否引入了已知規則能偵測到的風險？**
+
+它是確定性的檢查工具，不是 AI 評審。**A 100 只表示沒有命中生效的規則，不代表指令實用、語意完美或完全安全。** 提供中文文件也不表示檢查工具已經能理解任意中文指令。
+
+## 快速開始
+
+需要 Python 3.10+。`diff` 另外需要 Git；一般目錄掃描和兩個目錄之間的 `compare` 不需要 Git。
+
+```bash
+python -m pip install --upgrade agent-config-score
+agent-config-score --version
+agent-config-score init
+agent-config-score doctor
+agent-config-score diff
+```
+
+請在自己的儲存庫目錄執行。`init` 會建立 `.agentconfigscore.json` 和 `.github/workflows/agent-config-score.yml`；檢查並提交這兩個檔案後，後續 PR 即可自動檢查。它不會替你撰寫或改寫指令檔，也不會預設覆寫已存在且內容衝突的設定。
+
+`acs` 是較短的命令別名。v0.23.0+ 也能使用 `python -m agent_config_score`，不必依賴終端機 PATH 找到主命令。
+
+- [繁體中文使用指南](docs/zh-TW/user-guide.md)：安裝、基準、報告、結束代碼與疑難排解。
+- [分數意義與限制](docs/zh-TW/limitations.md)：先了解能偵測哪些問題，以及可能遺漏什麼。
+- [完整英文文件索引](docs/README.md)：進階介面與研究資料。
+
+## 為什麼使用回歸檢查
+
+既有儲存庫不必先達到 100 分才能導入。若基準為 72 分，沒有退步的改動可以通過；分數下降或引入新錯誤時，則依設定阻擋。
+
+初始化後的核心策略如下：
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/v0/schema/agentconfigscore.schema.json",
+  "version": 1,
+  "policy": {
+    "max_drop": 0,
+    "fail_on_new_errors": true
+  }
+}
+```
+
+比較以**基準策略**為準：PR 不能透過放寬自己的門檻，或新增自己的排除設定來核准自身。若需接受某項例外，必須經過基準審查，指定規則 ID、原因與到期日；被排除的檢查結果仍會保留稽核紀錄。
+
+一般掃描預設只回報結果，不會只因發現問題就自動失敗。需要絕對分數門檻時，請明確設定：
+
+```bash
+agent-config-score . --fail-under 90
+```
+
+## 本機檢查與報告
+
+```bash
+agent-config-score .
+agent-config-score rules curl-pipe-shell
+agent-config-score diff origin/main
+agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors
+agent-config-score . --json
+agent-config-score . --html .agent-config-score/report.html --sarif .agent-config-score/results.sarif
+```
+
+`diff` 包含尚未提交的工作目錄改動；自動偵測基準不連線，也不自動 fetch。找不到基準時，請明確指定本機已存在的預設分支參照。
+
+規則、行號與上下文比數字本身更重要。報告可能包含儲存庫路徑和檢查資訊，公開分享前請先檢查。`feedback` 能產生盡量減少私人資訊的本機草稿，但不會上傳，仍須自行審閱。
+
+## 整合 GitHub Actions
+
+建議用 `init` 產生工作流程，也可以手動設定：
+
+```yaml
+name: agent-config-regression
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  regression:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: LE0-Lin/AgentConfigScore@v0.23.0
+```
+
+固定使用 `@v0.23.0` 較容易重現；`@v0` 是會隨後續版本更新的滾動參照。PR 留言是[選用整合（英文）](docs/pr-comments.md)，檢查工具預設不會替你留言。
+
+## 支援的指令檔
+
+包含根目錄與巢狀目錄的 `AGENTS.md` / `AGENTS.override.md`、`CLAUDE.md`、`GEMINI.md`、Cursor 的 `.cursorrules` / `.cursor/rules/`、Copilot 的 `.github/copilot-instructions.md` / `.github/instructions/`，以及 `.claude/`、`.clinerules`、`.windsurfrules`。可用 `.agentconfigscoreignore` 排除探索路徑。
+
+準備自己的指令檔時，可參考[可直接複製的範本（英文）](examples/README.md)，再替換成儲存庫真正的命令與限制。不要為了提高分數而複製空泛的「最佳實務」。
+
+## 可靠性與界線
+
+執行時沒有第三方相依套件；本機掃描不呼叫 AI API，也不執行指令檔內的命令。安裝套件需存取選定的套件索引；GitHub Actions 是獨立的 CI 環境，報告存取權限由你的工作流程決定。
+
+跨平台測試、持續維護的規則案例與安裝驗收，證明程式符合指定的工程預期，**不代表它比直接詢問 AI 更準確，也不代表已經具備真實使用者價值**。獨立對照評測尚未完成，已知的語意漏報仍保留。請見[限制說明](docs/zh-TW/limitations.md)與[評測資料（英文）](benchmarks/README.md)。
+
+本頁是核心入門的中文概覽，不是完整英文 README 的逐行翻譯。使用指南與限制說明已提供中文；進階 Action 參數、規則語法細節、貢獻和研究文件目前仍為英文。[翻譯範圍與維護說明](docs/translations.md)。命令、終端機訊息和 JSON 協定維持原樣，English 仍為預設入口。
+
+專案採用 [MIT 授權](LICENSE)。[發布與升級說明](docs/releases/v0.23.0.md)目前為英文。
diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,7 @@
 # Documentation
 
+[English](user-guide.md) | [简体中文](zh-CN/user-guide.md) | [繁體中文](zh-TW/user-guide.md)
+
 Start with the [user guide](user-guide.md): install, initialize, check a change,
 read the result, and troubleshoot a failing gate.
 

diff --git a/docs/limitations.md b/docs/limitations.md
@@ -1,5 +1,7 @@
 # What the score does—and does not—mean
 
+English | [简体中文](zh-CN/limitations.md) | [繁體中文](zh-TW/limitations.md)
+
 AgentConfigScore is a deterministic linter and regression gate for persistent
 coding-agent instructions. Its score measures detected, rule-defined risks. It
 does not measure whether an AI agent is intelligent, whether a prompt will solve

diff --git a/docs/release-readiness.md b/docs/release-readiness.md
@@ -54,18 +54,18 @@ The release workflow is manual. Running tests or merging a readiness PR does
 not create a tag or publish to PyPI. This document is a gate definition, not an
 assertion that all future release steps have already been performed.
 
-## Next milestone: optional Chinese documentation
+## Optional Chinese documentation
 
-After the core package is cut, add a lightweight language switch in each README:
+After the v0.23.0 core package was cut, a documentation update adds a language switch in each README:
 English (default), 简体中文 and 繁體中文. The approach follows
 [Transformers' multilingual README](https://github.com/huggingface/transformers/blob/main/README.md)
 without adding a documentation framework or runtime translation dependency.
 
-Planned files:
+Initial core documentation:
 
 - `README.zh-CN.md` and `README.zh-TW.md`, with reciprocal language links.
-- `docs/zh-CN/` and `docs/zh-TW/` versions of the user guide, limitations and
-  configuration / suppression guidance first; advanced reference pages follow.
+- `docs/zh-CN/` and `docs/zh-TW/` versions of the user guide and limitations,
+  including the core policy / exception explanations; advanced references remain English.
 - A translation maintenance note recording the English source revision and
   explicitly identifying untranslated pages instead of linking empty placeholders.
 
@@ -81,6 +81,8 @@ Rules for the translation stage:
 - Do not add a CLI `--language` option until terminal-output localization is
   explicitly in scope and independently tested. Documentation is the first stage.
 
-The translated files and language selector are planned, **not shipped yet**.
+The repository's core translated pages and selector are included in the
+documentation update, not retroactively in the immutable v0.23.0 distributions
+or tag. See [translation scope and source revision](translations.md).
 Real-user feedback and independent evaluation remain separate ongoing work;
 they are not replaced by localization or release acceptance.
diff --git a/docs/translations.md b/docs/translations.md
@@ -0,0 +1,41 @@
+# Optional documentation languages
+
+[English](../README.md) | [简体中文](../README.zh-CN.md) | [繁體中文](../README.zh-TW.md)
+
+English is the default repository entrypoint and package README. Choosing a
+different document language does not change CLI output, rule grammar, scores,
+configuration version, command names, JSON keys or API behavior. There is no
+runtime `--language` option. Chinese instruction semantics are not certified by
+providing Chinese documentation.
+
+## Available scope
+
+| English source | 简体中文 | 繁體中文 | Scope |
+|---|---|---|---|
+| [README](../README.md) | [Overview](../README.zh-CN.md) | [Overview](../README.zh-TW.md) | Localized core overview, not the entire long English reference |
+| [User guide](user-guide.md) | [Guide](zh-CN/user-guide.md) | [Guide](zh-TW/user-guide.md) | Core user journey, all executable examples, exit codes and troubleshooting |
+| [Limitations](limitations.md) | [Limits](zh-CN/limitations.md) | [Limits](zh-TW/limitations.md) | Core score contract, rule limits and unestablished accuracy; historic table/manual links stay in English |
+
+Advanced Action inputs/outputs, precise rule grammars, score-history integrations,
+release notes, contribution instructions and research protocols remain English.
+Localized pages identify those links as English instead of creating empty pages.
+The two Chinese variants are maintained with Simplified and Traditional regional
+wording rather than changing the program's machine-readable identifiers.
+
+## Source baseline and maintenance
+
+The first localized core pages use English source revision
+`78af3f9a470c9edab67f3d1579e8319a299bb191` (v0.23.0). The repository language
+links are a subsequent documentation update; they are not inside the immutable
+v0.23.0 PyPI distributions or v0.23.0 tag.
+
+When an English source page changes, review both variants together and record
+the new source revision here. Preserve executable examples, rule IDs and JSON
+keys verbatim. Keep the score limitations and failure/exit semantics aligned;
+do not translate a prohibition into an affirmative command. Mark any partial
+coverage clearly and retain links to the English reference.
+
+Tests verify language-link targets, guide code-block parity, identical config
+and workflow examples between variants, and English as the default package
+README. They cannot verify translation meaning or serve as independent human
+review. Wording and rule interpretation still need review when sources change.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -1,5 +1,7 @@
 # User guide
 
+English | [简体中文](zh-CN/user-guide.md) | [繁體中文](zh-TW/user-guide.md)
+
 AgentConfigScore is a local, deterministic linter and pull-request regression
 gate for coding-agent instructions. It does not call an AI service or execute
 commands found in instruction files. A 100 means no active rule matched, not