feat(i18n): add multilingual support with translations for English, Japanese, and Simplified Chinese

- Create README.md for internationalization (i18n) documentation - Add English translation for main README and quick start guide - Add Japanese translation for main README - Add Simplified Chinese translation for main README - Introduce sample Docker Compose configurations for various deployment scenarios - Implement CI/CD documentation for testing and deployment workflows - Establish end-to-end testing guidelines and strategies - Create test strategy documentation outlining unit, integration, and E2E tests
2026-01-23 14:32:27 +08:00 · 2026-01-23 14:32:27 +08:00 · da856d89ff
commit da856d89ff
parent b3b382d1e0
42 changed files with 4901 additions and 263 deletions
--- a/docs/features/converters.md
+++ b/docs/features/converters.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)
--- a/docs/features/i18n.md
+++ b/docs/features/i18n.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": "開始轉換",
+  ...
+}
+```
+
+---
+
+## 相關文件
+
+- [貢獻指南](../development/contribution.md)
+- [專案結構](../development/project-structure.md)
--- a/docs/features/ocr.md
+++ b/docs/features/ocr.md
@ -0,0 +1,117 @@
+# OCR 功能
+
+ConvertX-CN 內建 Tesseract OCR，可將圖片中的文字轉換為可編輯文字。
+
+---
+
+## 內建語言
+
+ConvertX-CN 完整版內建以下 OCR 語言：
+
+| 語言     | 代碼      |
+| -------- | --------- |
+| 繁體中文 | `chi_tra` |
+| 簡體中文 | `chi_sim` |
+| 英文     | `eng`     |
+| 日文     | `jpn`     |
+| 韓文     | `kor`     |
+| 德文     | `deu`     |
+| 法文     | `fra`     |
+
+---
+
+## 使用方式
+
+### 圖片 → 文字
+
+1. 上傳圖片（PNG, JPG, TIFF 等）
+2. 選擇目標格式 `txt` 或 `pdf`（可搜尋）
+3. 進行轉換
+
+### PDF → 可搜尋 PDF
+
+1. 上傳掃描版 PDF
+2. 選擇 OCR 處理
+3. 獲得可搜尋的 PDF
+
+---
+
+## 支援的輸入格式
+
+- **點陣圖**：PNG, JPG, JPEG, TIFF, BMP, GIF
+- **文件**：PDF（掃描版）
+- **其他**：WebP, PNM, PBM
+
+---
+
+## 輸出格式
+
+| 格式 | 說明            |
+| ---- | --------------- |
+| TXT  | 純文字          |
+| PDF  | 可搜尋 PDF      |
+| HOCR | HTML + 座標資訊 |
+
+---
+
+## 最佳實踐
+
+### 提高辨識準確度
+
+1. **解析度**：至少 300 DPI
+2. **對比度**：文字與背景對比清晰
+3. **傾斜校正**：確保文字水平
+4. **雜訊去除**：去除背景雜訊
+
+### 處理多語言文件
+
+Tesseract 可同時辨識多種語言，但準確度可能下降。
+
+建議：
+
+- 單一語言文件使用單一語言包
+- 中英混合使用 `chi_tra+eng`
+
+---
+
+## 新增語言
+
+### 方法一：自訂 Dockerfile
+
+```dockerfile
+# 在 Dockerfile.full 中取消註解
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  tesseract-ocr-spa \  # 西班牙文
+  tesseract-ocr-ita \  # 義大利文
+  && rm -rf /var/lib/apt/lists/*
+```
+
+### 方法二：掛載語言包
+
+```yaml
+volumes:
+  - ./tessdata:/usr/share/tesseract-ocr/5/tessdata
+```
+
+下載語言包：https://github.com/tesseract-ocr/tessdata_best
+
+---
+
+## 可選語言包
+
+| 區域   | 語言                           |
+| ------ | ------------------------------ |
+| 西歐   | 西班牙文、義大利文、葡萄牙文   |
+| 北歐   | 瑞典文、丹麥文、挪威文、芬蘭文 |
+| 東歐   | 俄文、波蘭文、捷克文、匈牙利文 |
+| 中東   | 阿拉伯文、希伯來文、土耳其文   |
+| 南亞   | 印地文、孟加拉文、泰米爾文     |
+| 東南亞 | 泰文、越南文、印尼文           |
+
+---
+
+## 相關文件
+
+- [支援的轉換器](converters.md)
+- [翻譯功能](translation.md)
+- [Docker 部署](../deployment/docker.md)
--- a/docs/features/translation.md
+++ b/docs/features/translation.md
@ -0,0 +1,118 @@
+# 翻譯功能
+
+ConvertX-CN 內建 PDFMathTranslate 引擎，可翻譯 PDF 同時保留數學公式與排版。
+
+---
+
+## 功能特色
+
+- 📊 **保留數學公式**：LaTeX 公式完整保留
+- 📈 **保留圖表**：圖片、表格位置不變
+- 📑 **保留目錄**：連結與結構完整
+- 🌐 **多語言支援**：15+ 種目標語言
+
+---
+
+## 支援的目標語言
+
+| 格式代碼    | 目標語言 |
+| ----------- | -------- |
+| `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`    | 泰文     |
+
+---
+
+## 使用方式
+
+1. 上傳 PDF 檔案
+2. 在目標格式選擇 `pdf-zh-TW`（或其他語言）
+3. 點擊轉換
+4. 下載翻譯後的 PDF
+
+---
+
+## 輸出格式
+
+所有輸出一律打包為 `.tar` 檔案，包含：
+
+```
+output.tar
+├── original.pdf      # 原始 PDF
+└── translated-*.pdf  # 翻譯後的 PDF
+```
+
+---
+
+## 環境變數設定
+
+### PDFMATHTRANSLATE_SERVICE
+
+選擇翻譯服務提供商。
+
+| 值       | 說明                |
+| -------- | ------------------- |
+| `google` | Google 翻譯（預設） |
+| `deepl`  | DeepL 翻譯          |
+| `openai` | OpenAI API          |
+| `azure`  | Azure Translator    |
+
+```yaml
+environment:
+  - PDFMATHTRANSLATE_SERVICE=google
+```
+
+### 使用付費服務
+
+如需使用 DeepL 或 OpenAI 等付費服務，需設定 API Key：
+
+```yaml
+environment:
+  - PDFMATHTRANSLATE_SERVICE=openai
+  - OPENAI_API_KEY=sk-xxxxx
+```
+
+---
+
+## 適用場景
+
+### ✅ 適合
+
+- 學術論文翻譯
+- 數學/物理教科書
+- 技術文件翻譯
+- AI/ML 論文
+
+### ⚠️ 限制
+
+- 掃描版 PDF（需先 OCR）
+- 複雜排版的雜誌
+- 手寫文件
+
+---
+
+## 注意事項
+
+1. **模型已預載**：所需模型已在 Docker build 階段下載
+2. **不會隱式下載**：Runtime 不會下載額外模型
+3. **預設免費服務**：使用 Google 翻譯（免費）
+
+---
+
+## 相關文件
+
+- [支援的轉換器](converters.md)
+- [OCR 功能](ocr.md)
+- [環境變數設定](../configuration/environment-variables.md)