hd2-bilingual-doc-verify
English / 简体中文
신뢰도: 여기서 검증되었습니다; 두 가지 실패 모드가 의도적으로 유발되었습니다.
scripts/verify_translations.py는 번역이 절대 변경해서는 안 되는 사항들을 확인하므로, 리뷰 관심을 산문에 집중할 수 있고 코드 샘플이 여전히 올바른지 확인하는 데 시간을 낭비하지 않게 됩니다.
이 저장소의 모든 문서가 영어/중국어 쌍으로 늘어난 후에 작성되었습니다: 6쌍의 X.md / X_cn.md에서, 중국어 복사본의 오래된 코드 블록은 아무도 알아채지 못하는 버그입니다.
전제 조건
| 필요 항목 | 이유 | 없을 경우 |
|---|---|---|
| Python 3.8+ | 스크립트 실행 | — |
lupa | 번역된 Lua 블록을 실제 LuaJIT에서 재컴파일 (검사 1) | 나머지 5개 검사는 여전히 실행됨; 스크립트는 건너뛴 항목을 출력함 |
| 저장소 레이아웃의 문서 쌍 | 검색이 X.md와 그 옆에 있는 X_cn.md를 찾음 (트리 어디든) | --root로 지정 |
다른 것은 필요 없음: 게임, 로더 도구, 네트워크 없음. 아무것도 쓰지 않습니다.
사용법
python -B scripts/verify_translations.py # 저장소 루트 스캔
python -B scripts/verify_translations.py --root <repo> # 또는 특정 저장소 지정
python -B scripts/verify_translations.py --no-luajit # 축소 모드 강제
종료 코드 0 = 모든 쌍 통과; 0이 아님 = 최소 하나 실패, 실패한 쌍이 명시됨.
9가지 검사 항목
-
번역된 Lua가 LuaJIT에서 여전히 컴파일되는지 — 번역본에서 모든
lua펜스를 추출하여 컴파일합니다. 코드를 건드린 번역을 잡아냅니다. -
모든 주석 제거 후 코드 펜스가 원본과 일치하는지 — Lua의
--및--[[ ]], 셸/PowerShell 및 Python의#(인라인# …주석은 번역 가능한 텍스트), 의사 코드의;. 주석은 번역됨; 코드는 그렇지 않음. -
문서화 펜스는 문서로 비교됨 — 실행 코드가 없는 펜스는 문서로 간주됨 (예: 디렉토리 트리/패키지 레이아웃, 산문의
text블록, 독스트링이나 주석만 인용하는 코드 펜스). 트리는 골격(글리프, 들여쓰기, 줄당 첫 토큰)으로 비교되어 누락된 브랜치나 이름 변경된 경로를 잡아냄; 산문은 줄 수만 비교됨 (모든 단어가 번역되므로). -
헤딩 구조 일치 — 순서대로 개수와 수준. 누락된 섹션을 잡아냄.
-
모든 상대 링크가 유지되거나 의도적으로
_cn대응 파일로 재지정됨 (실패가 아닌 참고 사항으로 보고). 소스가_cn파일을 가리키는 경우 번역본이 정확히 그 파일이면 이것도 참고 사항. -
프론트매터 온전함 — 동일한 키,
name:은 변경되지 않음 (식별자),description:은 번역됨 (사용자가 스킬을 선택할 때 보는 내용). -
언어 전환기가 존재하며 정확히 하나이고 대응 파일을 가리킴 — 양쪽의 헤더 블록에서, 현재 언어는 링크되지 않은 상태로:
English / [简体中文](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README_cn.md) [English](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README.md) / 简体中文절대 URL은 의도적입니다 — DeepSeek의 자체 저장소에서 가져왔는데, 전환기는 사용자가 다른 것을 탐색하기 전에 필요한 유일한 링크이기 때문입니다. 신뢰하는 대신 검사합니다: 하나를 제거하거나, 잘못된 파일을 가리키거나, 헤더에 두 개를 남기면 모두 실행 실패.
-
모든 스킬 파일은 자체 전환기를 가지며, 아직 번역이 없어도 마찬가지 —
skills/아래의 모든SKILL.md및SKILL_cn.md에 대해 쌍과 무관하게 검사. 쌍 루프는 양쪽이 모두 존재할 때만 실행되므로, 영어 파일만 있고 번역이 없는 스킬은 완전히 회피됨: 이것이 정확히 5개의 영어 스킬이 전환기 없이 남아 있고 중국어 파일에는 있는 이유. -
절대 GitHub URL 대상이 유효해야 함 —
check_absolute_targets()에 의해 보고됨, 전환기가 관례상 절대 URL을 사용하고 대응 파일이 없으면 렌더링된 페이지에서 끊어진 링크가 되어 아무도 알아채지 못하기 때문.
내장된 두 가지 교훈
- 명백한 레이아웃을 가정한 검증기는 거짓 실패를 보고합니다. 첫 번째 버전은 전체 줄 주석만 제거했기 때문에, 뒤에
--주석이 있는 모든 코드 블록이 불일치처럼 보였습니다. 번역이 아니라 검증기를 수정하는 것이 올바른 결정이었습니다 — 실패 횟수가 터무니없이 높았기 때문에 명백했습니다. 같은 일이 두 번 더 발생했습니다: Python 펜스의 인라인#주석 (제거기가 셸만 알았음), 그리고 독스트링만 인용한python펜스 (실행 코드가 전혀 없어 전체 블록이 산문). 각 수정은 검사 3을 더 좁고 정확하게 만들었습니다: 코드는 코드로, 문서는 문서로 비교하고, 펜스 레이블이 아닌 내용에서 결정하라. - 검사 3은 거짓 긍정 때문에 존재합니다. 새 스킬의 4개 "코드" 펜스가 디렉토리 트리였습니다; 번역된 주석을 코드 변경으로 처리했다면 번역자가 산문을 영어로 남겨두도록 강제했을 것입니다.
검증기가 실패를 보고하면, 번역을 건드리기 전에 실패를 살펴보십시오. 위의 세 경우 모두 번역이 정확했습니다 — 배포 사고를 설명하는 독스트링이 "코드"였고 의도적으로 번역된 경우를 포함하여. 잘못된 린터는 린터가 없는 것보다 더 큰 비용이 듭니다: 사람들이 무시하도록 가르칩니다.
한계
- 구조적 일치를 증명할 뿐, 번역이 올바르다는 것을 증명하지 않습니다. 잘못 번역된 문장은 모든 검사를 통과합니다. 산문을 읽으십시오.
- 검사 3의 구조적 지문은 의도적으로 주석 텍스트를 무시하므로, 경로 설명을 잘못된 것으로 바꾼 번역은 잡히지 않습니다.
discover_pairs()의 레이아웃만 알고 있습니다; 다르게 구성된 저장소는 해당 함수를 확장해야 합니다.
참고
writing-mod-tools (정직한 성능 저하, 종료 코드, 도구가 할 수 없는 것을 명시).