# 预处理与回填层技术文档 本文档详细描述 EPUB 双语翻译器的预处理（Preprocessing）和回填（Backfill）层的技术方案、数据结构、问题解决方案，用于指导代码开发、调试和维护。 --- ## 1. 架构概览 ``` ┌─────────────┐ ┌────────────────┐ ┌───────────────────┐ │ EPUB 文件 │ ──► │ EpubCleaner │ ──► │ book_structure.json│ └─────────────┘ └────────────────┘ └───────────────────┘ │ ▼ ┌────────────────┐ ┌───────────────────┐ │FineGrainedExt. │ ──► │ manifest.json │ └────────────────┘ └───────────────────┘ │ ┌────────────────┐ │ │ BackfillEngine │ ◄───────────┘ └────────────────┘ │ ▼ ┌────────────────┐ ┌───────────────────┐ │BilingualBuilder│ ──► │ 输出 EPUB │ └────────────────┘ └───────────────────┘ ``` --- ## 2. 目录结构 ``` work/ ├── {book_name}/ # 每本书独立的工作目录 │ ├── book_structure.json # 书籍结构（会被复用） │ ├── manifest.json # 翻译清单（持久化，Source of Truth） │ └── assets/ # 解压出的 EPUB 资源文件 │ └── OEBPS/images/... # 保留原始路径结构 └── translations/ # (可选) 翻译记忆或其他中间文件 ``` **关键设计**：`book_structure.json` **默认复用**。为避免 UUID 不一致导致回填失败，除非显式指定强制清理，否则程序优先读取现有的结构文件。 --- ## 3. 数据结构定义 ### 3.1 BookStructure (book_structure.json) 记录书籍的“骨架”，确保翻译后的章节能按正确顺序和层级重组。 ```json { "metadata": { "title": "书名", "author": "作者", "language": "en", "identifier": "ISBN或UUID" }, "spine": ["item_id_1", "item_id_2", ...], // 阅读顺序 "resources": { "item_id_1": { "href": "OEBPS/chapter1.xhtml", "media_type": "application/xhtml+xml", "content": "...", // 清理并注入ID后的HTML内容 "properties": "nav" }, ... } } ``` ### 3.2 ManifestEntry (manifest.json) 翻译清单是全生命周期的核心，记录了所有待翻译段落的状态。 ```json [ { "entry_id": "OEBPS/c3Z.xhtml#uuid-603ff3fb", "file_path": "OEBPS/c3Z.xhtml", "element_id": "uuid-603ff3fb", "original_text": "φ1φHelloφ/1φ world.", "placeholders": { "1": "", "/1": "", "_prefix": "

", "_suffix": "

" }, "translated_text": "φ1φ你好φ/1φ 世界。", "context": "body" } ] ``` | 字段 | 类型 | 说明 | |------|------|------| | `entry_id` | str | **全局唯一ID** (`file_path#element_id`)，用于精准追踪。 | | `file_path` | str | 标识该段落属于哪一章，用于按章分组批处理。 | | `element_id` | str | HTML DOM 元素的 ID，回填时的锚点。 | | `original_text` | str | 经过智能抽提和占位符化后的文本，发送给 LLM。 | | `placeholders` | Dict | 格式映射表，用于还原 HTML 结构。 | | `translated_text`| str | 翻译结果（含占位符），初始为 null。 | --- ## 4. 预处理与抽提流程 (Extraction) 流程由 `FormatExtractor` 驱动，分为三个阶段： ### Step 1: 结构索引 (Structure Indexing) * **动作**: 解析 OPF 文件，提取 Spine 和 Metadata。 * **目的**: 建立骨架，确定处理顺序。 ### Step 2: 语义识别 (Semantic Detection) * **动作**: 使用 `HeadingDetector` 分析 DOM 节点。 * **逻辑**: * 匹配 `h1`-`h6` 正则，区分 `Chapter`（章）与 `Section`（节）。 * 识别 `blockquote` 或特定 class 判定 `Epigraph`（引言）。 * **目的**: 为 LLM 提供差异化的 Prompt（例如翻译标题时不要加句号）。 ### Step 3: 智能抽提 (Smart Extraction - `_smart_extract_v3`) 这是核心算法，将 HTML 转换为“纯文本+占位符”。 1. **首尾分离 (Prefix/Suffix Separation)**: * 将包裹文本的外层标签（如 `

`, `div`）剥离到 `_prefix` 和 `_suffix`。 * **目的**: 极大减少 LLM 输入 Token，且防止 LLM 随意修改外层布局。 2. **首字下沉处理 (Drop Cap Handling)**: * 检测并合并被 `` 单独包裹的首字母（如 `O` + `nce` → `Once`）。 * **目的**: 修复语意割裂，让 LLM 看到完整的单词。 3. **占位符化 (Placeholder Mapping)**: * 将内联标签（``, ``）或公式替换为短码 `φIDφ`。 * **目的**: 保护 HTML 属性不被“翻译”，降低噪声干扰。 4. **完整性校验 (Integrity Check)**: * **逻辑**: 抽提后的文本（去占位符）与原始纯文本进行归一化比对，要求覆盖率 **100%**。 * **兜底**: 若校验失败（如误删内容），回退到简单模式（只剥离首尾标签）。 --- ## 5. 构建与回填流程 (Backfill & Build) ### 5.1 翻译回填 * 根据 `entry_id` 找到对应的 DOM 节点。 * 使用 `FormatRestorer` 将 `translated_text` 中的占位符（`φ1φ`）还原为原始 HTML 标签（``）。 * 根据模式（双语/单语）决定将新节点插入到原文后还是替换原文。 ### 5.2 链接修复 (Link Repair) 在 `BilingualBuilder` 中执行： 1. **ID 补全**: 为缺失 ID 的 TOC 节点自动生成 UUID。 2. **死链检测**: 检查 TOC/Nav 指向的文件是否存在。 3. **模糊修复**: 尝试通过文件名后缀匹配（解决路径前缀变更问题）或特定重定向（如 `c0.xhtml` -> `cover.xhtml`）。 4. **坏死剔除**: 无法修复的死链将从目录中移除。 ### 5.3 CSS 样式恢复 `EbookLib` 默认可能会重写 `` 导致样式丢失。 * **逻辑**: * 收集所有 CSS 资源。 * 在构建每个 HTML Item 时，显式计算 HTML 到 CSS 的**相对路径**。 * 强制调用 `item.add_link(..., rel='stylesheet', type='text/css')` 注入引用。 --- ## 6. 常见问题排查 ### 6.1 UUID 不匹配 **现象**: `WARNING - Element uuid-xxx not found`. **原因**: 手动删除了 `book_structure.json` 但保留了 `manifest.json`，导致重新生成的 HTML ID 与清单记录不一致。 **解决**: 清空 `work/BookName` 目录重新运行，或确保两个 JSON 文件版本一致。 ### 6.2 样式丢失 **现象**: 打开书面目全非，只有黑白文字。 **检查**: 解压 EPUB，查看 HTML `` 是否有 ``。如果没有，检查 `BilingualBuilder` 的 Step 4 逻辑。 ### 6.3 翻译错位 **现象**: 译文出现在了错误的位置。 **检查**: 确认 `entry_id` 生成逻辑是否包含文件名，且文件名在处理过程中未被意外修改。