在地化資訊圖表 PDF（保留美術設計）
產生一份翻譯版本的設計 PDF，外觀與原始版本完全相同，唯一差別是所有內文文字都換成目標語言。運作方式是將頁面點陣化、擦除源文字，然後將翻譯內容合成回相同座標位置——所有美術元素（照片、圖表、漸層、圖示、Logo）都不會重新生成。
為何採用此流程（請先閱讀）
設計軟體匯出的 PDF 通常將可見文字儲存為向量外框（文字轉曲線）或 Type3 字形——它們並非可編輯文字，也沒有乾淨的方法來「取代文字」。
但這些 PDF 通常也附帶一個隱藏的、可搜尋的文字圖層，其文字框與可見文字像素對齊。該圖層免費提供了精確的位置/大小資訊。
所以：不要嘗試編輯文字，也不要使用生成式影像模型來「重繪」背景——那樣會改變美術元素且無法做到像素忠實。相反地，採用遮蓋與覆蓋：擦除每個源文字的字形序列，並在相同位置重繪翻譯內容。背景保持位元組忠實。
更多詳細原理與失敗模式請參閱 references/pipeline.md。
工作流程（按順序從技能的 scripts/ 執行腳本）
選擇一個工作目錄（預設 loc_work）。所有腳本都接受 SOURCE.pdf [OUTDIR] [PAGE] 參數。
-
分析 —
01_analyze.py SOURCE.pdf OUTDIR確認文字如何儲存、列出內嵌圖片、渲染頁面。查看渲染結果，注意任何嵌入在圖表/Logo/照片影像中的文字（它們不會出現在文字圖層中，必須作為manual_labels處理）。 -
提取 —
02_extract.py SOURCE.pdf OUTDIR（環境變數LOC_KEEP='brandA|brandB'可保留更多源語言文字）。產生units.json（每個實體文字行一個條目，包含邊界框/顏色/大小）和translator_source.txt（一個可讀的、帶 ID 標記的承載檔案）以及half_*.png。 -
翻譯 — 派遣一個翻譯代理。將
translator_source.txt和half_0/1.png交給它。它必須寫入OUTDIR/translation.json = {"<id>":"译文", ...}涵蓋每個 ID（對於 KEEP-AS-IS 的 ID 保持不變）。使用references/agent-prompts.md中的提示。 -
覆蓋（僅在需要時） — 寫入
OUTDIR/overrides.json，用於自動引擎無法看到的文件特定部分：嵌入圖像中的文字（manual_labels）、位於細描邊控制項（如藥丸形狀/徽章）內部的文字（solid_fill_labels）、置中標籤區域（centered_id_ranges）以及drop_ids。結構與如何測量座標請參閱references/overrides.md。多數簡單傳單不需要覆蓋；圖表較多的文件可能需要少量設定。 -
合成 —
03_compose.py SOURCE.pdf OUTDIR→final_zh.png。這是確定性引擎（背景重建 + 統一大小的重繪）。每個文件不需要調整。 -
PDF 與裁切 —
04_pdf.py SOURCE.pdf OUTDIR OUT.pdf→ 產生 PDF 以及用於 QA 的zh_L/zh_R.png。 -
審查與迭代 — 派遣一個審查代理比較
zh_L/zh_R.png與half_0/1.png（提示在references/agent-prompts.md）。透過編輯overrides.json/translation.json修正問題，然後重新執行 03→04。重複直到乾淨。常見問題及其修復方式列於references/pipeline.md。
三個角色的循環（翻譯者 → 合成器 → 審查者）模擬人類在地化團隊；執行審查者 1-2 次即可捕捉到長尾問題（殘留源文字、尺寸錯誤的區塊）。
引擎自動處理的項目（無需設定）
- 淺色文字在深色背景上 以及 深色文字在淺色背景上的面板（自動選擇正確的背景顏色）。
- 平面面板、平滑漸層和照片背景（自動選擇填充或修補區域）。
- 「幽靈」文字圖層條目（沒有可見字形，自動跳過，永不繪製）。
- 項目符號列表（項目符號被第一個文字列吃掉的情況，自動重新對齊）。
- 字型大小：保持原始大小，每個區塊統一，使換行的段落/引言不會參差不齊。
預設值與需求
- Python：
pymupdf (fitz),numpy,opencv-python (cv2),Pillow。 - 中日韓字型預設
Hiragino Sans GB.ttc（macOS；W3 常規索引 0 / W6 粗體索引 2）。可透過overrides.json中的"font"覆蓋以支援其他語言/字型。 - 渲染比例預設為 6.0（約 432 dpi）。迭代時可降低至 4 以加快速度；印刷用途時提高。
- 預設保留源語言：URL、電子郵件、品牌/產品商標、Logo 內的嵌入文字、純數字/單位和專有名詞。由翻譯者決定；KEEP 正則表達式會預先標記明顯的項目。
參考檔案
references/pipeline.md— 原理、移除策略決策樹，以及常見視覺缺陷及其精確修復方法（條紋、殘留、破損的藥丸形狀、尺寸崩潰）的目錄。references/agent-prompts.md— 可直接複製使用的翻譯者和審查者代理提示。references/overrides.md—overrides.json結構以及如何測量圖表/藥丸形狀座標。