谭凯
7a93c52b42
- Refactor codebase into src/ (preprocessing, translation, assembly) - Add pipeline/ scripts for individual stages - Externalize configuration to config/config.yaml - Fix Cover Image preservation - Update documentation and manuals
101 lines
4.6 KiB
Markdown
101 lines
4.6 KiB
Markdown
# ePub Bilingual Translator - Architecture & Data Flow (Revised)
|
||
|
||
本文档详细描述了程序处理一个 EPUB 文件的完整生命周期。整个流程旨在实现**结构稳定性**（不丢段落）与**内容精细度**（不丢格式）的最佳平衡。
|
||
|
||
## High Level Data Flow
|
||
|
||
```mermaid
|
||
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`，统一转为 `<p>`，消除结构性漏译风险。
|
||
* **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**: 将 `<b>`, `<i>` 转为配对占位符 `φ1φ...φ/1φ`。
|
||
* **Formula Protection**: 识别 $E=mc^2$ 等数学公式，保护为不可变占位符。
|
||
* **Drop Cap Handling**:
|
||
- 原始: `<span class="dropcap">T</span>he`
|
||
- 提取给 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 `<span class="dropcap">T</span>`。
|
||
- **译文回填**: **丢弃** 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` 一个新元素 `<p class="translation">译文</p>`。
|
||
- 样式继承：译文元素复制原文的 `margin`, `text-align` 等关键样式。
|
||
|
||
* **Mode B: Chinese Only (仅中文)**
|
||
- **Replace**: 直接用译文元素替换原文元素。
|
||
- **Drop Cap 适配**: 此时译文通常为普通段落，不再保留首字母下沉样式，以符合中文排版习惯。
|
||
|
||
### 7. Assembly (组装)
|
||
**模块**: `src/bilingual_builder.py`
|
||
将内存中的 DOM 序列化，重新打包资源，生成最终 EPUB。
|