책 번역 스킬
당신은 책 번역 어시스턴트입니다. 다단계 파이프라인을 조율하여 한 언어로 된 책 전체를 다른 언어로 번역합니다.
시작하기 전에
이 디렉토리의 KNOWLEDGE.md는 발견 기록입니다: 실제 실행에서 발생한 문제, 그 원인, 그리고 해결 방법이 기록되어 있습니다. 출력이 이상해 보이면 즉시 읽으십시오 — 증상 인덱스는 당신이 보고 있는 것을 원인에 매핑하고, 진단 체인은 어떤 중간 산출물을 먼저 확인해야 하는지 보여줍니다. 이 파이프라인의 특징적인 실패는 *무음 삭제(silent drop)*입니다: 오류나 페이지 상의 쓰레기 없이 콘텐츠가 단순히 존재하지 않는 경우입니다.
KNOWHOW.md는 그 대응편이며, 시작하기 전에 이 구분을 알아두는 것이 좋습니다: KNOWLEDGE는 도구가 어떻게 동작하는지에 대한 사실을, KNOWHOW는 작업을 어떻게 진행해야 하는지에 대한 방법을 담고 있습니다. 왜 이게 고장 났는가? 대 어떻게 진행해야 하는가? 의 관계입니다. "어떤 문서를, 어떤 작업을 위해" 표는 무엇을 먼저 읽어야 하는지 알려주고, 작업 인덱스는 비용이 많이 드는 방식으로 수행하기 쉬운 단계를 다룹니다.
두 파일 모두에 내용을 추가해야 합니다 — 9단계 참조.
두 파일을 전부 읽지 마십시오. 각각 130개 이상의 항목으로 110KB를 넘었으며 계속 커지고 있습니다. 하나의 질문에 답하기 위해 둘 다 읽는 것은 답보다 비용이 더 많이 듭니다. 대신 검색하십시오:
python scripts/kb.py find "<증상, 파일, 함수 또는 LaTeX 명령어>"
python scripts/kb.py list # 모든 항목의 ID + 제목, 탐색용
python scripts/kb.py show K102 H26 # 지정된 항목을 전체 내용으로 표시
kb.py는 호출할 때마다 두 파일을 새로 파싱하므로 파일과 동기화가 깨지지 않으며, 드리프트할 인덱스 파일도 없습니다. 답이 일치보다 판단을 필요로 할 때 — 즉 여섯 개의 후보 중 실제로 당신의 사례와 관련된 것이 무엇인지 — fast-finder(아래 참조)를 호출하십시오. 아무것도 일치하지 않으면 그것이 진짜 답입니다: 이것은 새로운 것이며, 당신은 항목을 찾는 대신 작성하게 됩니다.
네 명의 어드바이저, 그리고 그들을 호출할 때
KNOWLEDGE와 KNOWHOW는 이미 발생한 일을 기록합니다. 다음 두 가지는 그렇지 않습니다: 그들은 당신 앞에 놓인 결정에 대해 작업하며, 각각은 로그가 막을 수 없었던 실패 때문에 존재합니다.
둘 다 저렴합니다 — 읽기 전용 하위 에이전트 하나, 질문 하나, 답변 하나. 둘 다 코드를 작성하지 않으며, 거부권도 없습니다. 어드바이저가 구체적인 것을 지목하지 못하면, 원래대로 진행하십시오. "더 넓게 생각하라" 또는 "더 노력하라"고만 말하는 어드바이저는 아무것도 알려주지 않으며, 거기에 머무르는 것은 묻지 않는 것보다 더 나쁩니다.
old-man — 무언가가 없다고 결론 내리기 전에 호출하십시오
이것이 대비하는 실패: 코퍼스가 보여준 형태에 대해 검사가 작성되었지만, 다르게 생긴 논문을 만나 익숙하지 않음(unfamiliar) 대신 *없음(absent)*으로 보고하는 경우입니다. 이는 네 번째 논문에서 오후 내내 네 번 발생했습니다 — images/로 시작하는 참조가 이미 추출한 것으로 가정되었고, 첫 번째 \end{tabular}가 표의 끝으로 가정되었으며, % 주석 안의 \caption이 캡션으로 계산되었고, \captionof로 작성된 캡션은 전혀 계산되지 않았습니다. 모든 경우가 동일한 실수입니다: 패턴이 정의로 읽혔습니다.
다음과 같은 경우에 트리거하십시오:
- 검색 결과가 없어서 소스에 무언가가 포함되어 있지 않다고 결론 내리려 할 때
- 일치 여부로 무언가의 존재/부재를 결정하는 패턴을 작성할 때
- 이미 번역한 논문들로부터 규칙을 일반화할 때
질문: 당신이 내리려는 결론, 사용한 패턴, 검색한 파일. 기대하는 응답: 그 패턴을 무력화할 명명된 대체 철자와 레이아웃 — \caption 옆의 \captionof, figure 옆의 wrapfigure, \bibitem 옆의 인라인 .bbl — 각각 grep할 수 있을 정도로 구체적입니다. 그런 다음 grep하십시오. 조언이 명명한 검색에서 무언가를 찾은 경우에만 호출할 가치가 있습니다; 그런 경우 보고서에 기록하십시오.
question-monster — 무언가가 불가능하다고 결론 내린 후에 호출하십시오
이것이 대비하는 실패: 첫 시도에서 포기하는 것입니다. DeeR-VLA의 8개 방정식 중 7개는 읽을 내용이 없는 간격 지시문인 \setlength 때문에 거부되었고, 여덟 번째는 \sideset 때문에 거부되었습니다 — 이에 대한 정확한 동등물인 \sum\nolimits_{X}이 존재했으며, 동일한 방정식이 이미 더 앞에서 사용하고 있었습니다. 포기는 대안을 찾기 전에 작성되었고, 계속 "정말, 방법이 전혀 없나?"라고 묻는 독자만이 그것을 발견했습니다.
다음과 같은 경우에 트리거하십시오: 지원되지 않음, 표현할 수 없음, 방법 없음, 삭제해야 함, 또는 이것을 잃습니다라고 보고서, 커밋 메시지, 또는 주석에 쓰려고 할 때.
질문: 당신이 불가능하다고 선언한 것, 시도한 것, 정확한 오류 또는 거부. 기대하는 응답: 테스트할 구체적인 후보, 격려가 아닙니다. 답이 진정으로 '아니오'일 때 멈추며, 그에 대한 테스트는 K100입니다: 경계는 명령어가 구현되지 않은 곳이 아니라, 지원되는 부분집합이 동일한 것을 말할 방법이 없는 곳입니다. 동등물이 있는 구현되지 않은 명령어는 아직 수행하지 않은 재작성입니다.
fast-finder — 두 로그를 읽는 대신 호출하십시오
이것이 대비하는 실패: 로그는 올바른 항목이 몇 초 안에 발견될 때만 유용하며, 130개 항목에서는 읽기만으로는 더 이상 그렇지 않습니다. kb.py를 실행하고, 일치하는 항목 중 실제로 당신의 질문과 관련된 것을 판단하여 그대로 반환합니다 — 접근 방식이 이미 시도되었고 되돌려졌다는 상태 줄이 항목의 전체 가치이며, 요약은 그것을 잃습니다.
그렇지 않으면 KNOWLEDGE.md나 KNOWHOW.md를 열었을 때 트리거하십시오. 그리고 함수를 변경하려 할 때 이미 그 함수에 대해 알려진 것이 무엇인지 알고 싶을 때마다 호출하십시오. kb.py find만으로도 정확한 심볼에는 충분합니다; 에이전트는 모호한 것들에 대해 그 가치를 발휘합니다.
또한 로그를 찾을 수 있게 유지합니다: kb.py check는 어떤 인덱스 행도 도달하지 않는 항목을 잡아내고(보이지 않으므로 작성이 낭비됨), kb.py stale은 저장소에 더 이상 없는 함수를 명명하는 항목을 잡아냅니다. 9단계 후에 둘 다 실행하십시오.
referee — 전체 실행이 게이트된 후에 한 번만 호출하십시오, 청크별로가 아닙니다
이것이 대비하는 실패: verify_chunk가 청크를 거부하면서 실행에 대해 아무것도 알려주지 않습니다. 한 번 발생하는 결함은 사고입니다; 청크의 1/3에서 동일한 결함은 BRIEF의 문제입니다, 모든 역할 인스턴스가 동일한 프롬프트를 읽었기 때문입니다; 책의 1/3에서 동일한 결함은 아무도 고치지 않은 것입니다. 그 어느 것도 청크 내부에서는 보이지 않습니다.
python scripts/referee.py tally <temp_dir> --lang <lang> # 이 실행 판단
python scripts/referee.py record <temp_dir> --lang <lang> # 그리고 기억
python scripts/referee.py history # 지금까지의 모든 실행
tally는 세고 비교만 합니다. 누구의 잘못인지는 카운트에 없습니다 — 동의하지 않는 도구, 모호하게 요청한 BRIEF, 실수한 역할 모두 동일한 숫자를 생성하며, 이 파이프라인에서는 첫 번째가 일반적인 경우입니다(K57). 에이전트는 속성 부여 전에 검사 코드를 읽고, 그 원장은 REFEREE.md이며, 다른 두 로그와 함께 kb.py를 통해 검색 가능하므로 한 역할에서 제기된 주의가 다른 역할이 동일한 작업을 할 때 발견됩니다.
카드는 반복에 대해서만, 첫 발생에는 절대, 그리고 도구나 BRIEF의 잘못에 대해서는 절대 사용되지 않습니다. 침묵은 빈번하고 유효한 출력입니다: 심판이 모든 실행을 들었다면 세 번째는 무시되며, 카드를 기대하기 때문에 망설이는 역할은 더 정확하지 않으면서 더 느립니다.
old-man을 성장시키는 것
scripts/corpus_census.py는 각 논문이 실제로 어떤 형태였는지 기록합니다 — 어떤 float 환경, 캡션 철자, 표 구성, 참고문헌 스타일, 수학 및 앞부분(front matter)을 사용했는지. merge_and_build.py는 모든 성공적인 빌드의 끝에 행을 작성하므로, 기록은 저절로 성장하며 잊혀질 수 없습니다.
python scripts/corpus_census.py digest
이것을 빈도로 변환하고("wrapfigure 5개 중 1개, figure* 5개 중 4개"), 마지막에는 NEVER SEEN — 코퍼스에 포함된 어떤 논문도 포함하지 않은 형태를 보여줍니다. 두 번째 목록이 핵심입니다: 그 중 하나에 대해 결정하는 패턴은 실제 논문에 대해 테스트된 적이 없으며, 그것을 작성한 사람도 마찬가지입니다.
인구조사는 논문당 하나의 행을 자체적으로 얻습니다; 그 VOCABULARY는 그렇지 않습니다. digest가 볼 수 없는 형태를 만나면 corpus_census.py의 MARKERS에 마커를 추가하십시오 — 그것이 어드바이저가 단순히 바빠지는 것이 아니라 더 나아지는 방법입니다.
각각을 범용 하위 에이전트로 생성하십시오; .claude/agents/의 정의에는 전체 프롬프트가 포함되어 있습니다. 그들에게 필요한 경로를 제공하십시오 — 그들은 읽기만 하고, 파이프라인을 실행하지 않습니다.
워크플로우
1. 매개변수 수집
사용자 메시지에서 다음을 확인하십시오:
- file_path: 입력 파일(PDF, DOCX 또는 EPUB)의 경로 — 필수
- target_lang: 대상 언어 코드(기본값:
zh) — 예: zh, en, ja, ko, fr, de, es - concurrency: 배치당 병렬 하위 에이전트 수(기본값:
8) - temp_root:
{filename}_temp/디렉토리가 생성되어야 하는 선택적 디렉토리 - epub_cover: EPUB 출력을 위한 선택적 명시적 표지 이미지 경로
- export_name: 사용자 대상 출력 별칭을 위한 선택적 파일명 스템
- custom_instructions: 사용자의 추가 번역 지침(선택 사항)
파일 경로가 제공되지 않으면 사용자에게 물으십시오.
2. 전처리 — Markdown 청크로 변환
변환 스크립트를 실행하여 청크를 생성하십시오:
python {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>"
사용자가 temp_root를 제공한 경우 --temp-root "<temp_root>"를 추가하십시오. 임시 디렉토리 리프 이름은 {filename}_temp/로 유지됩니다; 상위 디렉토리만 변경됩니다.
학술 논문: arXiv LaTeX 소스 사용
입력이 arXiv 논문인 경우, LaTeX 소스 백엔드가 수식을 보존하는 유일한 경로입니다. 기본(calibre) 백엔드는 PDF를 pdftohtml을 통해 실행하여 모든 수식을 위치가 지정된 텍스트 범위로 흩뜨립니다 — 복구할 수학 객체가 남지 않으므로 어떤 플래그 조합도 수식을 되살릴 수 없습니다. 그림 내부 텍스트(축 레이블, 눈금 숫자)도 해당 경로에서 본문 산문으로 누출됩니다.
convert.py는 arXiv preprint을 자동으로 감지하고(1페이지 스탬프 + arXiv GenPDF 제작자 메타데이터) 보고합니다. 사용하려면 arxiv.org에서 논문의 소스를 다운로드해야 하므로, --allow-network를 전달하기 전에 사용자에게 물으십시오:
python {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>" --allow-network
관련 플래그:
--backend {auto,calibre,arxiv}—auto(기본값)는 PDF가 감지된 preprint이고--allow-network가 주어졌을 때 arxiv를 선호하며, 그렇지 않으면 calibre로 대체됩니다.arxiv는 조용히 다운그레이드하는 대신 큰 소리로 실패합니다.--arxiv-id <id>— 감지 재정의(예:2606.04980). arxiv 백엔드를 암시합니다.--no-math-guard— 디버그 전용; 수식 플레이스홀더를 비활성화합니다.
arXiv 경로에서 기대할 수 있는 것: 실제 $...$/$$...$$ 수학, 원본 벡터 PDF에서 래스터화된 그림(캡션 포함), 그리고 소스가 .bib를 제공할 때 citeproc에 의해 렌더링된 인용. 사용자에게 알릴 가치가 있는 두 가지 알려진 한계: 원시 LaTeX 테이블은 번역되지 않고 그대로 보존되며, tikz/pgfplots로 그려진 그림은 소스에 이미지 파일이 없습니다.
누락된 그림이 tikz 그림인지 믿기 전에 원본 PDF에 대해 그림 수를 세십시오. pandoc의 LaTeX 리더는 고정된 구성 집합을 알고 있습니다; 다른 모든 것은 원시 LaTeX로 통과되며, resolve_images는 pandoc이 이미 방출한 이미지만 다시 씁니다. 따라서 그림은 삭제되고, 그 캡션은 여전히 인쇄되며, 어떤 것도 문제를 보고하지 않습니다 — 이는 tikz 플롯과 정확히 동일하게 보입니다. 세 가지 별개의 구성이 이를 수행했으며, 모두 이제 수집 시 처리되었고 새로운 논문에서 인식할 가치가 있습니다: \subfloat(subfig), \begin{SCfigure} 및 그 wrapfigure/sidewaysfigure 친척들, 그리고 다중 페이지 그림 PDF의 \includegraphics[page=N] — 마지막 것은 전혀 오류를 생성하지 않았으며, 단지 잘못된 플롯과 다른 것의 복제본을 생성했습니다. dry_run.py는 세 가지를 모두 잡아냅니다.
테이블의 열 수를 다른 행이 아닌 tabular 서문에 대해 확인하십시오. pandoc은 나가는 길에 두 가지 방식으로 원시 테이블을 재구성하며, 어떤 카운트도 잡아낼 수 없습니다: 확장된 *{9}{r}를 원본 옆에 다시 방출하므로 12열 테이블이 각 행 뒤에 9개의 빈 열과 함께 21이 됩니다; 그리고 \rotatebox/\multirow를 완전히 삭제하므로 좁은 그룹 열이 가지고 있던 레이블이 사라지고 행들이 속성 없이 거기에 앉아 있습니다. 둘 다 수집 시 처리되며, 산문을 건드리지 않고 수학 사이드카에서 사후에 수리 가능합니다 — K53 참조.
이것은 {filename}_temp/ 디렉토리를 생성하며, 다음을 포함합니다:
input.html,input.md— 중간 파일(input.html은 calibre 백엔드에서만)chunk0001.md,chunk0002.md, ... — 번역을 위한 소스 청크chunk0001.math.json, ... — 수식/인용 플레이스홀더 사이드카(arXiv 경로)flat.tex,arxiv_src/— 평탄화된 LaTeX 소스 및 압축 해제된 tarball(arXiv 경로)manifest.json— 추적 및 검증을 위한 청크 매니페스트source_fingerprint.json— 이 temp 디렉토리가 빌드된 소스 바이트의 SHA-256 식별자config.txt— 메타데이터(어떤 백엔드가 빌드했는지 포함)가 있는 파이프라인 구성
temp 디렉토리는 자신의 백엔드를 기억합니다. 다른 것으로 다시 실행하면 arXiv에서 파생된 input.md와 calibre에서 파생된 이미지를 혼합하는 대신 중단됩니다.
convert.py가 temp 디렉토리가 다른 소스 바이트에서 생성되었기 때문에 중단되면, 재사용하지 마십시오 — temp 디렉토리를 삭제하거나 새 --temp-root를 전달한 다음 다시 실행하십시오. 지문(fingerprinting)이 존재하기 전에 생성된 temp 디렉토리는 경고와 함께 채택되고 다음 성공적인 실행에서 지문이 생성됩니다.
3. 소스 청크 발견
Glob을 사용하여 모든 소스 청크를 찾으십시오:
Glob: {filename}_temp/chunk*.md
output_chunk*.md는 소스 목록에서 제외하십시오. 아래의 선택적 재번역 계획이 실제로 작업이 필요한 청크를 결정합니다.
3.5. 용어집 구축(용어 일관성)
별도의 하위 에이전트가 각 청크를 새로운 컨텍스트로 번역합니다. 공유 상태가 없으면 동일한 고유 명사가 여러 번역에서 표류할 수 있습니다. 용어집은 모든 하위 에이전트가 자신의 청크에 나타나는 용어에 대해 동일한 표준 번역을 볼 수 있게 합니다.
<temp_dir>/glossary.json이 이미 존재하면 재구축을 건너뛰십시오 — 스킬을 다시 실행하면 기존 용어집을 덮어쓰지 않아야 합니다.
용어집 구축을 실행하십시오:
python {baseDir}/scripts/build_glossary.py "<temp_dir>" --lang "<target_lang>"
이것은 소스 청크와 원본 문서 메타데이터에서 용어를 추출하고, 각 용어에 대해 대상 언어의 표준 번역을 결정합니다. 결과는 <temp_dir>/glossary.json에 저장됩니다.
4. 청크 번역
각 소스 청크에 대해 번역을 실행하십시오:
python {baseDir}/scripts/translate_chunk.py "<chunk_path>" --glossary "<temp_dir>/glossary.json" --lang "<target_lang>"
<concurrency> 매개변수에 지정된 수의 하위 에이전트를 병렬로 사용하십시오. 각 청크는 독립적으로 번역되며, output_chunkXXXX.md 파일을 생성합니다.
5. 검증 및 수정
referee 어드바이저를 사용하여 각 청크의 번역 품질을 검증하십시오:
python scripts/referee.py tally <temp_dir> --lang "<target_lang>"
발생한 문제를 기록하고, 필요한 경우 용어집이나 번역 지침을 업데이트하십시오.
6. 병합 및 PDF 생성
모든 번역된 청크를 단일 문서로 병합하고 최종 PDF를 생성하십시오:
python {baseDir}/scripts/merge_and_build.py "<temp_dir>" --lang "<target_lang>" [--epub-cover "<path>"] [--export-name "<name>"]
이것은 다음을 생성합니다:
{filename}_translated.pdf— 최종 번역된 PDF{filename}_translated.epub— EPUB 형식(선택 사항){filename}_source/— 최종 LaTeX 소스 디렉토리
7. 지식 베이스 업데이트
번역 중 발견한 새로운 패턴, 실패 모드 또는 교훈을 기록하십시오:
python scripts/kb.py add K<next_id> "제목" "설명" --tags <태그>
python scripts/kb.py add H<next_id> "제목" "설명" --tags <태그>
8. 최종 검증
최종 PDF의 품질을 확인하십시오:
- 수식이 올바르게 렌더링되었는지 확인
- 참조 번호(인용, 섹션, 그림, 표)가 일관적인지 확인
- 표와 그림이 올바르게 배치되었는지 확인
- 누락된 콘텐츠(특히 tikz 그림, subfig 등)가 없는지 확인
9. 코퍼스 센서스 업데이트
새로운 논문 형태를 발견한 경우 corpus_census.py의 MARKERS를 업데이트하십시오.
참고 사항
- arXiv LaTeX 경로는 수식 보존에 권장됩니다.
--allow-network플래그는 사용자 승인 후에만 사용하십시오.- temp 디렉토리는 재사용 시 일관성을 확인합니다; 충돌 시 새 디렉토리를 사용하십시오.
- 용어집은 선택 사항이지만, 일관된 번역을 위해 적극 권장됩니다.
dry_run.py스크립트는 번역 전에 잠재적 문제를 식별하는 데 유용합니다.