ePub Bilingual Translator - Architecture & Data Flow (Revised)

本文档详细描述了程序处理一个 EPUB 文件的完整生命周期。整个流程旨在实现结构稳定性（不丢段落）与内容精细度（不丢格式）的最佳平衡。

High Level Data Flow

graph TD
    Input[Input EPUB] --> Cleaner[EpubCleaner]
    Cleaner --> CleanedEPUB[1. Cleaned EPUB Temp]
    
    CleanedEPUB --> Profiler[Book Profiler]
    Profiler -->|Identify| Profile[Book Profile / Style]
    
    CleanedEPUB --> Extractor[FineGrainedExtractor]
    
    subgraph Extraction
        Extractor -->|Step 1: P/H Tags| P[Source Paragraph]
        P -->|Step 2: FormatExtract| PhText[Analyzed Text]
        PhText -->|Register| Manifest[Manifest DB]
    end
    
    Manifest -->|Batch| LLM[LLM Translation]
    Profile -->|Prompt Context| LLM
    
    LLM -->|Translation| Manifest
    
    Manifest --> Restorer[FormatRestorer]
    Restorer -->|Reconstruct HTML| TargetHtml[Target HTML]
    
    CleanedEPUB --> Backfiller[Backfill Engine]
    TargetHtml --> Backfiller
    
    Backfiller -->|Bilingual/Chinese Mode| DOM[Final DOM]
    DOM --> Builder[BilingualBuilder]
    Builder --> Output[Output EPUB]

Detailed Workflow

1. Preprocessing (预处理)

模块: src/epub_cleaner.py

Flatten Structure: 消除嵌套 div，统一转为 ，消除结构性漏译风险。
Auto-Fix: 修复 TOC 死链、缺失 UID、由于 ebooklib bug 导致的样式丢失。
Result: 产生一个标准的临时文件，后续所有操作基于此文件，不再受原始糟糕格式影响。

2. Intelligent Extraction (智能提取)

模块: src/fine_grained_extractor.py + src/format_extractor.py

A. 结构层 (Macro)

使用 FineGrainedExtractor 锁定所有正文元素 (p, h1-h6)。

Filter: 排除页码、页眉脚。
Optimization: 针对目录章节，识别 罗马数字 (I, II)、单独数字 (1, 2)、修饰符 ()，这些内容不送翻译*，直接在回填时保留原文，以维持原书排版美感。

B. 内容层 (Micro)

对每个提取的段落调用 FormatExtractor：

Inline Style: 将 ,  转为配对占位符 φ1φ...φ/1φ。
Formula Protection: 识别 E=mc^2 等数学公式，保护为不可变占位符。
Drop Cap Handling:
- 原始: The
- 提取给 LLM: "The" (完整单词，无格式干扰)
- 记录: Prefix 包含 Drop Cap 样式。

3. Manifest Management (清单管理)

模块: src/manifest_manager.py Manifest 是系统的核心状态中心 (Source of Truth)。

作用: 解耦提取和翻译。提取器只管往 Manifest 填数据，翻译器只管从 Manifest 取数据。
Persistence: 支持中断续传，翻译进度实时保存。

4. Translation with Profiling (翻译)

模块: src/book_profiler.py & src/translator.py

Profiling: 在翻译前，抽取部分文本分析书籍的类型（技术、小说、诗歌）、核心术语和语言风格，生成 System Prompt。
Translation: 这是纯文本层面的转换，LLM 处理的是带有 φ 占位符的文本。

5. Robust Restoration (健壮还原)

模块: src/format_restorer.py 负责将 LLM 返回的文本还原为 HTML。

Drop Cap Logic:
- 原文回填: 需要 Prefix T。
- 译文回填: 丢弃 Drop Cap Prefix。中文不需要首字母下沉，否则会出现 "T这本书..." 的怪诞结果。
Error Handling:
- Missing Placeholders: 如果 LLM 丢了 φ1φ，自动在末尾补全或报错重试。
- Hallucinated Placeholders: 移除 LLM 臆造的不存在 ID。

6. Backfill Strategy (回填策略)

模块: src/fine_grained_extractor.py (backfill method) 支持多种模式，且严格遵循一对一 (One-to-One) 映射，绝不依赖顺序，而是依赖元素的内存引用或唯一 ID。

Mode A: Bilingual (双语)
- 保留原文 DOM。
- 在原文后 append 一个新元素 译文。
- 样式继承：译文元素复制原文的 margin, text-align 等关键样式。
Mode B: Chinese Only (仅中文)
- Replace: 直接用译文元素替换原文元素。
- Drop Cap 适配: 此时译文通常为普通段落，不再保留首字母下沉样式，以符合中文排版习惯。

7. Assembly (组装)

模块: src/bilingual_builder.py 将内存中的 DOM 序列化，重新打包资源，生成最终 EPUB。

4.6 KiB Raw Blame History Unescape Escape