a4489f4945
- Introduced `compose.ocr-languages.yml` for installing additional Tesseract OCR language packs during container startup. - Updated documentation to include new OCR language extension options and usage scenarios. - Enhanced existing documentation with references to the new OCR language extension guide. - Improved test coverage for the deark converter and formats, ensuring accurate format handling and error management. - Refactored code to streamline file system operations and improve readability.
345 lines
10 KiB
Markdown
345 lines
10 KiB
Markdown
# OCR 語言擴展指南
|
||
|
||
ConvertX-CN 預設內建 7 種 OCR 語言（+ 自動多語言模式），但你可以透過多種方式擴展支援更多語言。
|
||
|
||
---
|
||
|
||
## 內建語言
|
||
|
||
以下語言已預先安裝，無需額外配置：
|
||
|
||
| 語言 | Tesseract 代碼 | UI 格式代碼 |
|
||
| -------- | -------------- | ----------- |
|
||
| 英文 | `eng` | `pdf-en` |
|
||
| 繁體中文 | `chi_tra` | `pdf-zh-TW` |
|
||
| 簡體中文 | `chi_sim` | `pdf-zh` |
|
||
| 日文 | `jpn` | `pdf-ja` |
|
||
| 韓文 | `kor` | `pdf-ko` |
|
||
| 德文 | `deu` | `pdf-de` |
|
||
| 法文 | `fra` | `pdf-fr` |
|
||
|
||
另外還有 `pdf-ocr` 自動多語言模式，會同時使用所有已安裝的語言包。
|
||
|
||
---
|
||
|
||
## 擴展方法比較
|
||
|
||
| 方法 | 優點 | 缺點 | 適用場景 |
|
||
| --------------------------- | ---------------------- | ------------------ | -------------- |
|
||
| **方法一：compose.yaml** | 簡單、無需建立額外檔案 | 每次啟動需重新安裝 | 測試、臨時使用 |
|
||
| **方法二：掛載語言包** | 離線可用、啟動快 | 需手動下載檔案 | 離線環境 |
|
||
| **方法三：自訂 Dockerfile** | 一次安裝、啟動最快 | 需要建立自訂 image | 生產環境 |
|
||
|
||
---
|
||
|
||
## 方法一：透過 compose.yaml 安裝
|
||
|
||
### 完整範例
|
||
|
||
```yaml
|
||
# compose.yaml
|
||
services:
|
||
convertx:
|
||
image: ghcr.io/cysk003/convertx-cn:latest
|
||
container_name: convertx-cn
|
||
restart: unless-stopped
|
||
|
||
# 使用自訂 entrypoint 安裝額外語言包
|
||
entrypoint: ["/bin/sh", "-c"]
|
||
command:
|
||
- |
|
||
echo "📦 正在安裝額外 OCR 語言包..."
|
||
apt-get update && apt-get install -y --no-install-recommends \
|
||
tesseract-ocr-spa \
|
||
tesseract-ocr-ita \
|
||
tesseract-ocr-por \
|
||
tesseract-ocr-rus \
|
||
&& rm -rf /var/lib/apt/lists/*
|
||
echo "✅ 語言包安裝完成"
|
||
echo "🚀 啟動 ConvertX..."
|
||
exec bun run start
|
||
|
||
ports:
|
||
- "3000:3000"
|
||
|
||
volumes:
|
||
- ./data:/app/data
|
||
|
||
environment:
|
||
- TZ=Asia/Taipei
|
||
- JWT_SECRET=請改成你自己的長隨機字串-至少32個字元
|
||
- ACCOUNT_REGISTRATION=true
|
||
- HTTP_ALLOWED=true
|
||
- ALLOW_UNAUTHENTICATED=false
|
||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||
```
|
||
|
||
### 說明
|
||
|
||
1. `entrypoint` 和 `command` 覆蓋了原本的啟動命令
|
||
2. 在啟動應用前先執行 `apt-get install` 安裝語言包
|
||
3. `exec bun run start` 確保應用正確啟動並接收信號
|
||
|
||
### 注意事項
|
||
|
||
> ⚠️ **每次容器重啟都會重新安裝語言包**，首次啟動可能需要 1-2 分鐘。
|
||
|
||
> 💡 如果需要更快的啟動速度，請使用方法二或方法三。
|
||
|
||
---
|
||
|
||
## 方法二：掛載語言包（推薦離線環境）
|
||
|
||
### 步驟 1：下載語言包
|
||
|
||
```bash
|
||
# 建立 tessdata 目錄
|
||
mkdir -p tessdata
|
||
cd tessdata
|
||
|
||
# 下載需要的語言包
|
||
# 高精度版（推薦，檔案較大）
|
||
wget https://github.com/tesseract-ocr/tessdata_best/raw/main/spa.traineddata # 西班牙文
|
||
wget https://github.com/tesseract-ocr/tessdata_best/raw/main/ita.traineddata # 義大利文
|
||
wget https://github.com/tesseract-ocr/tessdata_best/raw/main/por.traineddata # 葡萄牙文
|
||
wget https://github.com/tesseract-ocr/tessdata_best/raw/main/rus.traineddata # 俄文
|
||
|
||
# 或使用標準版（檔案較小，速度較快）
|
||
# wget https://github.com/tesseract-ocr/tessdata/raw/main/spa.traineddata
|
||
```
|
||
|
||
### 步驟 2：配置 compose.yaml
|
||
|
||
```yaml
|
||
# compose.yaml
|
||
services:
|
||
convertx:
|
||
image: ghcr.io/cysk003/convertx-cn:latest
|
||
container_name: convertx-cn
|
||
restart: unless-stopped
|
||
|
||
ports:
|
||
- "3000:3000"
|
||
|
||
volumes:
|
||
- ./data:/app/data
|
||
# 掛載語言包目錄
|
||
- ./tessdata:/usr/share/tesseract-ocr/5/tessdata:ro
|
||
|
||
environment:
|
||
- TZ=Asia/Taipei
|
||
- JWT_SECRET=請改成你自己的長隨機字串-至少32個字元
|
||
```
|
||
|
||
### 目錄結構
|
||
|
||
```
|
||
your-project/
|
||
├── compose.yaml
|
||
├── data/
|
||
└── tessdata/
|
||
├── spa.traineddata
|
||
├── ita.traineddata
|
||
├── por.traineddata
|
||
└── rus.traineddata
|
||
```
|
||
|
||
### 語言包下載來源
|
||
|
||
| 版本 | 說明 | 下載位置 |
|
||
| -------- | -------------------- | ---------------------------------------------- |
|
||
| 高精度版 | 辨識準確度最高 | https://github.com/tesseract-ocr/tessdata_best |
|
||
| 標準版 | 平衡準確度與速度 | https://github.com/tesseract-ocr/tessdata |
|
||
| 快速版 | 速度最快，準確度較低 | https://github.com/tesseract-ocr/tessdata_fast |
|
||
|
||
---
|
||
|
||
## 方法三：自訂 Dockerfile（推薦生產環境）
|
||
|
||
### 步驟 1：建立 Dockerfile
|
||
|
||
```dockerfile
|
||
# Dockerfile
|
||
FROM ghcr.io/cysk003/convertx-cn:latest
|
||
|
||
# 安裝額外 OCR 語言包
|
||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||
tesseract-ocr-spa \
|
||
tesseract-ocr-ita \
|
||
tesseract-ocr-por \
|
||
tesseract-ocr-rus \
|
||
tesseract-ocr-ara \
|
||
tesseract-ocr-hin \
|
||
tesseract-ocr-vie \
|
||
tesseract-ocr-tha \
|
||
&& rm -rf /var/lib/apt/lists/*
|
||
|
||
# 可選：驗證安裝
|
||
RUN tesseract --list-langs
|
||
```
|
||
|
||
### 步驟 2：配置 compose.yaml
|
||
|
||
```yaml
|
||
# compose.yaml
|
||
services:
|
||
convertx:
|
||
build:
|
||
context: .
|
||
dockerfile: Dockerfile
|
||
container_name: convertx-cn
|
||
restart: unless-stopped
|
||
|
||
ports:
|
||
- "3000:3000"
|
||
|
||
volumes:
|
||
- ./data:/app/data
|
||
|
||
environment:
|
||
- TZ=Asia/Taipei
|
||
- JWT_SECRET=請改成你自己的長隨機字串-至少32個字元
|
||
```
|
||
|
||
### 步驟 3：建置並啟動
|
||
|
||
```bash
|
||
# 建置自訂 image
|
||
docker compose build
|
||
|
||
# 啟動
|
||
docker compose up -d
|
||
```
|
||
|
||
### 目錄結構
|
||
|
||
```
|
||
your-project/
|
||
├── compose.yaml
|
||
├── Dockerfile
|
||
└── data/
|
||
```
|
||
|
||
---
|
||
|
||
## 可用語言包完整列表
|
||
|
||
### 常用語言
|
||
|
||
| Tesseract 包名 | 語言代碼 | 語言 | 檔案大小（約） |
|
||
| ------------------- | -------- | -------- | -------------- |
|
||
| `tesseract-ocr-spa` | es | 西班牙文 | 5 MB |
|
||
| `tesseract-ocr-ita` | it | 義大利文 | 4 MB |
|
||
| `tesseract-ocr-por` | pt | 葡萄牙文 | 4 MB |
|
||
| `tesseract-ocr-rus` | ru | 俄文 | 6 MB |
|
||
| `tesseract-ocr-ara` | ar | 阿拉伯文 | 3 MB |
|
||
| `tesseract-ocr-hin` | hi | 印地文 | 7 MB |
|
||
| `tesseract-ocr-vie` | vi | 越南文 | 2 MB |
|
||
| `tesseract-ocr-tha` | th | 泰文 | 5 MB |
|
||
|
||
### 歐洲語言
|
||
|
||
| Tesseract 包名 | 語言代碼 | 語言 |
|
||
| ------------------- | -------- | ------------ |
|
||
| `tesseract-ocr-swe` | sv | 瑞典文 |
|
||
| `tesseract-ocr-dan` | da | 丹麥文 |
|
||
| `tesseract-ocr-nor` | no | 挪威文 |
|
||
| `tesseract-ocr-fin` | fi | 芬蘭文 |
|
||
| `tesseract-ocr-pol` | pl | 波蘭文 |
|
||
| `tesseract-ocr-ces` | cs | 捷克文 |
|
||
| `tesseract-ocr-hun` | hu | 匈牙利文 |
|
||
| `tesseract-ocr-nld` | nl | 荷蘭文 |
|
||
| `tesseract-ocr-ell` | el | 希臘文 |
|
||
| `tesseract-ocr-ukr` | uk | 烏克蘭文 |
|
||
| `tesseract-ocr-ron` | ro | 羅馬尼亞文 |
|
||
| `tesseract-ocr-bul` | bg | 保加利亞文 |
|
||
| `tesseract-ocr-hrv` | hr | 克羅地亞文 |
|
||
| `tesseract-ocr-slk` | sk | 斯洛伐克文 |
|
||
| `tesseract-ocr-slv` | sl | 斯洛維尼亞文 |
|
||
|
||
### 中東語言
|
||
|
||
| Tesseract 包名 | 語言代碼 | 語言 |
|
||
| ------------------- | -------- | -------- |
|
||
| `tesseract-ocr-heb` | he | 希伯來文 |
|
||
| `tesseract-ocr-tur` | tr | 土耳其文 |
|
||
| `tesseract-ocr-fas` | fa | 波斯文 |
|
||
|
||
### 亞洲語言
|
||
|
||
| Tesseract 包名 | 語言代碼 | 語言 |
|
||
| ------------------- | -------- | ------------ |
|
||
| `tesseract-ocr-ben` | bn | 孟加拉文 |
|
||
| `tesseract-ocr-tam` | ta | 泰米爾文 |
|
||
| `tesseract-ocr-tel` | te | 泰盧固文 |
|
||
| `tesseract-ocr-kan` | kn | 卡納達文 |
|
||
| `tesseract-ocr-mal` | ml | 馬拉雅拉姆文 |
|
||
| `tesseract-ocr-mar` | mr | 馬拉地文 |
|
||
| `tesseract-ocr-guj` | gu | 古吉拉特文 |
|
||
| `tesseract-ocr-pan` | pa | 旁遮普文 |
|
||
| `tesseract-ocr-mya` | my | 緬甸文 |
|
||
| `tesseract-ocr-khm` | km | 高棉文 |
|
||
| `tesseract-ocr-lao` | lo | 寮文 |
|
||
| `tesseract-ocr-ind` | id | 印尼文 |
|
||
| `tesseract-ocr-msa` | ms | 馬來文 |
|
||
|
||
> 💡 **查詢所有可用語言包**：在容器內執行 `apt-cache search tesseract-ocr-`
|
||
|
||
---
|
||
|
||
## 驗證語言包安裝
|
||
|
||
### 方法 1：在容器內檢查
|
||
|
||
```bash
|
||
# 進入容器
|
||
docker exec -it convertx-cn /bin/bash
|
||
|
||
# 列出已安裝的語言
|
||
tesseract --list-langs
|
||
```
|
||
|
||
### 方法 2：透過日誌確認
|
||
|
||
啟動容器後查看日誌：
|
||
|
||
```bash
|
||
docker compose logs -f convertx
|
||
```
|
||
|
||
如果使用方法一（compose.yaml 安裝），會看到類似以下輸出：
|
||
|
||
```
|
||
📦 正在安裝額外 OCR 語言包...
|
||
✅ 語言包安裝完成
|
||
🚀 啟動 ConvertX...
|
||
```
|
||
|
||
---
|
||
|
||
## 常見問題
|
||
|
||
### Q: 為什麼 UI 上看不到新增的語言選項？
|
||
|
||
**A:** OCRmyPDF 的 UI 格式是在程式碼中固定的（8 種選項），新增語言包只會影響 `pdf-ocr` 自動模式的辨識能力。如果你使用 `pdf-ocr` 模式，系統會自動使用所有已安裝的語言包。
|
||
|
||
### Q: 自動模式會變慢嗎？
|
||
|
||
**A:** 安裝更多語言包後，`pdf-ocr` 自動模式可能會稍微變慢，因為 Tesseract 需要嘗試更多語言。如果你知道文件語言，選擇特定語言格式會更快。
|
||
|
||
### Q: 如何在 UI 上顯示新的語言選項？
|
||
|
||
**A:** 需要修改 `src/converters/ocrmypdf.ts` 中的 `SUPPORTED_LANGUAGES` 陣列，並重新建置應用。這超出了簡單配置的範圍。
|
||
|
||
### Q: 語言包太大，如何減少下載量？
|
||
|
||
**A:** 使用 `tessdata_fast` 版本而非 `tessdata_best`，或只安裝實際需要的語言。
|
||
|
||
---
|
||
|
||
## 相關文件
|
||
|
||
- [OCR 功能說明](../功能說明/OCR.md)
|
||
- [Docker Compose 說明](說明文件.md)
|
||
- [compose.ocr-languages.yml](compose.ocr-languages.yml)
|
||
- [環境變數設定](../配置設定/環境變數.md)
|