Revayat — 영어 → 페르시아어 책 번역
아래 아홉 단계를 순서대로 실행하세요. 각 단계는 명령어와 출력 처리 규칙으로 구성됩니다. 순서를 임의로 변경하거나 이전 단계가 괜찮아 보인다고 다음 단계를 건너뛰지 마세요.
두 변수를 한 번 설정한 후 모든 곳에서 사용하세요:
SKILL_DIR— 이 파일이 있는 폴더입니다. Claude Code 플러그인에서는${CLAUDE_PLUGIN_ROOT}/skills/revayat입니다.WORK— 이 책의 작업 폴더입니다(예:work/).
모든 명령어는 python3 $SKILL_DIR/scripts/revayat.py <단계> … 형식입니다.
절대 깨뜨리면 안 되는 다섯 가지 규칙
- 페르시아어 텍스트를 절대 반전시키지 마세요. 방향은 빌더가 설정합니다. 반전시키면 한 뷰어를 제외한 모든 곳에서 깨진 파일이 생성됩니다.
@@ id헤더를 절대 만들거나, 삭제하거나, 병합하거나, 분할하거나, 순서를 바꾸지 마세요. 제공된 것을 정확히 반환하세요.[[fn:…]],**bold**,*italic*또는`verbatim`마커를 절대 삭제하지 마세요. 이들은 계산되며, 불일치는 QA 실패를 초래합니다.- 번역을 수정하기 위해
book.json을 수동 편집하지 마세요. 워크시트를 수정하고 병합을 다시 실행하세요. - 책을 절대 줄이지 마세요. 요약하거나, 어려운 문장을 건너뛰거나, 순화하지 마세요. 단계에서 콘텐츠 누락을 보고하면 해당 청크를 다시 실행하세요.
1단계 — 도구 확인
python3 $SKILL_DIR/scripts/revayat.py doctor
"ready": true→ 계속 진행합니다."ready": false→pip install -r $SKILL_DIR/requirements.txt를 실행한 후doctor를 다시 실행합니다.optional_tools에not found가 표시되어도 지금은 괜찮습니다. 2단계에서 OCR이 실제로 필요한지 알려줍니다.
2단계 — 추출
python3 $SKILL_DIR/scripts/revayat.py extract "<input file>" --out $WORK
페르시아어 소스의 경우 --ocr-lang fas를 추가하세요. 다른 언어의 경우 Tesseract 코드(deu, fra, ara, …)를 사용하세요.
출력된 JSON을 읽고 다음 표를 따르세요:
| 표시 | 조치 |
|---|---|
"kind": "digital" | 아무것도 하지 않음; OCR 불필요 |
"kind": "scanned" 또는 "mixed" | OCR이 자동으로 실행됨; ocr.probe_after.text_share가 0.7 이상인지 확인 |
| OCRmyPDF를 명명하는 오류 | 메시지에 따라 설치한 후 이 단계 다시 실행 |
clean_scan.cleaned가 0 이상 | 해당 페이지에서 컬러 워터마크가 제거됨 |
ocr.warning이 null이 아님 | 읽어보기; 파일은 여전히 사용 가능하므로 계속 진행 |
page_scans_dropped가 0 이상 | 해당 수의 전체 페이지 래스터가 그림이 아닌 스캔 자체로 인식됨 |
클리너는 파일을 편집하지 않습니다. 원본은 그대로 유지되고 정리된 복사본은 $WORK/cleaned.pdf에 기록되며, clean_scan에는 페이지별로 제거된 내용과 그대로 남은 내용이 기록됩니다. 전체를 건너뛰려면 --clean-scan off를, 스탬프가 남아 있으면 --clean-scan force를 전달하세요.
책이 스캔된 경우 지금 다음 두 가지 추가 작업을 수행하세요.
인식 신뢰도 — 이것이 없으면 잘못 읽은 단어와 올바른 단어를 구분할 수 없습니다. 둘 다 유창한 페르시아어이기 때문입니다:
python3 $SKILL_DIR/scripts/revayat.py ocr-sidecar --pdf $WORK/ocr.pdf --out $WORK --lang fas --book $WORK/book.json
이 명령은 source.ocr.json(단어, 줄, 블록 및 페이지별: 상자, 신뢰도, 읽기 순서 및 실행된 전처리)과 source.ocr.txt를 작성한 다음 book.json의 각 블록에 해당 영역의 신뢰도를 기록합니다. low 등급의 블록은 qa check에서 ocr-low-confidence로 보고되며, 이를 수락하면 페이지 이미지를 살펴봐야 합니다. 임계값은 기본적으로 85 및 60이며 --high/--low로 이동합니다.
스캔 내부의 삽화 — 스캔된 페이지는 하나의 평평한 이미지이므로, 페이지에 있는 사진은 무언가가 찾을 때까지 별도의 그림이 아닙니다:
mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l arabic
python3 $SKILL_DIR/scripts/revayat.py extract "<input file>" --out $WORK --figures-from-mineru $WORK/mineru
원본이 아닌 cleaned.pdf에서 MinerU를 실행하세요. 그렇지 않으면 워터마크를 그림으로 잘라냅니다. MinerU에서 그림만 가져오세요. MinerU가 자체적으로 인식한 페르시아어 텍스트는 단어와 단어 안의 문자가 뒤집혀서 반환됩니다. Tesseract(fas)는 같은 페이지를 올바르게 읽으므로 텍스트는 그대로 둡니다. MinerU가 페이지 범위에서 실행된 경우 --figures-page-offset N을 사용하세요.
그런 다음 더 진행하기 전에 결과를 확인하세요:
python3 $SKILL_DIR/scripts/revayat.py qa check --book $WORK/book.json --allow-incomplete
여기서 untranslated-block은 무시하세요. 아직 번역되지 않았습니다. asset-missing을 찾고 있습니다. 실제 책의 경우 stats.text_blocks가 20 미만이면 추출에 실패한 것입니다: references/extraction.md를 참조하세요.
3단계 — 용어집
python3 $SKILL_DIR/scripts/revayat.py glossary scan \
--book $WORK/book.json --out $WORK/glossary.json
보고서에는 needs_persian이 가장 빈도가 높은 순서로 나열됩니다. $WORK/glossary.json을 열고 처음 20개 항목 각각에 대해 다음 네 필드를 채우세요:
"target": "الیزابت بنت",
"later_form": "الیزابت بنت",
"first_form": "الیزابت بنت (Elizabeth Bennet)",
"locked": true
first_block_id는 정확히 그대로 두세요. 파이프라인은 이 필드를 사용하여 이름을 소개하는 단일 청크를 결정합니다. 편집하지 말고, 첫 번째 언급을 직접 결정하지 마세요.
실제 이름이 아닌 항목은 삭제하세요. 그런 다음 계속 진행합니다.
4단계 — 청킹
python3 $SKILL_DIR/scripts/revayat.py chunk build \
--book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json
청크 수를 기록하세요. 각 청크는 하나의 번역 작업이 됩니다.
이미 일부 워크시트를 번역했는데 입력이 변경된 경우, 이 명령은 조용히 책과 일치하지 않는 워크시트를 제공하는 대신 "refused": "stale-worksheets"와 함께 거부합니다. 제공된 이유를 다시 읽고, 기존 번역이 여전히 유효하다고 판단한 경우에만 --force를 추가하세요.
5단계 — 번역
각 $WORK/chunks/chunkNNNN.md에 대해 $WORK/chunks/out_chunkNNNN.md를 생성하세요. 런타임에 하위 에이전트가 있는 경우 청크당 별도의 하위 에이전트를 사용하고, 한 번에 8개씩 처리하세요. 그렇지 않은 경우 하나씩 처리하세요. 결과는 동일하며 속도만 느려집니다.
하위 에이전트에 정확히 다음 내용을 제공하세요:
$WORK/chunks/chunkNNNN.md를 읽고$WORK/chunks/out_chunkNNNN.md를 작성하세요.페르시아어로 번역하세요. 먼저
$SKILL_DIR/references/translation-policy.md를 읽고 따르세요.출력 형식 — 기계적입니다. 정확히 맞춰야 합니다:
- 각
@@ <id> <kind>줄을 변경하지 않고 같은 순서로 복사하세요.- 그 아래 줄에 페르시아어 번역을 넣으세요.
- 다른 것은 출력하지 마세요: 서문, 영어, 설명, 요약 금지.
규칙:
- "이름" 테이블은 구속력이 있습니다. 행에 "첫 번째 언급, 여기서 소개"라고 표시된 경우 해당 긴 형태를 사용하세요. 다른 모든 곳에서는 짧은 형태를 사용하세요. 스스로 결정하지 마세요. 테이블이 이미 결정했습니다.
- "주변 텍스트"는 컨텍스트일 뿐입니다. 절대 번역하거나 복사하지 마세요.
**bold**,*italic*,`verbatim`및[[fn:…]]를 동등한 페르시아어 단어 주위에 정확히 유지하세요. 추가하거나 제거하지 마세요.- 모든 단위를 완전히 번역하세요. 절대 요약하거나 건너뛰지 마세요.
- 자체 각주를 추가하려면: 문장에
[[fn:tr-01]]을 쓰고 끝에@@ tr-01 footnote블록을 추가하여 텍스트를 넣으세요. 실제 문화적 참조나 말장난에만 사용하세요.
언제든지 남은 내용을 확인하세요:
python3 $SKILL_DIR/scripts/revayat.py chunk status --chunks $WORK/chunks
6단계 — 병합
python3 $SKILL_DIR/scripts/revayat.py merge --book $WORK/book.json --chunks $WORK/chunks
| 필드 | 의미 | 조치 |
|---|---|---|
"ok": true | 모든 것이 정상적으로 병합됨 | 7단계로 진행 |
missing_outputs | 해당 청크가 번역되지 않음 | 번역 실행 |
missing_units | 헤더가 누락됨 | 해당 청크 다시 실행 |
unknown_units | 헤더가 생성됨 | 해당 청크 다시 실행 |
수정 후 병합을 다시 실행하는 것은 항상 안전합니다.
7단계 — 페르시아어 타이포그래피
python3 $SKILL_DIR/scripts/revayat.py falint fix --book $WORK/book.json
기계적이며 두 번 실행해도 안전합니다. 책에 라틴 숫자를 유지해야 하는 경우 --digits keep를 추가하세요.
8단계 — 게이트, 그런 다음 빌드
python3 $SKILL_DIR/scripts/revayat.py qa check \
--book $WORK/book.json --assets $WORK/assets --glossary $WORK/glossary.json
"ok"가 false인 동안 빌드하지 마세요. 오류 코드로 수정하세요:
| 코드 | 의미 | 조치 |
|---|---|---|
untranslated-block | 블록에 페르시아어 없음 | 해당 청크 번역 |
footnote-marker-lost | [[fn:…]]가 삭제됨 | 해당 청크 다시 실행 |
footnote-marker-invented | 마커가 아무것도 가리키지 않음 | 해당 청크 다시 실행 |
possible-omission | 대상이 소스보다 훨씬 짧음 | 읽어보기; 일반적으로 절 누락 |
untranslated | 페르시아어에 영어가 남아 있음 | 해당 청크 다시 실행 |
asset-missing / asset-modified | 그림이 없거나 변경됨 | 다시 추출 |
copied-source-run | 소스의 절이 페르시아어에 그대로 있음 | 해당 청크 다시 실행 |
duplicate-translation | 두 개의 다른 소스가 같은 페르시아어를 가짐 | 워크시트 응답이 두 번 붙여넣어짐; 둘 다 다시 실행 |
first-mention-repeated | 이름이 두 군데 이상에서 소개됨 | 첫 번째 유지, 나머지 삭제 |
image-order | 패키지에서 그림 순서가 잘못됨 | 다시 빌드 |
bookmarks-missing / bookmark-duplicate | 목차가 아무 곳도 링크하지 않거나 잘못된 곳을 링크함 | 다시 빌드 |
emphasis-parity (경고) | 굵게/기울임꼴 개수 변경됨 | 하나 확인; 대개 문제 없음 |
glossary-drift (경고) | 잠긴 이름이 다르게 렌더링됨 | 해당 청크 다시 실행 |
ocr-low-confidence (경고) | 엔진이 이 블록을 확신하지 못함 | 페이지 이미지를 열고 비교 |
--strict를 추가하여 출판 작업의 경우 마지막 세 개도 차단하도록 만드세요.
책의 제목과 저자를 book.json의 meta.title_target 및 meta.author_target으로 번역하세요. 이것이 유일하게 허용되는 수동 편집입니다. 이를 위한 워크시트가 없기 때문입니다.
그런 다음 빌드하세요:
python3 $SKILL_DIR/scripts/revayat.py build \
--book $WORK/book.json --assets $WORK/assets --out out/book.fa.docx \
--font "Vazirmatn" --size 11.5
유용한 플래그: 페르시아어 글꼴이 없는 시스템에서 렌더링해야 하는 경우 --font Tahoma; 원본 제목 포인트 크기를 재현하려면 --heading-size source; 기존 Word 파일의 스타일을 상속하려면 --template ref.docx. 전체 목록은 references/docx-and-ooxml.md를 참조하세요.
9단계 — 확인 및 보고
python3 $SKILL_DIR/scripts/revayat.py qa docx --file out/book.fa.docx --book $WORK/book.json
"ok": false이면 사용자에게 파일이 준비되었다고 말하기 전에 수정하세요.
그런 다음 보고하세요: 파일 위치, 장, 이미지 및 각주 수, QA에서 표시했지만 조치하지 않기로 선택한 모든 사항, 그리고 이 제한 사항:
Word는 텍스트를 다시 흐르게 하므로 편집 가능한 페르시아어 문서는 소스 PDF와 페이지별로 동일할 수 없습니다. 이미지 바이트 및 물리적 크기, 장 구조, 강조, 각주 및 장 링크는 정확합니다.
참조 자료
단계가 가리킬 때만 읽으세요:
references/translation-policy.md— 번역 하위 에이전트에 제공할 내용references/persian-typography.md— RTL, ZWNJ, 구두점, 혼합 스크립트references/extraction.md— OCR 라우팅, 워터마크, 어려운 책references/glossary-and-voice.md— 명명 정책, 별칭, 캐릭터 음성references/docx-and-ooxml.md— 모든 빌드 옵션 및 생성 결과references/troubleshooting.md— 발생할 가능성이 가장 높은 오류