convertor/docs/Docker組合配置/OCR語言擴展.md

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 安裝

完整範例

# 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：下載語言包

# 建立 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

# 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
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

# 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：建置並啟動

# 建置自訂 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：在容器內檢查

# 進入容器
docker exec -it convertx-cn /bin/bash

# 列出已安裝的語言
tesseract --list-langs

方法 2：透過日誌確認

啟動容器後查看日誌：

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 功能說明
• Docker Compose 說明
• compose.ocr-languages.yml
• 環境變數設定