sulipapa/localize-infographic-pdf

인포그래픽 PDF 현지화 (아트워크 보존)

디자인 PDF를 번역된 버전으로 제작하며, 원본과 동일하게 보이되 모든 본문 텍스트만 대상 언어로 교체합니다. 페이지를 래스터화하고, 소스 텍스트를 지운 뒤, 동일한 좌표에 번역문을 합성하는 방식으로 작동합니다. 사진, 차트, 그라데이션, 아이콘, 로고 등 아트워크는 절대 다시 생성되지 않습니다.

이 파이프라인을 사용하는 이유 (먼저 읽기)

디자인으로 내보낸 PDF는 일반적으로 보이는 텍스트가 벡터 외곽선(텍스트-투-커브) 또는 Type3 글리프로 저장되어 있어 편집 가능한 텍스트가 아니며, "텍스트를 교체"하는 깔끔한 방법이 없습니다. 하지만 이러한 PDF는 거의 항상 보이는 텍스트와 픽셀 단위로 정렬된 단어 상자를 가진 숨겨진 검색 가능 텍스트 레이어도 함께 포함합니다. 이 레이어는 정확한 위치와 크기를 무료로 제공합니다. 따라서 텍스트를 편집하려고 시도하지 말고, 생성형 이미지 모델을 사용해 배경을 "다시 칠하지" 마십시오. 이는 아트워크를 변경하고 픽셀 단위로 정확하지 않습니다. 대신, 덮고 오버레이하십시오. 각 소스 글리프 실행을 지우고 번역문을 제자리에 다시 그리면 배경은 바이트 단위로 그대로 유지됩니다. 자세한 근거와 실패 모드는 references/pipeline.md를 참조하십시오.

워크플로우 (스킬의 scripts/에 있는 스크립트를 순서대로 실행)

작업 디렉토리를 선택합니다(기본값 loc_work). 모든 스크립트는 SOURCE.pdf [OUTDIR] [PAGE] 인수를 받습니다.

1. 분석 — 01_analyze.py SOURCE.pdf OUTDIR 텍스트가 어떻게 저장되었는지 확인하고, 포함된 이미지를 나열하며, 페이지를 렌더링합니다. 렌더링 결과를 보고 차트/로고/사진 이미지에 굽혀진 텍스트가 있는지 확인하십시오(이 텍스트는 텍스트 레이어에 없으며 manual_labels로 처리해야 함).

2. 추출 — 02_extract.py SOURCE.pdf OUTDIR (환경 변수 LOC_KEEP='brandA|brandB'를 설정하여 더 많은 문자열을 소스 언어로 유지). units.json(물리적 텍스트 줄 하나당 항목 하나, bbox/색상/크기 포함)과 translator_source.txt(읽기 쉬운 ID 태그가 있는 페이로드) 및 half_*.png를 생성합니다.

3. 번역 — 번역 에이전트에 작업을 할당합니다. translator_source.txt와 half_0/1.png를 제공합니다. 에이전트는 모든 ID를 포함하는 OUTDIR/translation.json = {"<id>":"译文", ...}를 작성해야 합니다(KEEP-AS-IS ID는 변경하지 않고 그대로 반영). references/agent-prompts.md의 프롬프트를 사용하십시오.

4. 오버라이드(필요한 경우에만) — 자동 엔진이 감지할 수 없는 문서별 요소에 대해 OUTDIR/overrides.json을 작성합니다: 이미지에 굽혀진 텍스트(manual_labels), 얇은 선으로 그려진 컨트롤(알약/배지 등) 내부 텍스트(solid_fill_labels), 중앙 정렬 레이블 영역(centered_id_ranges), drop_ids. 스키마 및 좌표 측정 방법은 references/overrides.md를 참조하십시오. 대부분의 단순한 전단지에는 오버라이드가 필요하지 않으며, 차트가 많은 문서에는 몇 개만 필요합니다.

5. 합성 — 03_compose.py SOURCE.pdf OUTDIR → final_zh.png. 결정론적 엔진(배경 재구성 + 크기 통일 재그리기)입니다. 문서별 조정이 필요하지 않습니다.

6. PDF 및 크롭 — 04_pdf.py SOURCE.pdf OUTDIR OUT.pdf → PDF 및 QA용 zh_L/zh_R.png.

7. 검토 및 반복 — 검토 에이전트에 작업을 할당하여 zh_L/zh_R.png를 half_0/1.png와 비교합니다(references/agent-prompts.md의 프롬프트). 결과를 수정하려면 overrides.json / translation.json을 편집하고 03→04 단계를 다시 실행하십시오. 깨끗해질 때까지 반복합니다. 일반적인 문제와 해결 방법은 references/pipeline.md에 나열되어 있습니다.

3역할 루프(번역가 → 합성기 → 검토자)는 인간 현지화 팀을 모방합니다. 검토자를 1~2회 실행하면 긴 꼬리 문제(잔여 소스 텍스트, 잘못된 크기의 블록)가 잡힙니다.

엔진이 자동으로 처리하는 항목 (설정 불필요)

• 밝은 배경의 어두운 텍스트와 어두운 배경의 밝은 텍스트 패널 모두 처리(올바른 배경색 선택).
• 평평한 패널, 부드러운 그라데이션, 사진 배경(영역별로 채우기 대 인페인트 선택).
• 보이는 글리프가 없는 "유령" 텍스트 레이어 항목(자동 건너뜀 — 절대 그리지 않음).
• 글머리 기호가 첫 번째 행의 상자에 포함된 목록(자동 재정렬).
• 글꼴 크기: 원본 크기, 블록별로 통일되어 줄바꿈된 단락/인용문이 들쭉날쭉해지지 않음.

기본값 및 요구 사항

• Python: pymupdf (fitz), numpy, opencv-python (cv2), Pillow.
• CJK 글꼴 기본값 Hiragino Sans GB.ttc(macOS; W3 일반 인덱스 0 / W6 굵게 인덱스 2). 다른 언어/글꼴의 경우 overrides.json의 "font"로 재정의합니다.
• 렌더링 배율 기본값 6.0(≈432dpi). 반복 중 속도를 위해 4로 낮추고, 인쇄용으로는 높입니다.
• 기본적으로 소스 언어로 유지: URL, 이메일, 브랜드/제품 상표, 로고에 굽혀진 텍스트, 숫자/단위, 고유 명사. 번역기가 결정하며, KEEP 정규식이 명백한 항목을 사전 표시합니다.

참조 파일

• references/pipeline.md — 근거, 제거 전략 결정 트리, 일반적인 시각적 결함 및 정확한 해결 방법 카탈로그(줄무늬, 잔여물, 깨진 알약, 크기 붕괴).
• references/agent-prompts.md — 바로 복사하여 사용할 수 있는 번역기 및 검토자 에이전트 프롬프트.
• references/overrides.md — overrides.json 스키마 및 차트/알약 좌표 측정 방법.