# 翻譯功能

ConvertX-CN 內建兩個 PDF 翻譯引擎：

| 引擎                 | 命令       | 輸出格式              | 特色                 |
| -------------------- | ---------- | --------------------- | -------------------- |
| **PDFMathTranslate** | `pdf2zh`   | PDF                   | 保留數學公式與排版   |
| **BabelDOC**         | `babeldoc` | PDF / Markdown / HTML | 多格式輸出、快速翻譯 |

---

## PDFMathTranslate

適合學術論文、數學/物理教科書等需要保留公式的文件。

### 功能特色

- 📊 **保留數學公式**：LaTeX 公式完整保留
- 📈 **保留圖表**：圖片、表格位置不變
- 📑 **保留目錄**：連結與結構完整
- 🌐 **多語言支援**：15+ 種目標語言

### 使用方式

1. 上傳 PDF 檔案
2. 在目標格式選擇 `pdf-zh-TW`（或其他語言代碼）
3. 點擊轉換
4. 下載翻譯後的 PDF（.tar 檔案）

---

## BabelDOC

適合一般文件翻譯，支援多種輸出格式。

### 功能特色

- 📄 **多格式輸出**：PDF、Markdown、HTML
- ⚡ **快速翻譯**：針對一般文件優化
- 🔄 **格式轉換**：可同時翻譯並轉換格式

### 使用方式

1. 上傳 PDF 檔案
2. 在目標格式選擇：
   - `pdf-zh-TW`：翻譯後輸出 PDF
   - `md-zh-TW`：翻譯後輸出 Markdown
   - `html-zh-TW`：翻譯後輸出 HTML
3. 點擊轉換
4. 下載結果（.tar 檔案）

---

## 支援的目標語言

兩個引擎都支援以下語言：

| 格式代碼    | 目標語言 |
| ----------- | -------- |
| `pdf-en`    | 英文     |
| `pdf-zh`    | 簡體中文 |
| `pdf-zh-TW` | 繁體中文 |
| `pdf-ja`    | 日文     |
| `pdf-ko`    | 韓文     |
| `pdf-de`    | 德文     |
| `pdf-fr`    | 法文     |
| `pdf-es`    | 西班牙文 |
| `pdf-it`    | 義大利文 |
| `pdf-pt`    | 葡萄牙文 |
| `pdf-ru`    | 俄文     |
| `pdf-ar`    | 阿拉伯文 |
| `pdf-hi`    | 印地文   |
| `pdf-vi`    | 越南文   |
| `pdf-th`    | 泰文     |

> 💡 BabelDOC 額外支援 `md-<lang>` 和 `html-<lang>` 格式

### 與 OCRmyPDF 語言差異

| 功能     | 翻譯引擎     | OCRmyPDF       |
| -------- | ------------ | -------------- |
| 支援語言 | 15 種        | 8 種（可擴展） |
| 用途     | 翻譯目標語言 | OCR 文字辨識   |

翻譯引擎支援 15 種目標語言，而 OCRmyPDF 預設只內建 8 種 OCR 語言。

如需擴展 OCRmyPDF 語言支援，請參考 [OCR 功能 - 新增語言](OCR.md#新增語言)。

---

## 輸出格式

所有輸出一律打包為 `.tar` 檔案：

### PDFMathTranslate 輸出

```
output.tar
├── original.pdf      # 原始 PDF
└── translated-*.pdf  # 翻譯後的 PDF
```

### BabelDOC 輸出

```
output.tar
├── translated-*.pdf  # 翻譯後的 PDF（如果選擇 pdf-*）
├── translated-*.md   # 翻譯後的 Markdown（如果選擇 md-*）
└── translated-*.html # 翻譯後的 HTML（如果選擇 html-*）
```

---

## 環境變數設定

### 翻譯服務（PDFMathTranslate）

> 💡 `PDFMATHTRANSLATE_SERVICE` 可選值：`google`（預設）、`bing`、`deepl`、`openai`、`azure`

```yaml
environment:
  - PDFMATHTRANSLATE_SERVICE=google
```

| 服務     | 說明             | 需要 API Key |
| -------- | ---------------- | ------------ |
| `google` | Google 翻譯      | ❌ 免費      |
| `bing`   | Bing 翻譯        | ❌ 免費      |
| `deepl`  | DeepL 翻譯       | ✅           |
| `openai` | OpenAI API       | ✅           |
| `azure`  | Azure Translator | ✅           |

### 使用付費服務

如需使用付費服務，需設定對應的 API Key：

```yaml
environment:
  - PDFMATHTRANSLATE_SERVICE=openai
  - OPENAI_API_KEY=sk-xxxxx
  # 或
  - PDFMATHTRANSLATE_SERVICE=deepl
  - DEEPL_API_KEY=xxxxx
```

---

## 適用場景

### PDFMathTranslate 適合

- ✅ 學術論文翻譯
- ✅ 數學/物理教科書
- ✅ 包含 LaTeX 公式的文件
- ✅ AI/ML 論文

### BabelDOC 適合

- ✅ 一般文件翻譯
- ✅ 需要 Markdown 輸出（方便後續編輯）
- ✅ 需要 HTML 輸出（網頁展示）
- ✅ 快速翻譯大量文件

### ⚠️ 共同限制

- 掃描版 PDF（系統會自動偵測並使用 OCR 處理）
- 複雜排版的雜誌
- 手寫文件

---

## 如何選擇引擎？

| 需求               | 推薦引擎         |
| ------------------ | ---------------- |
| 有數學公式         | PDFMathTranslate |
| 需要 Markdown 輸出 | BabelDOC         |
| 需要 HTML 輸出     | BabelDOC         |
| 一般商業文件       | 兩者皆可         |
| 追求翻譯品質       | PDFMathTranslate |
| 追求翻譯速度       | BabelDOC         |

---

## 注意事項

1. **模型已預載**：所需模型已在 Docker build 階段下載
2. **不會隱式下載**：Runtime 不會下載額外模型
3. **預設免費服務**：使用 Google/Bing 翻譯（免費）
4. **離線模式**：可設定 `HF_HUB_OFFLINE=1` 確保完全離線

---

## 相關文件

- [支援的轉換器](轉換器.md)
- [OCR 功能](OCR.md)
- [環境變數設定](../配置設定/環境變數.md)