Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
- 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
This commit is contained in:
Your Name 2026-01-23 14:32:27 +08:00
parent b3b382d1e0
commit da856d89ff
42 changed files with 4901 additions and 263 deletions
Download patch file Download diff file Expand all files Collapse all files

326
README.md
View file

@ -11,93 +11,41 @@
## 為什麼選擇 ConvertX-CN？
ConvertX-CN 不只是轉檔工具，而是 **文件轉換與翻譯的一站式平台**：
- **1000+ 格式全支援**：文件、圖片、影音、電子書一次搞定
- **20+ 轉換引擎整合**：LibreOffice、FFmpeg、Pandoc 全到位
- **中文友善設計**：內建中日韓字型與 OCR，告別亂碼
- **65 種介面語言**：跨國團隊無障礙使用
- **MinerU**：強化文件解析與穩定度(測試)
- **PDFMathTranslate**：數學、工程、AI 論文公式安全翻譯與完整保留(測試)
| 特色 | 說明 |
| ----------------- | ------------------------------------ |
| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 |
| 🔧 **20+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 |
| 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 |
| 🌐 **65 種語言** | 跨國團隊無障礙使用 |
| 📊 **PDF 翻譯** | 數學公式完整保留（PDFMathTranslate） |
---
## 線上示範
## 📚 文件
想先試用再部署？歡迎使用我們的示範站：
完整文件請參閱 **[文件中心](docs/README.md)**
🔗 **https://convertx-cn.bioailab.qzz.io**
| 項目 | 內容 |
| -------- | ----------------- |
| 範例帳號 | admin@example.com |
| 範例密碼 | admin |
> ⚠️ 示範站僅供測試，請勿上傳敏感檔案。資料可能定期清除。
| 分類 | 連結 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 🚀 快速入門 | [概覽](docs/getting-started/overview.md) · [快速開始](docs/getting-started/quick-start.md) · [FAQ](docs/getting-started/faq.md) |
| 🐳 部署指南 | [Docker](docs/deployment/docker.md) · [反向代理](docs/deployment/reverse-proxy.md) |
| ⚙️ 配置設定 | [環境變數](docs/configuration/environment-variables.md) · [安全性](docs/configuration/security.md) |
| 🔌 功能說明 | [轉換器](docs/features/converters.md) · [OCR](docs/features/ocr.md) · [翻譯](docs/features/translation.md) |
| 🔗 API | [API 總覽](docs/api/overview.md) · [端點說明](docs/api/endpoints.md) |
| 👩‍💻 開發 | [專案結構](docs/development/project-structure.md) · [貢獻指南](docs/development/contribution.md) |
---
## 快速啟動（Docker Run）
## 🚀 快速開始
### 1. 建立資料夾
```bash
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
```
### 2. 啟動容器
JWT_SECRET=請改成你自己的隨機字串至少32字元
```bash
docker run -d \
--name convertx-cn \
--restart unless-stopped \
-p 3000:3000 \
-v ./data:/app/data \
-e TZ=Asia/Taipei \
-e JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1 \
convertx/convertx-cn:latest
```
### 3. 開啟瀏覽器
```bash
http://localhost:3000
```
> 首次下載約 4-6 GB，請耐心等待。
---
## Docker Compose（推薦）
### 1. 建立專案資料夾
### Linux / macOS
### Docker Compose（推薦）
```bash
# 1. 建立專案資料夾
mkdir -p ~/convertx-cn && cd ~/convertx-cn
```
### Windows PowerShell
```bash
mkdir C:\convertx-cn; cd C:\convertx-cn
```
### Windows CMD
```bash
mkdir C:\convertx-cn
cd C:\convertx-cn
```
### 2. 建立 docker-compose.yml（在專案資料夾下）
- 範例內容（請修改 JWT_SECRET=請改成你自己的隨機字串至少32字元）：
```yaml
# 2. 建立 docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
convertx:
image: convertx/convertx-cn:latest
@ -109,57 +57,60 @@ services:
- ./data:/app/data
environment:
- TZ=Asia/Taipei
- JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1
```
- JWT_SECRET=請更換為長且隨機的字串至少32字元
EOF
### 3. 啟動：
```bash
# 3. 啟動
docker compose up -d
```
更多範例 → [docs/docker-compose/](docs/docker-compose/)
開啟瀏覽器：`http://localhost:3000`
> 📖 詳細說明請參閱 [快速開始](docs/getting-started/quick-start.md)
### Docker Run
```bash
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
docker run -d \
--name convertx-cn \
--restart unless-stopped \
-p 3000:3000 \
-v ./data:/app/data \
-e TZ=Asia/Taipei \
-e JWT_SECRET=請更換為長且隨機的字串 \
convertx/convertx-cn:latest
```
---
## 重要：資料夾說明
## 🔗 線上示範
`./data` 是你**主機上的實體資料夾**，用於存放上傳檔案、轉換結果與使用者資料。
🔗 **https://convertx-cn.bioailab.qzz.io**
| 作業系統 | 建立指令 |
| ------------- | ----------------------------- |
| Linux / macOS | `mkdir -p ~/convertx-cn/data` |
| Windows (PS) | `mkdir C:\convertx-cn\data` |
| Windows (CMD) | `mkdir C:\convertx-cn\data` |
| 項目 | 內容 |
| ---- | ----------------- |
| 帳號 | admin@example.com |
| 密碼 | admin |
> 若不先建立，Docker 會建立匿名 volume，導致資料難以存取或備份。
> ⚠️ 示範站僅供測試，請勿上傳敏感檔案
---
## 必要參數
## ⚡ 常見問題速查
| 參數 | 說明 |
| ------------ | ---------------------------------- |
| `./data` | 主機資料夾，必須先建立 |
| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 |
| 問題 | 解決方法 |
| ------------------ | ---------------------------------------------- |
| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
其他環境變數 → [docs/config/environment.md](docs/config/environment.md)
更多問題 → [FAQ](docs/getting-started/faq.md)
---
## 常見問題
| 問題 | 解法 |
| -------------------- | ---------------------------------------------- |
| 登入後又被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
更多問題 → [docs/faq.md](docs/faq.md)
---
## 支援格式
## 📦 支援格式
| 轉換器 | 用途 | 格式數 |
| ---------------- | -------- | ------ |
@ -169,113 +120,19 @@ docker compose up -d
| Pandoc | 文件 | 100+ |
| Calibre | 電子書 | 40+ |
| Inkscape | 向量圖 | 20+ |
| MinerU | 文件→MD | 2 |
| PDFMathTranslate | PDF 翻譯 | 15+ |
完整列表 → [docs/converters.md](docs/converters.md)
完整列表 → [轉換器文件](docs/features/converters.md)
---
## Dark Mode
## 🖼️ 預覽
ConvertX-CN 支援亮色與暗色主題。
- 可手動切換主題（點擊導覽列的太陽/月亮圖示）
- 偏好設定自動儲存於瀏覽器
- 預設跟隨系統色彩偏好
![ConvertX-CN Preview](images/preview.png)
---
## MinerU
ConvertX 內建文件轉換引擎。
- md-t（表格以 Markdown 呈現）
- md-i（表格以圖片呈現）
輸出格式：.tar（不壓縮封裝）
---
## PDFMathTranslate 引擎
PDFMathTranslate 是一個內容轉換引擎，用於翻譯 PDF 文件同時保留數學公式與排版。
### 功能特點
- 📊 保留數學公式、圖表、目錄與註解
- 🌐 支援多種目標語言（中文、英文、日文、韓文等）
- 🤖 支援多種翻譯服務（Google、DeepL、OpenAI 等）
### 輸出格式
所有輸出一律打包為 `.tar` 檔案，包含：
- `original.pdf` — 原始 PDF 文件
- `translated-<lang>.pdf` — 翻譯後的 PDF 文件
### 可用的目標格式
```
PDFMathTranslate
├─ pdf-en （翻譯為英文）
├─ pdf-zh （翻譯為簡體中文）
├─ pdf-zh-TW （翻譯為繁體中文）
├─ pdf-ja （翻譯為日文）
├─ pdf-ko （翻譯為韓文）
├─ pdf-de （翻譯為德文）
├─ pdf-fr （翻譯為法文）
└─ ...
```
### 環境變數
| 變數 | 說明 | 預設值 |
| ------------------------------ | -------------- | ------------------------ |
| `PDFMATHTRANSLATE_SERVICE` | 翻譯服務提供商 | google |
| `PDFMATHTRANSLATE_MODELS_PATH` | 模型路徑 | /models/pdfmathtranslate |
### 注意事項
- 所需模型已在 Docker build 階段預先下載
- 不會在 runtime 隱式下載任何模型
- 使用 Google 翻譯為預設服務（免費），可透過環境變數切換
---
## 檔案傳輸機制
Contents.CN 使用統一的檔案傳輸策略：
| 檔案大小 | 傳輸方式 | 說明 |
| -------- | -------- | ------------------------ |
| ≤ 10MB | 直接傳輸 | 單一請求完成上傳/下載 |
| > 10MB | 分段傳輸 | 使用 5MB chunks 分段傳輸 |
### 多檔輸出封裝
- ✅ 唯一允許格式：`.tar`
- ❌ 禁止使用：`.tar.gz`、`.tgz`、`.zip`
### 設計原則
- 分段傳輸僅存在於傳輸層
- 轉換引擎只接收完整檔案
- 前後端使用共用傳輸模組
---
## 語言支援
支援 **65 種語言**，包含繁體中文、簡體中文、英文、日文、韓文等。
語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。
詳細說明 → [docs/i18n.md](docs/i18n.md)
---
## 版本與更新
## 🔄 更新
```bash
docker compose down
@ -283,65 +140,8 @@ docker compose pull
docker compose up -d
```
- 版本說明 → [docs/versions/](docs/versions/)
- 更新指南 → [docs/deployment/update.md](docs/deployment/update.md)
- Changelog → [CHANGELOG.md](CHANGELOG.md)
---
## API Server（選用）
如需以程式整合方式使用 ConvertX 的轉檔功能，可啟用 **API Server**。
> ⚠️ API Server 為**選用功能**，不影響現有 Web UI 的使用。若只使用網頁介面，無需任何額外設定。
### 功能特點
- 🔐 **JWT 認證** — 安全的 API 存取控制
- 🌐 **REST + GraphQL** — 雙協議支援，滿足不同整合需求
- 🔍 **智慧建議** — 轉換失敗時自動推薦替代引擎
- 🛠️ **20+ 轉換引擎** — 與 Web UI 共用完整轉換器套件
### 快速啟用
```bash
# 同時啟動 Web UI 與 API Server
docker compose --profile api up -d
```
| 服務 | 端口 | 說明 |
| ---------- | ---- | -------------- |
| Web UI | 3000 | 網頁介面 |
| API Server | 3001 | REST & GraphQL |
### API 文件
詳細的 API 規格與使用說明：
- 📘 [API Server README](api-server/README.md)
- 📗 [API 規格文件](api-server/docs/API_SPEC.md)
- 📙 [架構說明](api-server/docs/ARCHITECTURE.md)
---
## 進階文件
| 文件 | 說明 |
| -------------------------------------- | ------------------------- |
| [環境變數](docs/config/environment.md) | 所有可用參數 |
| [安全性設定](docs/config/security.md) | HTTP_ALLOWED、TRUST_PROXY |
| [反向代理](docs/deployment.md) | Nginx / Traefik / Caddy |
| [Docker 進階](docs/docker.md) | 自訂 Build |
| [FAQ](docs/faq.md) | 疑難排解 |
---
## 預覽
![ConvertX-CN Preview](images/preview.png)
---
## License
## 📄 License
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)