Revayat Novel — 영어 → 페르시아어 책 번역
아래 9단계를 순서대로 실행합니다. 각 단계는 명령어와 출력 처리 규칙으로 구성됩니다. 순서를 임의로 바꾸거나 이전 단계가 괜찮아 보인다고 다음 단계를 건너뛰지 마십시오.
네 가지 변수를 한 번 설정한 후 모든 곳에서 사용합니다:
SKILL_DIR— 이 파일이 있는 폴더입니다. Claude Code 플러그인에서는${CLAUDE_PLUGIN_ROOT}/skills/revayat-novel입니다.WORK— 이 책의 작업 폴더입니다 (예:work/).PY— Python 인터프리터. 한 번 확인하십시오.python3는 대부분의 Windows 설치에 존재하지 않으므로, 이를 하드코딩한 명령줄은 세 플랫폼 중 두 개에서만 작동합니다:- macOS / Linux:
PY=python3 - Windows:
PY=python— 또는PY="py -3"(런처가 설치된 경우) - 둘 다 실행되지 않으면 1단계의
doctor가 시작되지 않으며, 이것이 신호입니다.
- macOS / Linux:
OCR_LANG— 번역 중인 책에 인쇄된 언어의 Tesseract 코드이며, 번역 대상 언어가 아닙니다. 일반적인 영어 → 페르시아어 작업의 경우eng입니다. 페르시아어 원본은fas, 독일어는deu, 프랑스어는fra, 아랍어는ara입니다. 모든 OCR 단계에서 동일한 값을 사용해야 합니다. 페르시아어 모델로 영어 페이지를 인식하면 자신 있는 듯한 무의미한 결과가 나오며, 이는 낮은 점수보다 더 나쁩니다. 다운스트림에서 이를 감지할 수 없기 때문입니다.
모든 명령어는 $PY $SKILL_DIR/scripts/revayat-novel.py <단계> … 형식입니다.
절대 깨지면 안 되는 다섯 가지 규칙
- 페르시아어 텍스트를 절대 반전시키지 마십시오 (오른쪽에서 왼쪽으로 읽히도록). 방향은 빌더가 설정합니다. 반전시키면 한 뷰어를 제외한 모든 곳에서 깨진 파일이 생성됩니다.
- 절대
@@ id헤더를 만들거나, 삭제하거나, 병합, 분할 또는 재정렬하지 마십시오. 제공된 헤더를 정확히 반환하십시오. - 절대
[[fn:…]],**bold**,*italic*또는`verbatim`마커를 삭제하지 마십시오. 이들은 계산되며, 불일치는 QA에 실패합니다. - 번역을 수정하기 위해
book.json을 절대 수동 편집하지 마십시오. 워크시트를 수정하고 병합을 다시 실행하십시오. - 절대 책을 축약하지 마십시오. 요약, 어려운 문장 건너뛰기, 순화 금지. 단계에서 콘텐츠 누락이 보고되면 해당 청크를 다시 실행하십시오.
1단계 — 도구 확인
$PY $SKILL_DIR/scripts/revayat-novel.py doctor
"ready": true→ 계속 진행합니다."ready": false→pip install -r $SKILL_DIR/requirements.txt를 실행한 후doctor를 다시 실행합니다.optional_tools에not found가 표시되어도 지금은 괜찮습니다. 2단계에서 OCR이 실제로 필요한지 알려줄 것입니다.
2단계 — 추출
$PY $SKILL_DIR/scripts/revayat-novel.py extract "<입력 파일>" --out $WORK --ocr-lang $OCR_LANG
$OCR_LANG은 책에 인쇄된 언어이며, 위에서 한 번 설정했습니다. 여기서 잘못 설정해도 눈에 띄는 실패는 아닙니다. OCR은 여전히 텍스트를 반환하지만, 단순히 잘못된 텍스트일 뿐입니다.
출력된 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를 사용하십시오.
책이 스캔된 경우, 지금 다음 두 가지 추가 패스를 실행하십시오.
인식 신뢰도 — 이것 없이는 잘못 읽은 단어와 올바른 단어를 구분할 수 없습니다. 둘 다 소스 언어의 일반적인 단어이며 문법적 문장 안에 있기 때문입니다. 파이프라인 후반부에서도 이들을 구분할 수 없으며, 번역기는 잘못된 단어를 충실히 렌더링합니다.
$PY $SKILL_DIR/scripts/revayat-novel.py ocr-sidecar \
--pdf $WORK/ocr.pdf --out $WORK --lang $OCR_LANG --book $WORK/book.json
여기서 --lang은 extract에 제공한 **동일한 $OCR_LANG**입니다. 그래야 합니다. 이 패스는 동일한 페이지를 재인식하여 엔진의 확신 정도를 알아냅니다. 다른 모델은 다른 단어를 읽고 책에 없는 내용을 점수화합니다.
이 명령은 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 en
$PY $SKILL_DIR/scripts/revayat-novel.py extract "<입력 파일>" --out $WORK \
--figures-from-mineru $WORK/mineru
MinerU의 -l은 Tesseract와 다른 자체 코드를 사용합니다: 영어 소스는 en, 페르시아어 또는 아랍어 스크립트는 arabic. $OCR_LANG과 동일한 방식으로 책과 일치시킵니다 — 레이아웃 감지는 스크립트를 사용하여 페이지를 분할합니다.
원본이 아닌 cleaned.pdf에 대해 MinerU를 실행하십시오. 그렇지 않으면 워터마크를 그림으로 자릅니다. MinerU에서 그림만 가져오십시오. 실제 페르시아어 스캔에서 측정한 결과, MinerU의 자체 인식 텍스트는 단어와 그 안의 문자가 반전되어 돌아온 반면, Tesseract는 동일한 페이지를 올바르게 읽었습니다. 따라서 텍스트는 계속 위의 OCR 패스에서 가져오고 MinerU는 OCR이 할 수 없는 한 가지, 즉 평평한 래스터에서 그림이 어디에 있는지 찾는 데만 사용됩니다. MinerU가 페이지 범위에 대해 실행된 경우 --figures-page-offset N을 사용하십시오.
그런 다음 더 진행하기 전에 결과를 확인하십시오:
$PY $SKILL_DIR/scripts/revayat-novel.py qa check --book $WORK/book.json --allow-incomplete
여기서 untranslated-block은 무시하십시오. 아직 번역된 것이 없습니다. asset-missing을 찾으십시오. 실제 책에서 stats.text_blocks가 20 미만이면 추출에 실패한 것입니다. references/extraction.md를 참조하십시오.
3단계 — 용어집
$PY $SKILL_DIR/scripts/revayat-novel.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
항목에 aliases — 책에서 단독으로 사용하는 성 또는 이름 — 가 있는 경우 페르시아어를 alias_targets에 입력합니다:
"aliases": ["Ashcroft", "Margaret"],
"alias_targets": ["اشکرافت", "مارگارت"]
소스에서 "Ashcroft"만 언급된 경우, 페르시아어는 "اشکرافت"만 사용해야 합니다. 이 필드를 비워두면 드리프트 검사가 매번 전체 이름을 요구하게 되어 페르시아어로서도 좋지 않고 오경보를 발생시킵니다.
first_block_id는 그대로 두십시오 — 파이프라인이 이름을 소개하는 단일 청크를 결정하는 데 사용합니다. 편집하거나 첫 번째 언급을 직접 결정하지 마십시오.
실제 이름이 아닌 항목은 삭제하십시오. 그런 다음 계속 진행합니다.
4단계 — 워크시트로 분할
전체 소설은 절대 하나의 모델 컨텍스트에 도달해서는 안 되므로 먼저 분할됩니다. 분할하는 방법은 두 가지이며, 소스가 결정합니다 — 이것은 선호도가 아닙니다:
| 소스 | 경로 |
|---|---|
| PDF (디지털 또는 스캔) | 페이지별 — 아래 |
| EPUB, DOCX, 일반 텍스트 | 문자 예산별 — 4b단계 |
PDF를 페이지별로 분할합니다. 페이지는 책에 이미 존재하는 경계입니다: 실행 간에 안정적이며, 검토자가 보는 단위이며, 렌더링된 페이지를 비교할 수 있는 유일한 단위입니다. 문자 예산으로 분할된 워크시트는 예산이 소진되는 곳에서 끊어지는데, 이는 특정 지점이 아니며 — 소스에 존재하지 않는 페이지는 소스와 비교하여 확인할 수 없습니다. 아래 줄의 형식에는 자체 페이지가 없으므로 예산 경로를 따르고 해당 검사를 포기합니다.
$PY $SKILL_DIR/scripts/revayat-novel.py pages build \
--book $WORK/book.json --out $WORK/pages --glossary $WORK/glossary.json
이 명령은 소스 페이지당 하나의 워크시트를 작성합니다 — page0001.md이며, 번역은 같은 위치에 out_page0001.md로 저장됩니다. 5단계의 chunkNNNN.md가 아닌 이 이름을 사용하십시오: 형식은 동일하며 파일 이름만 다르고, pages next는 열어야 할 정확한 파일을 알려주므로 추측할 필요가 없습니다.
또한 $WORK/pages/source/page-0001.pdf를 작성합니다 — 각 소스 페이지를 자체 PDF로 복사하며(다시 렌더링하지 않으므로 상자, 회전 및 이미지 품질이 책 자체와 동일), 매니페스트는 각각의 SHA-256과 함께 reference_pdf(전체 실행을 읽은 PDF)를 기록합니다. 매니페스트에서 소스 PDF를 읽으십시오. 디지털 도서의 경우 원본이고 스캔의 경우 OCR된 사본이며, 둘 중 하나를 하드코딩하면 다른 경우에 잘못됩니다.
각 페이지 작업은 필요한 것만 전달합니다: 해당 페이지에 적용되는 용어집 행, 그곳에서 말하는 음성, OCR이 확실하지 않은 단어, 그리고 번역하지 말 것으로 표시된 인접 페이지의 제한된 조각입니다. 자체 텍스트가 예산을 초과하는 페이지는 잘리는 대신 번호가 매겨진 부분으로 분할되며 (part 및 parts가 매니페스트에 표시됨), 부분은 페이지가 평가되기 전에 다시 합쳐집니다.
페이지 나누기로 반으로 잘린 단락은 시작된 페이지에 속하며 정확히 한 번 번역됩니다. 그 위로 넘어가는 페이지는 컨텍스트로만 볼 수 있습니다. 이웃 컨텍스트 제목 아래에 나타나는 블록을 절대 번역하지 마십시오 — 이미 다른 페이지의 워크시트에 속합니다.
$PY $SKILL_DIR/scripts/revayat-novel.py pages status --pages $WORK/pages
$PY $SKILL_DIR/scripts/revayat-novel.py pages next --pages $WORK/pages
status는 모든 페이지의 상태를 보고합니다. next는 아직 처리되지 않은 첫 번째 페이지의 이름을 알려주므로 중단된 실행이 처음부터가 아닌 중단된 지점에서 재개됩니다.
페이지 루프
소스 PDF는 이 실행이 읽은 PDF입니다: 디지털 PDF 도서의 경우 책 자체의 PDF, 스캔의 경우 OCR된 사본입니다. 매니페스트가 기록했습니다 — 존재하지 않을 수 있는 파일을 지정하는 대신 매니페스트에서 가져오십시오.
SOURCE_PDF=$($PY -c "import json,sys;print(json.load(open(sys.argv[1]))['reference_pdf'])" $WORK/pages/manifest.json)
한 번에 한 페이지씩, 다음 순서로 진행합니다. 각 명령어는 이전 명령어가 생성한 것이 필요하므로, 너무 일찍 실행된 단계는 단순히 거부합니다:
P=12 # `pages next`가 방금 지정한 값
# 3. 번역을 책에 병합
$PY $SKILL_DIR/scripts/revayat-novel.py pages merge \
--book $WORK/book.json --pages $WORK/pages --page $P --glossary $WORK/glossary.json
# 4. 해당 페이지를 단독으로 레이아웃
$PY $SKILL_DIR/scripts/revayat-novel.py pages preview \
--book $WORK/book.json --pages $WORK/pages --page $P
# 5. 소스 페이지와 비교
$PY $SKILL_DIR/scripts/revayat-novel.py render-qa \
--book $WORK/book.json --work $WORK --page $P \
--docx $WORK/previews/page-0012.docx --source-pdf $SOURCE_PDF
# 6. 두 이미지를 살펴봄 (8단계에서 무엇을 찾아야 하는지 설명)
$PY $SKILL_DIR/scripts/revayat-novel.py pages review \
--pages $WORK/pages --page $P \
--answer figure-placement=yes --answer script-integrity=yes \
--answer no-source-language=yes --answer hierarchy=yes \
--answer reads-as-a-book=yes --note "본 내용"
# 7. 이제서야 수락
$PY $SKILL_DIR/scripts/revayat-novel.py pages accept \
--book $WORK/book.json --pages $WORK/pages --page $P
그런 다음 pages next를 다시 실행하여, 더 이상 남은 것이 없다고 말할 때까지 반복합니다.
4단계는 선택 사항이 아니며, 건너뛰면 5단계가 자동으로 수행합니다 — --docx를 생략하면 render-qa가 자체적으로 미리보기를 빌드합니다. 명시적 명령은 Word에서 페이지를 열어 직접 보고 싶을 때 사용합니다.
미리보기는 하나의 소스 페이지를 단독으로 레이아웃한 것입니다. 이것은 결코 전체 책이 아닙니다: 페르시아어는 재배치되므로 소스 페이지 12가 책의 12페이지가 되지 않으며, 소설 중반쯤이면 드리프트가 몇 페이지에 달합니다. 책의 12번째 시트를 12페이지의 기대치와 비교하면 올바른 페이지가 모든 텍스트를 누락하고 이웃의 텍스트를 전달하는 것으로 보고됩니다. 미리보기는 프로덕션 빌더와 동일한 스타일, 글꼴, RTL, 이미지 크기 조정, 제목 논리를 사용하여 설정되므로 보이는 것은 실제 콘텐츠의 실제 조판입니다.
페르시아어가 영어보다 길게 실행되는 페이지는 두 장으로 나옵니다. 이것은 정상이며, 둘 다 renders/target/page-0012.png 및 page-0012-2.png로 유지되며 QA는 모두 읽습니다.
accept는 모든 게이트가 실제로 통과되지 않으면 거부합니다 — 사용자의 말을 받아들이지 않고 증거를 읽으므로, 페이지가 완료되었다고 주장하여 표시할 수 없습니다. 네 가지를 요구합니다: 페이지가 보낸 모든 단위에 대한 페르시아어, 실행 기록에 대한 렌더 QA 통과, 여전히 그렇게 말하는 보고서, 그리고 현재의 시각적 검토.
재구축은 안전하며 번역을 절대 버리지 않습니다. 마지막으로 분할된 이후 소스 텍스트가 변경된 페이지는 invalidated 아래에 나열됩니다 — 해당 페이지와 해당 페이지만 다시 번역해야 합니다. 다른 예산으로 재구축에서 남은 워크시트는 orphaned 아래에 나열됩니다: 디스크에 여전히 존재하지만 더 이상 아무도 읽지 않으므로 번역이 책에 도달하지 않습니다.
4b단계 — 소스에 페이지가 없는 경우
EPUB, DOCX 및 일반 텍스트 전용입니다. PDF의 경우 4단계를 사용하십시오.
$PY $SKILL_DIR/scripts/revayat-novel.py chunk build \
--book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json
청크 수를 확인하십시오. 각각은 하나의 번역 작업이 됩니다.
이미 일부 워크시트를 번역했는데 그 이후에 입력이 변경된 경우, "refused": "stale-worksheets"와 함께 거부되며 조용히 책과 더 이상 일치하지 않는 워크시트를 제공하지 않습니다.
…
[번역을 위해 잘림]