Communitygithub.com

Puipipi/HD2-Agent-Skills

이중 언어 문서 쌍의 정합성을 검증합니다. 번역된 마크다운 파일이 원본과 일치하는지 Lua 블록 재컴파일, 코드 펜스 비교, 헤딩 구조 및 링크 일치 여부, 디렉토리 트리 구조 비교 등을 통해 확인합니다. 문서 쌍 중 하나를 편집한 후나 번역이 코드에서 벗어나기 시작할 때 사용하세요.

HD2-Agent-Skills란 무엇인가요?

이 스킬은 이중 언어 문서 쌍(예: `X.md` / `X_cn.md`)이 구조적으로 일치하는지 자동으로 검증하는 도구입니다. 특히 Lua 코드 블록이 번역 과정에서 변경되지 않았는지 실제 LuaJIT 인터프리터로 재컴파일하여 확인하고, 주석 제거 후 코드 펜스의 내용, 헤딩 구조, 상대 링크, 프론트매터, 언어 전환 링크 등 9가지 항목을 체계적으로 검사합니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, `scripts/verify_translations.py` 스크립트 하나로 실행됩니다. 이 도구는 번역의 정확성보다는 구조적 일관성을 보장하므로, 리뷰어가 실제 번역 품질에 집중할 수 있도록 도와줍니다. 파이썬 3.8 이상과 선택적으로 `lupa` 라이브러리만 필요하며, 게임이나 네트워크 접속 없이 독립적으로 작동합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Puipipi/HD2-Agent-Skills/tree/HEAD/skills/hd2-bilingual-doc-verify

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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가지 검사 항목

  1. 번역된 Lua가 LuaJIT에서 여전히 컴파일되는지 — 번역본에서 모든 lua 펜스를 추출하여 컴파일합니다. 코드를 건드린 번역을 잡아냅니다.

  2. 모든 주석 제거 후 코드 펜스가 원본과 일치하는지 — Lua의 -- 및 --[[ ]], 셸/PowerShell 및 Python의 # (인라인 # … 주석은 번역 가능한 텍스트), 의사 코드의 ;. 주석은 번역됨; 코드는 그렇지 않음.

  3. 문서화 펜스는 문서로 비교됨 — 실행 코드가 없는 펜스는 문서로 간주됨 (예: 디렉토리 트리/패키지 레이아웃, 산문의 text 블록, 독스트링이나 주석만 인용하는 코드 펜스). 트리는 골격(글리프, 들여쓰기, 줄당 첫 토큰)으로 비교되어 누락된 브랜치나 이름 변경된 경로를 잡아냄; 산문은 줄 수만 비교됨 (모든 단어가 번역되므로).

  4. 헤딩 구조 일치 — 순서대로 개수와 수준. 누락된 섹션을 잡아냄.

  5. 모든 상대 링크가 유지되거나 의도적으로 _cn 대응 파일로 재지정됨 (실패가 아닌 참고 사항으로 보고). 소스가 _cn 파일을 가리키는 경우 번역본이 정확히 그 파일이면 이것도 참고 사항.

  6. 프론트매터 온전함 — 동일한 키, name:은 변경되지 않음 (식별자), description:은 번역됨 (사용자가 스킬을 선택할 때 보는 내용).

  7. 언어 전환기가 존재하며 정확히 하나이고 대응 파일을 가리킴 — 양쪽의 헤더 블록에서, 현재 언어는 링크되지 않은 상태로:

    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의 자체 저장소에서 가져왔는데, 전환기는 사용자가 다른 것을 탐색하기 전에 필요한 유일한 링크이기 때문입니다. 신뢰하는 대신 검사합니다: 하나를 제거하거나, 잘못된 파일을 가리키거나, 헤더에 두 개를 남기면 모두 실행 실패.

  8. 모든 스킬 파일은 자체 전환기를 가지며, 아직 번역이 없어도 마찬가지 — skills/ 아래의 모든 SKILL.md 및 SKILL_cn.md에 대해 쌍과 무관하게 검사. 쌍 루프는 양쪽이 모두 존재할 때만 실행되므로, 영어 파일만 있고 번역이 없는 스킬은 완전히 회피됨: 이것이 정확히 5개의 영어 스킬이 전환기 없이 남아 있고 중국어 파일에는 있는 이유.

  9. 절대 GitHub URL 대상이 유효해야 함 — check_absolute_targets()에 의해 보고됨, 전환기가 관례상 절대 URL을 사용하고 대응 파일이 없으면 렌더링된 페이지에서 끊어진 링크가 되어 아무도 알아채지 못하기 때문.

내장된 두 가지 교훈

  • 명백한 레이아웃을 가정한 검증기는 거짓 실패를 보고합니다. 첫 번째 버전은 전체 줄 주석만 제거했기 때문에, 뒤에 -- 주석이 있는 모든 코드 블록이 불일치처럼 보였습니다. 번역이 아니라 검증기를 수정하는 것이 올바른 결정이었습니다 — 실패 횟수가 터무니없이 높았기 때문에 명백했습니다. 같은 일이 두 번 더 발생했습니다: Python 펜스의 인라인 # 주석 (제거기가 셸만 알았음), 그리고 독스트링만 인용한 python 펜스 (실행 코드가 전혀 없어 전체 블록이 산문). 각 수정은 검사 3을 더 좁고 정확하게 만들었습니다: 코드는 코드로, 문서는 문서로 비교하고, 펜스 레이블이 아닌 내용에서 결정하라.
  • 검사 3은 거짓 긍정 때문에 존재합니다. 새 스킬의 4개 "코드" 펜스가 디렉토리 트리였습니다; 번역된 주석을 코드 변경으로 처리했다면 번역자가 산문을 영어로 남겨두도록 강제했을 것입니다.

검증기가 실패를 보고하면, 번역을 건드리기 전에 실패를 살펴보십시오. 위의 세 경우 모두 번역이 정확했습니다 — 배포 사고를 설명하는 독스트링이 "코드"였고 의도적으로 번역된 경우를 포함하여. 잘못된 린터는 린터가 없는 것보다 더 큰 비용이 듭니다: 사람들이 무시하도록 가르칩니다.

한계

  • 구조적 일치를 증명할 뿐, 번역이 올바르다는 것을 증명하지 않습니다. 잘못 번역된 문장은 모든 검사를 통과합니다. 산문을 읽으십시오.
  • 검사 3의 구조적 지문은 의도적으로 주석 텍스트를 무시하므로, 경로 설명을 잘못된 것으로 바꾼 번역은 잡히지 않습니다.
  • discover_pairs()의 레이아웃만 알고 있습니다; 다르게 구성된 저장소는 해당 함수를 확장해야 합니다.

참고

writing-mod-tools (정직한 성능 저하, 종료 코드, 도구가 할 수 없는 것을 명시).

관련 스킬