docs: 统一多语言文档生成（源文件驱动、生成文件不入库） - #760
Open
PtJade-Ceramic wants to merge 9 commits into
Open
Conversation
技术性： - 添加 `script\multilingual-issue-templates\bug-提交.yml` 作为现有议题模板的唯一多语言源文件 - 添加 `script\manage_templates.py` 验证每个语种的纯度（防止简繁混杂），赋能本地验证和云端持续集成（CI） - 添加 `.githooks\pre-commit` 在提交前验证议题模板，阻止手动更改单语言模板 - 添加 `.github\workflows\check_issue_template_consistency.yml` 在云端验证和生成议题模板 - 添加 `pyproject.toml` 给出依赖；添加 `script\.gitignore` 忽略自动生成的 `requirement.txt` - 更改 `.gitignore` 将 Python 虚拟环境纳入其中（见 https://docs.python.org/3/library/venv.html ） - 添加 `CONTRIBUTING.md` 给出今后议题模板的维护指南 编辑性： - [breaking change] 更改议题模板中“预期”和“实际”小节的 ID - 议题模板中添加空行，改进排版
- 区分源文件、生成模板和生成贡献指南三类暂存内容 - 手动修改生成文件时先运行脚本再比对差异并阻止提交 - 源文件变更时自动生成模板并纳入暂存区 - 修复直接编辑 CONTRIBUTING 文档时无法拦截的问题 👷 ci(multilingual): 扩展多语言文件一致性检查 - 将工作流重命名为“多语言文件一致性” - 新增 CONTRIBUTING.md 与 CONTRIBUTING_zh-TW.md 的一致性校验 - 更新流程图，展示源文件生成议题模板和贡献指南的流程
- 新增 Jinja2 依赖到 pyproject.toml，用于模板化生成多语言文档 - 移除 _render_doc 函数，改用 Jinja2 Environment 加载 .md.j2 模板 - 新增 CONTRIBUTING.md.j2 通用递归模板，结构与层级完全由 YAML 键顺序及 heading 嵌套推断 - 启用 StrictUndefined，模板缺失字段时立即报错，避免生成不完整文档
PtJade-Ceramic
force-pushed
the
ISSUE_TEMPLATE-test
branch
from
August 2, 2026 15:45
3e658ef to
f947664
Compare
- `README`、`vscode-extension/README` 与 `CONTRIBUTING` 统一走 Jinja2 + YAML 源文件 - 源目录 `multilingual-issue-templates` 更名 `multilingual-docs` - 贡献者墙自动写入 `README.yml`（`update_contributors_images.yml` + `update_contributors.py`） - `pre-commit` 钩子覆盖三份生成文档，并强制 LF 行尾 - 单次使用符号内联
PtJade-Ceramic
changed the title
PtJade-Ceramic
marked this pull request as ready for review
August 2, 2026 17:15
PtJade-Ceramic
marked this pull request as draft
August 2, 2026 17:29
- 移除无条件运行的生成脚本，`git diff HEAD` 检测已暂存的手动修改，阻止提交并打印差异 - 新增 `test/test_pre_commit_hook.sh`：临时 git 仓库重演钩子行为 - 动态检测 GFM 块类型 × 行首/行中/行尾 + 列表/引用/alert 空行断块 - 源文件变更自动生成纳入、无关改动放行 - CI 接入钩子测试；`chmod +x` 保证 Linux 钩子可执行；trap 清理失败不阻塞
PtJade-Ceramic
force-pushed
the
ISSUE_TEMPLATE-test
branch
from
August 2, 2026 18:28
40f84cd to
8a9fa51
Compare
PtJade-Ceramic
marked this pull request as ready for review
August 2, 2026 18:29
PtJade-Ceramic
marked this pull request as draft
August 2, 2026 18:31
- `git rm --cached` + `.gitignore`：自述/贡献指南/扩展自述/议题模板等生成文件不再入库 - 钩子：源文件变更时生成到临时目录与工作区比对，检测手动修改生成文件并阻止 - `manage_templates.py` 加 `--doc-dir` 支持输出重定向 - CI：默认分支 `git add -f` 生成并提交；PR 验证 + 测试钩子 - 测试脚本适配“手动修改阻止 / 生成文件不入库 / 无关放行，全通过”
- 检测到生成文件与源文件不一致时，列出文件并提示改源文件或重新生成预览 - 交互询问 y/N：Y 重新生成到工作区并继续提交；N 取消提交 - 钩子 stdin 默认 /dev/null，交互提交时从 /dev/tty 读取 - 新增 GIT_HOOK_NONINTERACTIVE，供测试/CI 非交互环境默认 N - 测试脚本验证"重新生成"提示，三场景通过
PtJade-Ceramic
force-pushed
the
ISSUE_TEMPLATE-test
branch
from
August 2, 2026 20:01
81be1c0 to
3939c1e
Compare
- 新增"Windows 开发者注意事项"：exec 位、CRLF/LF、钩子 stdin、PEP 668 常见坑 - 建议在 WSL 中测试以接近云端 CI，附 venv 准备步骤（依赖从 script/requirements.txt 安装）
PtJade-Ceramic
force-pushed
the
ISSUE_TEMPLATE-test
branch
from
August 2, 2026 21:10
c1dde45 to
68c60cd
Compare
PtJade-Ceramic
marked this pull request as ready for review
August 2, 2026 21:39
PtJade-Ceramic
changed the title
Contributor
Author
|
Tip @maboloshi 请安装 GitHub App gh-chinese-ai-reviewer 到您的账户 + 仅 github-chinese 仓库。 |
Owner
|
最近可能没太多时间复核 复杂PR，需要晚点处理 |
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
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.
简介
将议题模板、贡献指南（
CONTRIBUTING）与仓库/扩展自述（README）的多语言文档统一为「YAML 源文件 + Jinja2 模板」的自动化生成流程。生成文件不入库，由云端 CI 在默认分支自动生成并提交；开发者只需维护源文件。
变更内容
script/multilingual-docs/下的 YAML 源文件 +*.md.j2Jinja2 模板CONTRIBUTING、仓库README、vscode 扩展README、议题模板均由script/manage_templates.py生成简体/繁体版本script/requirements.txt安装（由pyproject.toml/--requirements生成）.gitignore忽略生成文件并git rm --cached移除已跟踪文件；云端 CI 在默认分支用git add -f自动生成并提交pre-commit钩子：源文件变更时自动验证并检测手动修改/过时的生成文件，不一致时提示并交互询问 Y/N；支持--doc-dir重定向输出与GIT_HOOK_NONINTERACTIVEtest/test_pre_commit_hook.sh覆盖「阻止手动修改 / 放行无关改动 / 生成文件不入库」三场景check_issue_template_consistency.yml校验 + 钩子测试 + 默认分支自动生成提交验证
manage_templates.py --check全部通过（OpenCC 校验 CN/TW 一致性）test/test_pre_commit_hook.sh在 Windows 与 WSL 均通过应先于 #758 审查和合并