xin61
136 lines
7.2 KiB
Markdown
136 lines
7.2 KiB
Markdown
# 双语 EPUB 审校编辑器
|
||
|
||
当前版本：`0.4.1`
|
||
|
||
这个工具用于把生成后的中日双语 EPUB 打开成浏览器审校界面。用户可以直接修改中文译文，也可以标记“哪里翻得不好”，并把所有记录沉淀为可交给 Codex 的反馈文件。
|
||
|
||
## 版本规则
|
||
|
||
维护版本号使用 `version = "0.1.0"` 这种语义化格式：
|
||
|
||
| 层级 | 触发条件 |
|
||
| --- | --- |
|
||
| PATCH | 修复 bug 或兼容性小修 |
|
||
| MINOR | 新增向后兼容能力、API 字段或可选配置 |
|
||
| MAJOR | 破坏兼容的 API、配置或行为变更 |
|
||
|
||
本次从 `0.1.0` 升到 `0.2.0`，因为新增了独立上传、会话管理、下载接口与可选 `--host` 配置，且保持原命令行 EPUB 路径用法兼容。
|
||
|
||
`0.2.1` 修复目录章节识别：优先读取 EPUB 内部目录页的中文标题，并把目录锚点之间的多个正文 part 合并为同一章；左侧目录增加章节展开/收起按钮。
|
||
|
||
`0.3.0` 新增插图阅读能力：目录中会把 EPUB spine 里的插图页作为独立章节显示，阅读模式可直接查看图片；正文子章节标题统一使用 `part0000` 这类规整编号，方便长篇审校快速定位。
|
||
|
||
`0.4.0` 新增阅读型交互与 GPT 重翻：左侧目录/检索改为按需打开的独立侧栏；阅读模式去掉每段下方操作按钮，点击段落直接打开右侧精修与重翻面板，并在面板挤开正文后恢复原阅读位置；本地可配置 OpenAI 兼容 GPT API，对单段生成重翻候选，确认后再应用到编辑框。
|
||
|
||
`0.4.1` 修复后端/API 安全与结构细节：章节内插图与文字按 spine 顺序 flush，结构统计补充 text/image 细分字段；内部目录识别增加目录页/链接密度判定；结构和 `/api/asset` 仅允许已识别的 raster 图片并加 `nosniff`；重翻接口不再允许单次请求临时覆盖 Base URL 或模型后复用已保存密钥。
|
||
|
||
## 独立安装
|
||
|
||
这个审校器现在可以脱离 Codex 使用，只需要 Python 和浏览器。把 `tools/epub_review_editor` 目录复制到其他电脑或服务器后，在该目录里安装依赖：
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\python -m pip install -r requirements.txt
|
||
```
|
||
|
||
Linux/macOS：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
./.venv/bin/python -m pip install -r requirements.txt
|
||
```
|
||
|
||
## 启动
|
||
|
||
不预先指定 EPUB，直接打开上传界面：
|
||
|
||
```powershell
|
||
$env:PYTHONIOENCODING='utf-8'
|
||
python 'C:\Users\xin61\Documents\轻小说翻译持续改进\tools\epub_review_editor\server.py'
|
||
```
|
||
|
||
也可以像原来一样直接打开某个 EPUB：
|
||
|
||
```powershell
|
||
$env:PYTHONIOENCODING='utf-8'
|
||
python 'C:\Users\xin61\Documents\轻小说翻译持续改进\tools\epub_review_editor\server.py' '<中日双语版.epub>' --daemon
|
||
```
|
||
|
||
默认会自动打开浏览器。如果没有自动打开，命令会打印 URL，例如：
|
||
|
||
```text
|
||
http://localhost:5177
|
||
```
|
||
|
||
局域网或服务器部署时，把监听地址改为 `0.0.0.0`，并把审校数据目录固定到一个你会备份的位置：
|
||
|
||
```powershell
|
||
python .\server.py --host 0.0.0.0 --port 5177 --review-root .\epub_review_sessions
|
||
```
|
||
|
||
当前版本没有登录鉴权，不要直接暴露到公网。需要远程使用时，优先放在可信局域网、VPN、反向代理鉴权或 SSH 隧道后面。
|
||
|
||
## 浏览器上传 EPUB
|
||
|
||
- 启动时不带 EPUB 路径，会进入开始页。
|
||
- 点击“选择 EPUB 文件”，上传中日双语 EPUB 后会自动创建审校会话。
|
||
- 开始页会列出已有会话，换电脑或重启服务后可以继续打开之前的审校记录。
|
||
- 上传的 EPUB、解包副本、反馈与导出文件都会保存在 `--review-root` 指定目录下。
|
||
|
||
## 能做什么
|
||
|
||
- 阅读模式下按章节连续阅读日文原文与中文译文，不需要逐句点击。
|
||
- 左侧目录和检索默认隐藏，通过顶部“目录”“检索”两个按钮分别打开，不会把两种入口混在同一个常驻侧栏里。
|
||
- 目录优先按 EPUB 内部目录页或 nav/toc 组织章节；章节下显示内部 `part0000` 形式的 part，可展开/收起，点击 part 后只看该 part，点击章节则看整章连续正文。
|
||
- 插图页会像文字章节一样出现在目录里，点击后可在阅读模式中直接查看原 EPUB 图片。
|
||
- 在阅读模式中点击段落即可打开右侧精修与重翻面板，直接编辑中文译文、标记问题或调用 GPT 重翻；打开/关闭面板时会尽量保持原来的阅读位置。
|
||
- 精修模式保留原有逐段编辑界面，用于较细的逐段复审。
|
||
- 可在网页中配置 OpenAI 兼容的 `base_url`、`model` 与 API Key，对当前段落生成重翻候选；候选不会自动覆盖正文，需要点击“应用重翻”并保存。
|
||
- 直接编辑中文译文。
|
||
- 标记问题段落或选中文本。
|
||
- 记录问题类型、严重程度、标签、备注和可沉淀的长期规则。
|
||
- 生成反馈文件，供 Codex 后续持续优化翻译和润色质量。
|
||
- 将编辑写回 EPUB 解包内容。
|
||
- 导出一份新的“网页审校版 EPUB”。
|
||
|
||
## 重要输出
|
||
|
||
每个 EPUB 会建立独立审校 session。通过浏览器上传时，默认位于：
|
||
|
||
```text
|
||
epub_review_sessions\<timestamp>_<epub-name>_<hash>\
|
||
```
|
||
|
||
通过命令行直接指定 EPUB 时，仍沿用固定路径：
|
||
|
||
```text
|
||
epub_review_sessions\<epub-name>_<hash>\
|
||
```
|
||
|
||
关键文件：
|
||
|
||
- `feedback/translation_feedback.jsonl`：逐次保存的结构化反馈记录。
|
||
- `feedback/feedback_for_codex.md`：适合直接给 Codex 阅读的审校反馈摘要。
|
||
- `exports/*_网页审校版_*.epub`：导出的修订版 EPUB。
|
||
- `review_state/state.json`：网页编辑器当前状态。
|
||
- `extracted/`：EPUB 解包后的工作副本。
|
||
|
||
在服务器上使用时，“生成反馈”和“导出审校 EPUB”会返回浏览器可访问的下载地址，不需要登录服务器找文件。
|
||
|
||
## 使用建议
|
||
|
||
- 正式长篇 EPUB 优先使用“阅读模式”：先在左侧点章节/part 连续读，看到问题再点段落快速编辑或标记。
|
||
- 需要集中逐段复审时切到“精修模式”，左侧段落列表会跟随当前章节筛选。
|
||
- 只想记录问题时：勾选“标记为翻译问题”，写备注，保存本段。
|
||
- 想直接修正译文时：编辑中文译文后保存本段。
|
||
- 想让 Codex 学习你的偏好时：把“可沉淀为长期规则”写具体，例如“Falchion 固定译为大砍刀，不要译成偃月刀”。
|
||
- 想单段重翻时：点击段落打开右侧面板，先在“API 设置”中保存 GPT 配置，再点“重翻本段”；满意后点“应用重翻”，最后保存本段记录。
|
||
- 审校结束后点击“生成反馈”，再在聊天里告诉 Codex 读取 `feedback_for_codex.md` 和 `translation_feedback.jsonl`。
|
||
|
||
## 当前限制
|
||
|
||
- 当前解析规则针对本项目的“日文灰字 + 中文紧随其后”的双语 EPUB。
|
||
- 目录用于审校导航；插图可以阅读和跳转，但当前版本不提供图片内容编辑。
|
||
- GPT API Key 仅保存在 `--review-root` 下的本地 `gpt_config.json`，接口不会回传密钥；重翻时只能使用已保存的 Base URL 和模型，避免把密钥发往未确认端点。服务器部署时请保护好审校目录，不要把没有鉴权的服务暴露到公网。
|
||
- 浏览器内保存的是审校工作副本；要生成 EPUB 文件，需要点击“导出审校 EPUB”。
|