feat: 新增 OCRmyPDF 轉換引擎 (v0.1.14)

## 新功能 - OCRmyPDF 轉換引擎：將掃描版 PDF 轉換為可搜尋 PDF - 支援 7 種語言：en, zh-TW, zh, ja, ko, de, fr - 與 PDFMathTranslate 風格一致的 UI 格式 (pdf-<lang>) - 自動偵測頁面方向並旋轉 - 自動校正傾斜 - 跳過已有文字層的頁面 - 詳細的 5 階段處理進度輸出 ## 建置 - Dockerfile：安裝 ocrmypdf 與 Tesseract OCR 語言包 ## 文件 - 更新 OCR 功能文件 - 文件目錄結構改為中文名稱 ## 測試 - 修復 BabelDOC 和 PDFMathTranslate 測試的 OCR mock - 所有 345 個測試通過
2026-01-23 16:28:33 +08:00 · 2026-01-23 16:28:33 +08:00 · a06df23b1d
commit a06df23b1d
parent f24eec070c
53 changed files with 1427 additions and 675 deletions
--- a/docs/功能說明/OCR.md
+++ b/docs/功能說明/OCR.md
@ -0,0 +1,152 @@
+# OCR 功能
+
+ConvertX-CN 內建 Tesseract OCR 與 ocrmypdf，提供完整的 OCR 功能：
+
+- **圖片 OCR**：將圖片中的文字轉換為可編輯文字
+- **PDF OCR**：將掃描版 PDF 轉換為可搜尋 PDF（加入文字層）
+- **PDF 自動偵測**：翻譯引擎會自動偵測掃描版 PDF 並進行 OCR 處理
+
+---
+
+## 內建語言
+
+ConvertX-CN 完整版內建以下 OCR 語言：
+
+| 語言     | 代碼      |
+| -------- | --------- |
+| 繁體中文 | `chi_tra` |
+| 簡體中文 | `chi_sim` |
+| 英文     | `eng`     |
+| 日文     | `jpn`     |
+| 韓文     | `kor`     |
+| 德文     | `deu`     |
+| 法文     | `fra`     |
+
+---
+
+## 使用方式
+
+### PDF → 可搜尋 PDF（OCR）
+
+將掃描版 PDF 轉換為可搜尋 PDF：
+
+1. 上傳 PDF 檔案
+2. 選擇 Converter: `OCRmyPDF`
+3. 選擇目標語言：
+   | 格式 | 說明 |
+   | ---- | ---- |
+   | `pdf-en` | English |
+   | `pdf-zh-TW` | 繁體中文 |
+   | `pdf-zh` | 簡體中文 |
+   | `pdf-ja` | 日本語 |
+   | `pdf-ko` | 한국어 |
+   | `pdf-de` | Deutsch |
+   | `pdf-fr` | Français |
+4. 進行轉換
+
+> 💡 **功能特點**：
+>
+> - 自動偵測頁面方向並旋轉
+> - 自動校正傾斜
+> - 跳過已有文字層的頁面
+> - 詳細的處理進度輸出
+
+### 圖片 → 文字
+
+1. 上傳圖片（PNG, JPG, TIFF 等）
+2. 選擇目標格式 `txt` 或 `pdf`（可搜尋）
+3. 進行轉換
+
+### 掃描版 PDF 翻譯（自動處理）
+
+當使用 PDFMathTranslate 或 BabelDOC 翻譯 PDF 時：
+
+1. 系統會**自動偵測**是否為掃描版 PDF（無文字層）
+2. 若為掃描版，系統會**自動執行 OCR** 加入文字層
+3. 翻譯引擎使用 OCR 處理後的 PDF 進行翻譯
+4. 使用者無需手動操作，全程自動完成
+
+---
+
+## 支援的輸入格式
+
+- **點陣圖**：PNG, JPG, JPEG, TIFF, BMP, GIF
+- **其他**：WebP, PNM, PBM
+
+---
+
+## 輸出格式
+
+| 格式 | 說明            |
+| ---- | --------------- |
+| TXT  | 純文字          |
+| PDF  | 可搜尋 PDF      |
+| HOCR | HTML + 座標資訊 |
+
+---
+
+## 最佳實踐
+
+### 提高辨識準確度
+
+1. **解析度**：至少 300 DPI
+2. **對比度**：文字與背景對比清晰
+3. **傾斜校正**：確保文字水平
+4. **雜訊去除**：去除背景雜訊
+
+### 處理多語言文件
+
+Tesseract 可同時辨識多種語言，但準確度可能下降。
+
+建議：
+
+- 單一語言文件使用單一語言包
+- 中英混合使用 `chi_tra+eng`
+
+---
+
+## 新增語言
+
+### 方法一：自訂 Dockerfile
+
+> 💡 在 `Dockerfile.full` 中取消註解以下內容
+
+```dockerfile
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  tesseract-ocr-spa \
+  tesseract-ocr-ita \
+  && rm -rf /var/lib/apt/lists/*
+```
+
+- `tesseract-ocr-spa` — 西班牙文
+- `tesseract-ocr-ita` — 義大利文
+
+### 方法二：掛載語言包
+
+```yaml
+volumes:
+  - ./tessdata:/usr/share/tesseract-ocr/5/tessdata
+```
+
+下載語言包：https://github.com/tesseract-ocr/tessdata_best
+
+---
+
+## 可選語言包
+
+| 區域   | 語言                           |
+| ------ | ------------------------------ |
+| 西歐   | 西班牙文、義大利文、葡萄牙文   |
+| 北歐   | 瑞典文、丹麥文、挪威文、芬蘭文 |
+| 東歐   | 俄文、波蘭文、捷克文、匈牙利文 |
+| 中東   | 阿拉伯文、希伯來文、土耳其文   |
+| 南亞   | 印地文、孟加拉文、泰米爾文     |
+| 東南亞 | 泰文、越南文、印尼文           |
+
+---
+
+## 相關文件
+
+- [支援的轉換器](轉換器.md)
+- [翻譯功能](翻譯.md)
+- [Docker 部署](../部署指南/Docker.md)
--- a/docs/功能說明/多語言.md
+++ b/docs/功能說明/多語言.md
@ -0,0 +1,132 @@
+# 多語言支援（i18n）
+
+ConvertX-CN 支援 **65 種語言**，提供完整的多語言介面體驗。
+
+---
+
+## 語言切換
+
+### 方法一：介面切換
+
+1. 點擊右上角語言圖示 🌐
+2. 從下拉選單選擇語言
+3. 頁面自動更新
+
+語言偏好會儲存在 Cookie 中。
+
+### 方法二：URL 參數
+
+```
+http://localhost:3000/?lang=ja
+```
+
+### 方法三：瀏覽器設定
+
+系統會自動偵測瀏覽器的語言設定。
+
+---
+
+## 語言優先順序
+
+1. Cookie 中儲存的語言偏好
+2. URL 參數 `?lang=xx`
+3. 瀏覽器 `Accept-Language` header
+4. 預設語言（繁體中文）
+
+---
+
+## 支援語言列表
+
+### 東亞語言（5 種）
+
+| 代碼    | 語言     | 原生名稱 |
+| ------- | -------- | -------- |
+| `zh-TW` | 繁體中文 | 繁體中文 |
+| `zh-CN` | 簡體中文 | 简体中文 |
+| `en`    | 英文     | English  |
+| `ja`    | 日文     | 日本語   |
+| `ko`    | 韓文     | 한국어   |
+
+### 西歐語言（10 種）
+
+| 代碼 | 語言       | 原生名稱   |
+| ---- | ---------- | ---------- |
+| `de` | 德文       | Deutsch    |
+| `fr` | 法文       | Français   |
+| `es` | 西班牙文   | Español    |
+| `it` | 義大利文   | Italiano   |
+| `pt` | 葡萄牙文   | Português  |
+| `nl` | 荷蘭文     | Nederlands |
+| `ca` | 加泰隆尼亞 | Català     |
+| `eu` | 巴斯克文   | Euskara    |
+| `gl` | 加利西亞文 | Galego     |
+| `mt` | 馬爾他文   | Malti      |
+
+### 北歐語言（5 種）
+
+| 代碼 | 語言   | 原生名稱 |
+| ---- | ------ | -------- |
+| `sv` | 瑞典文 | Svenska  |
+| `da` | 丹麥文 | Dansk    |
+| `fi` | 芬蘭文 | Suomi    |
+| `no` | 挪威文 | Norsk    |
+| `is` | 冰島文 | Íslenska |
+
+### 東歐語言（12 種）
+
+| 代碼 | 語言         | 原生名稱    |
+| ---- | ------------ | ----------- |
+| `ru` | 俄文         | Русский     |
+| `pl` | 波蘭文       | Polski      |
+| `uk` | 烏克蘭文     | Українська  |
+| `cs` | 捷克文       | Čeština     |
+| `hu` | 匈牙利文     | Magyar      |
+| `ro` | 羅馬尼亞文   | Română      |
+| `bg` | 保加利亞文   | Български   |
+| `hr` | 克羅埃西亞文 | Hrvatski    |
+| `sk` | 斯洛伐克文   | Slovenčina  |
+| `sl` | 斯洛維尼亞文 | Slovenščina |
+| `sr` | 塞爾維亞文   | Српски      |
+| `mk` | 馬其頓文     | Македонски  |
+
+### 其他語言
+
+詳見完整語言列表（共 65 種），包含：
+
+- 中東語言（阿拉伯文、希伯來文、波斯文、土耳其文）
+- 南亞語言（印地文、孟加拉文、泰米爾文等）
+- 東南亞語言（泰文、越南文、印尼文等）
+- 非洲語言（斯瓦希里文、祖魯文等）
+
+---
+
+## 貢獻翻譯
+
+歡迎協助改進翻譯！
+
+### 步驟
+
+1. 複製 `src/locales/en.json`
+2. 重命名為 `xx.json`（語言代碼）
+3. 翻譯所有文字
+4. 在 `src/i18n/index.ts` 中註冊
+5. 提交 Pull Request
+
+### 翻譯檔案格式
+
+```json
+{
+  "title": "ConvertX-CN",
+  "description": "檔案轉換服務",
+  "upload": "上傳檔案",
+  "convert": "開始轉換",
+  ...
+}
+```
+
+---
+
+## 相關文件
+
+- [貢獻指南](../開發指南/貢獻指南.md)
+- [專案結構](../開發指南/專案結構.md)
--- a/docs/功能說明/翻譯.md
+++ b/docs/功能說明/翻譯.md
@ -0,0 +1,187 @@
+# 翻譯功能
+
+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>` 格式
+
+---
+
+## 輸出格式
+
+所有輸出一律打包為 `.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)
--- a/docs/功能說明/轉換器.md
+++ b/docs/功能說明/轉換器.md
@ -0,0 +1,223 @@
+# 支援的轉換器
+
+ConvertX-CN 完整版已內建 20+ 種轉換器，支援 1000+ 種格式。
+
+---
+
+## 轉換器總覽
+
+| 轉換器           | 用途         | 輸入格式 | 輸出格式 |
+| ---------------- | ------------ | -------- | -------- |
+| FFmpeg           | 影音         | ~472     | ~199     |
+| ImageMagick      | 圖片         | 245      | 183      |
+| GraphicsMagick   | 圖片         | 167      | 130      |
+| Vips             | 高效圖片處理 | 45       | 23       |
+| LibreOffice      | 文件         | 41       | 22       |
+| Pandoc           | 文件         | 43       | 65       |
+| Calibre          | 電子書       | 26       | 19       |
+| Inkscape         | 向量圖形     | 7        | 17       |
+| libjxl           | JPEG XL      | 11       | 11       |
+| libheif          | HEIF         | 2        | 4        |
+| Assimp           | 3D 模型      | 77       | 23       |
+| Potrace          | 點陣轉向量   | 4        | 11       |
+| VTracer          | 點陣轉向量   | 8        | 1        |
+| resvg            | SVG          | 1        | 1        |
+| XeLaTeX          | LaTeX        | 1        | 1        |
+| dvisvgm          | 向量圖形     | 4        | 2        |
+| Dasel            | 資料檔案     | 5        | 4        |
+| msgconvert       | Outlook      | 1        | 1        |
+| VCF to CSV       | 聯絡人       | 1        | 1        |
+| Markitdown       | 文件         | 6        | 1        |
+| MinerU           | PDF → MD     | 1        | 2        |
+| PDFMathTranslate | PDF 翻譯     | 1        | 15+      |
+
+---
+
+## 影音轉換
+
+### FFmpeg
+
+最強大的影音轉換工具，支援幾乎所有影音格式。
+
+**常見輸入格式：**
+
+- 影片：MP4, MKV, AVI, MOV, WebM, FLV, WMV...
+- 音訊：MP3, WAV, FLAC, AAC, OGG, M4A...
+
+**常見輸出格式：**
+
+- 影片：MP4, WebM, MKV, GIF...
+- 音訊：MP3, WAV, FLAC, AAC...
+
+**硬體加速：**
+
+```yaml
+environment:
+  - FFMPEG_ARGS=-hwaccel cuda
+  - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc
+```
+
+---
+
+## 圖片處理
+
+### ImageMagick
+
+通用圖片處理工具，支援 200+ 種格式。
+
+**支援格式：**
+
+- 點陣圖：PNG, JPG, GIF, BMP, TIFF, WebP...
+- RAW：CR2, NEF, ARW, DNG...
+- 其他：PSD, PDF, EPS...
+
+### Vips
+
+高效能圖片處理，適合大型圖片。
+
+**優勢：**
+
+- 記憶體使用效率高
+- 處理速度快
+- 適合批次處理
+
+### 向量圖形
+
+| 工具     | 用途           |
+| -------- | -------------- |
+| Inkscape | SVG 編輯與轉換 |
+| Potrace  | 點陣圖轉向量   |
+| VTracer  | 照片轉向量     |
+| resvg    | SVG 渲染       |
+
+---
+
+## 文件轉換
+
+### LibreOffice
+
+辦公文件轉換引擎。
+
+**輸入格式：**
+
+- Microsoft Office：DOC, DOCX, XLS, XLSX, PPT, PPTX
+- OpenDocument：ODT, ODS, ODP
+- 其他：RTF, TXT, CSV
+
+**輸出格式：**
+
+- PDF, DOCX, ODT, TXT, HTML, EPUB...
+
+### Pandoc
+
+標記語言文件轉換。
+
+**輸入格式：**
+
+- Markdown, reStructuredText, Org-mode
+- HTML, LaTeX, EPUB
+- Word, ODT
+
+**輸出格式：**
+
+- PDF, DOCX, HTML, LaTeX
+- EPUB, Markdown, 純文字
+
+### Calibre
+
+電子書轉換專家。
+
+**輸入格式：**
+
+- EPUB, MOBI, AZW, AZW3
+- PDF, HTML, TXT
+- CBZ, CBR（漫畫）
+
+**輸出格式：**
+
+- EPUB, MOBI, AZW3
+- PDF, HTML, TXT
+
+---
+
+## 進階功能
+
+### MinerU
+
+將 PDF 轉換為結構化 Markdown。
+
+**輸出模式：**
+
+- `md-t`：表格以 Markdown 呈現
+- `md-i`：表格以圖片呈現
+
+**輸出格式：** `.tar` 封裝
+
+### PDFMathTranslate
+
+翻譯 PDF 同時保留數學公式與排版。
+
+**支援目標語言：**
+
+- 英文 (pdf-en)
+- 繁體中文 (pdf-zh-TW)
+- 簡體中文 (pdf-zh)
+- 日文 (pdf-ja)
+- 韓文 (pdf-ko)
+- 德文、法文等
+
+**特色：**
+
+- 保留數學公式
+- 保留圖表
+- 保留排版
+
+**環境變數：**
+
+```yaml
+- PDFMATHTRANSLATE_SERVICE=google # 翻譯服務
+```
+
+### OCR (Tesseract)
+
+光學字元辨識，將圖片文字轉為可編輯文字。
+
+**內建語言：**
+
+- 繁體中文、簡體中文
+- 日文、韓文
+- 英文、德文、法文
+
+---
+
+## 內建依賴
+
+ConvertX-CN 完整版已預載：
+
+| 類別         | 內建內容                                     |
+| ------------ | -------------------------------------------- |
+| **文件轉換** | LibreOffice (headless)、Pandoc               |
+| **LaTeX**    | TexLive Full                                 |
+| **OCR**      | Tesseract + 繁/簡中、日、韓、英、德語言包    |
+| **CJK 字型** | Noto CJK、Noto Emoji、微軟核心字型、標楷體   |
+| **影音轉換** | FFmpeg、ImageMagick、GraphicsMagick          |
+| **向量圖形** | Inkscape、Potrace、VTracer、resvg            |
+| **電子書**   | Calibre                                      |
+| **其他**     | Ghostscript、MuPDF、Poppler、libheif、libjxl |
+
+---
+
+## 新增轉換器
+
+如需新增轉換器支援，歡迎：
+
+1. 📝 [提交 Issue](https://github.com/pi-docket/ConvertX-CN/issues)
+2. 🔧 [發送 Pull Request](https://github.com/pi-docket/ConvertX-CN/pulls)
+
+---
+
+## 相關文件
+
+- [OCR 功能](ocr.md)
+- [翻譯功能](translation.md)
+- [Docker 部署](../deployment/docker.md)