# book_translator

**Repository Path**: Hilbert777/book_translator

## Basic Information

- **Project Name**: book_translator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图书自动翻译工具

本工具用于把图书或课件类文件自动翻译为中文，并输出为 `md`、`txt` 或 `pdf`。

当前版本默认提供**本地 Web 界面**：用户启动脚本后，浏览器会自动打开，在网页中完成文件选择、上传、参数配置、任务启动、日志查看和结果下载。

---

## 快速开始

### 最推荐的用法

1. 把要翻译的文件放进 [books_in](./books_in) 文件夹。
2. 双击运行 [run_translator.bat](./run_translator.bat)。
3. 浏览器会自动打开本地网页。
4. 在网页中：
   - 选择一个或多个已有文件，或直接拖拽上传一个或多个文件
   - 选择在线/离线翻译
   - 选择清洗模式
   - 选择输出格式
   - 点击“开始翻译”
5. 等待任务完成后，直接在网页中下载结果。

### 如果你什么都不想选

如果你不手动指定文件，工具会默认优先处理 `books_in` 中**最近放入或最近修改**的那个文件。

---

## Web 界面支持什么

当前 Web 界面支持：

- 浏览 `books_in` 中已有文件
- 点选上传文件
- 直接拖拽上传文件
- 多文件入队
- 启动翻译任务
- 查看实时日志
- 下载最终结果
- 下载原始 Markdown
- 下载提取文本
- 下载翻译缓存
- 查看最近任务
- 查看最近结果
- 删除任务记录
- 重新入队旧任务
- 清空历史任务

### 任务持久化

最近任务和最近结果会持久保存到本地：

- 历史文件：[jobs_history.json](./jobs_history.json)

这意味着：

- 关闭脚本后再次启动，历史任务仍然存在
- 之前成功完成的任务仍然可以从网页中继续下载结果
- 批量入队的任务也会按顺序继续显示在历史中

---

## 启动方式

### Web 版

- [run_translator.bat](./run_translator.bat)

作用：

- 启动本地 Web 服务
- 自动打开浏览器
- 默认使用图形化网页操作

### CLI 版

- [run_cli.bat](./run_cli.bat)

作用：

- 保留命令行交互模式
- 适合习惯命令行或调试时使用

---

## 支持的输入格式

工具目前支持以下输入格式：

- `pdf`
- `txt`
- `md`
- `docx`
- `doc`
- `pptx`
- `ppt`

### 各格式说明

#### `pdf`

- 优先使用 `pdftotext` 提取文本
- 如果系统里没有 `pdftotext`，会自动退回到 Python 的 `pypdf`

#### `txt` / `md`

- 直接读取文本内容

#### `docx`

- 使用 `python-docx` 提取正文和表格文本

#### `pptx`

- 使用 `python-pptx` 提取幻灯片中的文本

#### `doc` / `ppt`

- 会尝试通过本机已安装的 Microsoft Office 自动提取文本
- 如果机器上没有可用的 Word / PowerPoint，这两类文件会提取失败

---

## 支持的输出格式

工具目前支持以下输出格式：

- `md`
- `txt`
- `pdf`

### 输出逻辑

工具内部始终先生成：

1. 提取文本
2. 原始 Markdown
3. 清洗后的 Markdown

在此基础上再按用户选择导出最终格式。

### 各格式说明

#### `md`

- 推荐格式
- 结构最完整
- 最适合后续人工润色

#### `txt`

- 从清洗后的 Markdown 再导出纯文本
- 适合快速阅读或复制

#### `pdf`

- 从清洗后的 Markdown 导出 PDF
- 依赖：
  - `pandoc`
  - 本机 PDF 引擎，如 `xelatex`、`pdflatex` 或 `wkhtmltopdf`

如果本机缺少这些组件，PDF 导出会失败，但 Markdown 结果仍会保留。

---

## 翻译模式

### 在线翻译

特点：

- 效果通常更好
- 更适合普通文本和技术书初稿
- 运行前请准备好网络环境
- 脚本会自动安装所需在线翻译库

### 离线翻译

特点：

- 首次运行会自动安装离线翻译库和英译中语言包
- 首次安装通常仍需要联网
- 语言包装好后，后续翻译可离线进行
- 更适合对隐私或网络稳定性有要求的场景

---

## 清洗模式

### `basic`

适合：

- 普通文本
- 结构不复杂的文档
- 对后处理要求不高的场景

主要做：

- 页码/页眉噪声清理
- 基础段落归并
- 常见格式统一
- 公式块保护

### `academic`

推荐用于：

- 教材
- 学术书
- 技术文档
- 章节结构明显的 PDF

在 `basic` 的基础上额外增强：

- 章节标题识别
- 目录样式规整
- 短行合并
- 更强的公式/符号块保护
- 更适合教材类内容的段落重组

---

## 目录结构

项目主要目录如下：

- [books_in](./books_in)
  放原始输入文件
- [extracted_text](./extracted_text)
  放提取出的纯文本
- [raw_md](./raw_md)
  放原始翻译稿
- [translated_md](./translated_md)
  放清洗后的 Markdown 及最终导出结果
- [cache](./cache)
  放翻译缓存

主要程序文件：

- [book_translator.py](./book_translator.py)
  翻译主程序
- [web_app.py](./web_app.py)
  本地 Web 界面
- [run_translator.bat](./run_translator.bat)
  Web 启动脚本
- [run_cli.bat](./run_cli.bat)
  CLI 启动脚本

---

## 结果文件说明

一次任务完成后，通常会生成这些文件：

- `extracted_text/<文件名>.txt`
- `raw_md/<文件名> 中文译文_原始.md`
- `translated_md/<文件名> 中文译文.md`
- 如果选择了其他输出格式，还会有：
  - `translated_md/<文件名> 中文译文.txt`
  - `translated_md/<文件名> 中文译文.pdf`

---

## 备用命令行用法

如果你仍然想直接使用命令行，可以运行：

```powershell
python book_translator.py
python book_translator.py --mode online
python book_translator.py --mode offline
python book_translator.py --pdf your_book.pdf
python book_translator.py --cleanup-mode academic
python book_translator.py --output-format txt
python book_translator.py --output-format pdf
```

说明：

- 如果不写 `--pdf`，脚本会自动优先处理 `books_in` 中最新的文件
- `--pdf` 这里的参数名保留了历史兼容性，实际可用于指定任意受支持文件名

---

## 注意事项

- 如果 PDF 本身是扫描件、OCR 很差，翻译质量会明显下降
- 数学公式、页眉页脚、复杂排版仍然可能影响个别段落效果
- 自动清洗会明显改善输出质量，但它不是人工精修
- 对于 `doc` 和 `ppt`，如果本机没有可用的 Office，提取会失败
- 对于 `pdf` 输出，如果缺少 `pandoc` 或 PDF 引擎，导出会失败

---

## 常见问题

### 1. 双击后浏览器没有打开

- 先看命令行窗口是否报错
- 手动访问：

```text
http://127.0.0.1:8765
```

### 2. PDF 导出失败

大概率是缺少：

- `pandoc`
- `xelatex` / `pdflatex` / `wkhtmltopdf`

这时建议先输出 `md`，确认翻译结果正常后再处理 PDF 导出环境。

### 3. 拖拽上传没有反应

- 确认浏览器页面已完全打开
- 尝试先用“点选上传”验证接口是否正常
- 确认拖入的是受支持的文件类型

### 4. 历史任务不见了

- 检查 [jobs_history.json](./jobs_history.json) 是否仍在
- 如果该文件被手动删除，历史任务会被清空

---

## 当前最适合的使用场景

这套工具目前最适合：

- 教材翻译初稿
- 技术书和课件整理
- 教师/学生在本地批量处理文件
- 希望“尽量少折腾环境、直接在网页里操作”的普通用户

如果后续还要继续扩展，最值得增加的方向是：

- 历史任务管理（删除/清空/重跑）
- 多文件队列
- 术语配置文件
- 更完整的 GUI 包装