docs: 统一多语言文档生成（源文件驱动、生成文件不入库）

.gitattributes

@@ -0,0 +1,3 @@
+# bash 脚本必须保持 LF 行尾（CRLF 会导致解析问题）
+.githooks/pre-commit text eol=lf
+test/*.sh text eol=lf

.githooks/pre-commit

@@ -0,0 +1,66 @@
+#!/bin/sh
+# pre-commit hook：验证多语言源文件，检测手动修改生成文件
+# 模型 B：生成文件不入库（由 CI 自动生成并提交），提交时忽略它们
+set -e
+
+if [ -z "$(git diff --cached --name-only -- "script/multilingual-docs/")" ]; then
+    exit 0
+fi
+
+# 优先使用 venv 的 python
+PYTHON="python"
+if [ -f ".venv/Scripts/python" ]; then
+    PYTHON=".venv/Scripts/python"
+elif [ -f ".venv/bin/python" ]; then
+    PYTHON=".venv/bin/python"
+fi
+
+echo "📋 检测到多语言源文件变更..."
+$PYTHON script/manage_templates.py --check
+
+# ── 生成到临时目录（期望结果），与工作区比对：收集不一致的生成文件 ──
+GEN_TMP="$(mktemp -d)"
+trap 'rm -rf "$GEN_TMP" 2>/dev/null || true' EXIT
+$PYTHON script/manage_templates.py script/multilingual-docs/ "$GEN_TMP/.github/ISSUE_TEMPLATE/" --doc-dir "$GEN_TMP" >/dev/null
+
+mismatched=""
+for gen in $(find "$GEN_TMP" -type f); do
+    rel="${gen#"$GEN_TMP"/}"
+    if [ -f "$rel" ] && ! diff -q "$gen" "$rel" >/dev/null 2>&1; then
+        mismatched="$mismatched $rel"
+    fi
+done
+
+if [ -n "$mismatched" ]; then
+    echo -e "\n   以下生成文件与源文件不一致（可能被手动修改或未重新生成）："
+    for rel in $mismatched; do
+        echo "   - $rel"
+    done
+    echo ""
+    echo "   请通过源文件修改 script/multilingual-docs/ 下的 YAML，不要直接编辑生成文件；"
+    echo "   也可以选择重新生成到工作区，预览最新效果。"
+    echo -n "   是否重新生成并继续提交？[y/N] "
+    answer=""
+    # GIT_HOOK_NONINTERACTIVE：测试/CI 等非交互环境跳过询问，默认视为 N
+    if [ -z "${GIT_HOOK_NONINTERACTIVE:-}" ]; then
+        if [ -t 0 ]; then
+            read -r answer || true
+        else
+            # 钩子 stdin 默认是 /dev/null，交互提交时改从终端读取
+            read -r answer < /dev/tty || true
+        fi
+    fi
+    case "$answer" in
+        [Yy]*)
+            echo "   正在重新生成到工作区..."
+            $PYTHON script/manage_templates.py
+            ;;
+        *)
+            echo "   已取消提交。"
+            exit 1
+            ;;
+    esac
+else
+    # 无不一致：生成到工作区（本地方便预览）；生成文件不入库，由 CI 自动生成提交
+    $PYTHON script/manage_templates.py
+fi

.github/workflows/check_issue_template_consistency.yml

@@ -0,0 +1,63 @@
+name: 多语言文件一致性
+on:
+  pull_request:
+    paths:
+      - 'script/multilingual-docs/**'
+      - 'script/manage_templates.py'
+      - 'pyproject.toml'
+      - '.githooks/**'
+      - 'test/test_pre_commit_hook.sh'
+  push:
+    paths:
+      - 'script/multilingual-docs/**'
+      - 'script/manage_templates.py'
+      - 'pyproject.toml'
+      - '.githooks/**'
+      - 'test/test_pre_commit_hook.sh'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python script/manage_templates.py --requirements
+          pip install -r script/requirements.txt
+
+      # ── PR：验证 + 试生成（不提交） ──
+      - name: Validate & dry-run
+        if: github.event_name == 'pull_request'
+        run: |
+          python script/manage_templates.py --check
+          python script/manage_templates.py
+
+      # ── PR：测试 pre-commit 钩子行为 ──
+      - name: Test pre-commit hook
+        if: github.event_name == 'pull_request'
+        run: bash test/test_pre_commit_hook.sh
+
+      # ── 默认分支：验证 + 生成 + 自动提交（分支名语义化，随默认分支自适应） ──
+      - name: Generate & commit
+        if: github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+        run: |
+          python script/manage_templates.py
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          # 生成文件已 gitignore，需 -f 强制加回
+          git add -f .github/ISSUE_TEMPLATE/ CONTRIBUTING.md CONTRIBUTING_zh-TW.md README.md README_zh-TW.md vscode-extension/README.md vscode-extension/README_zh-TW.md
+          if git diff --cached --exit-code; then
+            echo "No changes."
+          else
+            git commit -m "chore: auto-generate multilingual files"
+            git push
+          fi

.github/workflows/update_contributors_images.yml

@@ -27,17 +27,21 @@ jobs:
           filter-author: (action-assistant\[bot\]|renovate\[bot\]|renovate-bot|@github-actions-bot|dependabot\[bot\]|ImgBotApp|imgbot\[bot\])
           avatarSize: 42
 
-      - name: Modify README.md
+      - name: Setup Python and install dependencies
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -r script/requirements.txt
+
+      - name: Update README.yml contributors and regenerate docs
         env:
           HTML_LIST: ${{ steps.contributors.outputs.htmlList }}
         run: |
-          escapedHtmlList=$(echo -e "$HTML_LIST" | sed ':a;N;$!ba;s/\n/\\n/g;s/\\n$//')
-          openDelimiter='<!--AUTO_GENERATED_PLEASE_DONT_DELETE_IT-->'
-          closeDelimiter='<!--AUTO_GENERATED_PLEASE_DONT_DELETE_IT-END-->'
-          sed -i "/$openDelimiter/,/$closeDelimiter/c\\$openDelimiter$escapedHtmlList$closeDelimiter" README.md
-          git diff --quiet --exit-code README.md || echo "CHANGES_DETECTED=true" >> $GITHUB_ENV
+          printf '%s' "$HTML_LIST" | python script/update_contributors.py
+          python script/manage_templates.py
+          git diff --quiet --exit-code README.md README_zh-TW.md script/multilingual-docs/README.yml || echo "CHANGES_DETECTED=true" >> $GITHUB_ENV
 
-      - name: Commit and push README.md
+      - name: Commit and push docs
         if: ${{ env.CHANGES_DETECTED == 'true' }}
         env:
           GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
@@ -47,5 +51,5 @@ jobs:
           -R "${{ github.repository }}" \
           -B "${{ github.ref_name }}" \
           -P "${{ github.sha }}" \
-          -F "README.md" \
+          -F "README.md README_zh-TW.md script/multilingual-docs/README.yml" \
           -h "修改文档: 更新\`贡献者列表\`"

.gitignore

@@ -13,3 +13,15 @@ Desktop.ini
 main(local).js
 # VS Code extension package
 *.vsix
+
+# Python
+.venv/
+
+# 多语言生成文件（由 CI 自动生成并提交，不入库）
+/CONTRIBUTING.md
+/CONTRIBUTING_zh-TW.md
+/README.md
+/README_zh-TW.md
+vscode-extension/README.md
+vscode-extension/README_zh-TW.md
+.github/ISSUE_TEMPLATE/bug-*.yml