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
This commit is contained in:
Your Name
parent
b3b382d1e0
commit
da856d89ff
42 changed files with 4901 additions and 263 deletions
192
docs/getting-started/faq.md
Normal file
192
docs/getting-started/faq.md
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
# 常見問題 FAQ
|
||||
|
||||
---
|
||||
|
||||
## 🔐 登入與帳號
|
||||
|
||||
### Q: 如何註冊帳號？
|
||||
|
||||
首次訪問 ConvertX-CN 時：
|
||||
|
||||
1. 開啟 `http://localhost:3000`
|
||||
2. 點擊右上角 **Register**
|
||||
3. 輸入 Email 和密碼
|
||||
4. 完成！系統會自動登入
|
||||
|
||||
> ✅ **預設開放註冊**，無需設定任何環境變數
|
||||
|
||||
### Q: 可以關閉公開註冊嗎？
|
||||
|
||||
可以。如果您想限制只有現有用戶可使用：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
```
|
||||
|
||||
> ⚠️ 請確保您已經有至少一個帳號，否則將無法登入
|
||||
|
||||
### Q: 忘記密碼怎麼辦？
|
||||
|
||||
目前版本尚未提供密碼重設功能。您可以：
|
||||
|
||||
1. 刪除 `data/convertx.db`
|
||||
2. 重新啟動容器
|
||||
3. 重新註冊
|
||||
|
||||
> ⚠️ 這會刪除所有用戶資料和轉換歷史
|
||||
|
||||
### Q: 登入後又被踢回登入頁？
|
||||
|
||||
這通常是 Cookie 設定問題。請檢查：
|
||||
|
||||
1. **沒有 HTTPS 但 HTTP_ALLOWED=false**
|
||||
|
||||
```yaml
|
||||
- HTTP_ALLOWED=true # 允許 HTTP 連線
|
||||
```
|
||||
|
||||
2. **使用反向代理但沒設定 TRUST_PROXY**
|
||||
|
||||
```yaml
|
||||
- TRUST_PROXY=true # 信任反向代理
|
||||
```
|
||||
|
||||
3. **沒有設定 JWT_SECRET**
|
||||
```yaml
|
||||
- JWT_SECRET=固定的隨機字串
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker 相關
|
||||
|
||||
### Q: 為什麼 Image 這麼大（4-6 GB）？
|
||||
|
||||
ConvertX-CN 是「完整版」，內建：
|
||||
|
||||
- LibreOffice（文件轉換）
|
||||
- TexLive（LaTeX 支援）
|
||||
- FFmpeg（影音轉換）
|
||||
- Tesseract + 多語言 OCR
|
||||
- CJK 字型
|
||||
|
||||
如果您只需要基本功能，可使用原作者的輕量版：`ghcr.io/c4illin/convertx:latest`
|
||||
|
||||
### Q: Docker 啟動失敗？
|
||||
|
||||
常見原因：
|
||||
|
||||
1. **Port 被占用**：改用其他 port，如 `-p 3001:3000`
|
||||
2. **磁碟空間不足**：Image 需約 6GB
|
||||
3. **權限問題**：確保 `./data` 資料夾有寫入權限
|
||||
|
||||
```bash
|
||||
chmod -R 777 ./data
|
||||
```
|
||||
|
||||
### Q: 資料存在哪裡？
|
||||
|
||||
所有資料存放在掛載的 `/app/data` 目錄：
|
||||
|
||||
```
|
||||
./data/
|
||||
├── convertx.db # SQLite 資料庫
|
||||
├── uploads/ # 上傳的原始檔案
|
||||
└── output/ # 轉換後的檔案
|
||||
```
|
||||
|
||||
### Q: 如何備份資料？
|
||||
|
||||
直接備份 `./data` 資料夾：
|
||||
|
||||
```bash
|
||||
tar -czvf convertx-backup.tar.gz ./data
|
||||
```
|
||||
|
||||
### Q: 如何更新版本？
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌍 語言相關
|
||||
|
||||
### Q: 如何切換介面語言？
|
||||
|
||||
1. 點擊右上角語言圖示 🌐
|
||||
2. 從下拉選單選擇語言
|
||||
3. 頁面自動更新
|
||||
|
||||
語言偏好會儲存在 Cookie 中。
|
||||
|
||||
### Q: 支援哪些語言？
|
||||
|
||||
目前支援 65 種語言，包含：
|
||||
|
||||
- 繁體中文、簡體中文
|
||||
- 日文、韓文
|
||||
- 英文、德文、法文
|
||||
- 更多詳見 [多語言支援](../features/i18n.md)
|
||||
|
||||
---
|
||||
|
||||
## 📄 轉換相關
|
||||
|
||||
### Q: 支援哪些格式？
|
||||
|
||||
1000+ 種格式，詳見 [支援的轉換器](../features/converters.md)
|
||||
|
||||
### Q: 轉換失敗怎麼辦？
|
||||
|
||||
1. 檢查檔案是否損壞
|
||||
2. 檢查容器日誌：`docker logs convertx-cn`
|
||||
3. 嘗試不同的轉換引擎
|
||||
|
||||
### Q: 檔案大小有限制嗎？
|
||||
|
||||
預設無限制，但可透過反向代理設定限制：
|
||||
|
||||
```nginx
|
||||
client_max_body_size 500M;
|
||||
```
|
||||
|
||||
### Q: 轉換很慢怎麼辦？
|
||||
|
||||
1. 增加容器記憶體限制
|
||||
2. 考慮使用硬體加速（GPU）
|
||||
3. 限制同時轉換數量：
|
||||
```yaml
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 進階問題
|
||||
|
||||
### Q: 如何使用反向代理？
|
||||
|
||||
詳見 [反向代理設定](../deployment/reverse-proxy.md)
|
||||
|
||||
### Q: 如何啟用硬體加速？
|
||||
|
||||
詳見 [進階配置 - 硬體加速](../deployment/docker.md#硬體加速)
|
||||
|
||||
### Q: 如何啟用 API Server？
|
||||
|
||||
```bash
|
||||
docker compose --profile api up -d
|
||||
```
|
||||
|
||||
詳見 [API 文件](../api/overview.md)
|
||||
|
||||
---
|
||||
|
||||
## 還有問題？
|
||||
|
||||
- 📖 查看 [完整文件](../README.md)
|
||||
- 🐛 回報問題：[GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues)
|
||||
- 💬 討論區：[GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions)
|
||||
83
docs/getting-started/overview.md
Normal file
83
docs/getting-started/overview.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# ConvertX-CN 概覽
|
||||
|
||||
ConvertX-CN 是一個功能完整的自託管檔案轉換平台，支援 1000+ 種格式轉換。
|
||||
|
||||
---
|
||||
|
||||
## 什麼是 ConvertX-CN？
|
||||
|
||||
ConvertX-CN 是 fork 自 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 的增強版本，針對中文使用者與亞洲地區需求進行優化：
|
||||
|
||||
- **完整的轉換能力**：整合 20+ 種轉換引擎
|
||||
- **中文優化**：內建 CJK 字型、OCR 語言包
|
||||
- **一鍵部署**：Docker 容器化，無需安裝依賴
|
||||
- **多語言介面**：支援 65 種語言
|
||||
|
||||
---
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 📄 文件轉換
|
||||
|
||||
| 引擎 | 用途 | 格式數 |
|
||||
| ----------- | ------------ | ------ |
|
||||
| LibreOffice | 辦公文件 | 60+ |
|
||||
| Pandoc | 標記語言文件 | 100+ |
|
||||
| Calibre | 電子書 | 40+ |
|
||||
| XeLaTeX | LaTeX 文件 | 1 |
|
||||
|
||||
### 🖼️ 圖片處理
|
||||
|
||||
| 引擎 | 用途 | 格式數 |
|
||||
| ----------- | ------------ | ------ |
|
||||
| ImageMagick | 圖片轉換 | 200+ |
|
||||
| Vips | 高效圖片處理 | 45+ |
|
||||
| Inkscape | 向量圖形 | 20+ |
|
||||
| Potrace | 點陣轉向量 | 11 |
|
||||
|
||||
### 🎬 影音轉換
|
||||
|
||||
| 引擎 | 用途 | 格式數 |
|
||||
| ------ | -------- | ------ |
|
||||
| FFmpeg | 影音轉換 | 400+ |
|
||||
|
||||
### 🔬 進階功能
|
||||
|
||||
| 引擎 | 用途 |
|
||||
| ---------------- | ---------------- |
|
||||
| MinerU | PDF → Markdown |
|
||||
| PDFMathTranslate | PDF 公式翻譯保留 |
|
||||
| Tesseract OCR | 光學字元辨識 |
|
||||
|
||||
---
|
||||
|
||||
## 系統需求
|
||||
|
||||
| 需求 | 最低 | 建議 |
|
||||
| -------- | ------ | ------ |
|
||||
| Docker | 20.10+ | 24.0+ |
|
||||
| RAM | 4 GB | 8 GB |
|
||||
| 磁碟空間 | 10 GB | 20 GB |
|
||||
| CPU | 2 核心 | 4 核心 |
|
||||
|
||||
---
|
||||
|
||||
## 與原版差異
|
||||
|
||||
| 功能 | ConvertX | ConvertX-CN |
|
||||
| -------- | -------- | -------------------- |
|
||||
| 鏡像大小 | ~2 GB | ~4-6 GB |
|
||||
| OCR 語言 | 英文 | 中日韓英德法 |
|
||||
| CJK 字型 | ❌ | ✅ Noto CJK + 標楷體 |
|
||||
| TexLive | 基本 | 完整 |
|
||||
| 繁中介面 | ❌ | ✅ 預設 |
|
||||
| MinerU | ❌ | ✅ |
|
||||
| PDF 翻譯 | ❌ | ✅ PDFMathTranslate |
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- 🚀 [快速開始](quick-start.md) — 5 分鐘內完成部署
|
||||
- ❓ [常見問題](faq.md) — 解決常見問題
|
||||
- 📦 [Docker 部署](../deployment/docker.md) — 詳細部署指南
|
||||
144
docs/getting-started/quick-start.md
Normal file
144
docs/getting-started/quick-start.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
# 快速開始
|
||||
|
||||
5 分鐘內完成 ConvertX-CN 部署。
|
||||
|
||||
---
|
||||
|
||||
## 前置需求
|
||||
|
||||
- Docker 20.10+（[安裝指南](https://docs.docker.com/get-docker/)）
|
||||
- 4GB+ 記憶體
|
||||
- 10GB+ 磁碟空間
|
||||
|
||||
---
|
||||
|
||||
## 方法一：Docker Run（最快）
|
||||
|
||||
### 1. 建立資料夾
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
||||
|
||||
# Windows PowerShell
|
||||
mkdir C:\convertx-cn\data; cd C:\convertx-cn
|
||||
|
||||
# Windows CMD
|
||||
mkdir C:\convertx-cn\data
|
||||
cd C:\convertx-cn
|
||||
```
|
||||
|
||||
### 2. 啟動容器
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name convertx-cn \
|
||||
--restart unless-stopped \
|
||||
-p 3000:3000 \
|
||||
-v ./data:/app/data \
|
||||
-e TZ=Asia/Taipei \
|
||||
-e JWT_SECRET=你的隨機字串至少32字元 \
|
||||
convertx/convertx-cn:latest
|
||||
```
|
||||
|
||||
### 3. 開始使用
|
||||
|
||||
開啟瀏覽器訪問：`http://localhost:3000`
|
||||
|
||||
1. 點擊右上角 **Register** 註冊帳號
|
||||
2. 輸入 Email 和密碼
|
||||
3. 完成！開始轉換檔案
|
||||
|
||||
---
|
||||
|
||||
## 方法二：Docker Compose（推薦）
|
||||
|
||||
### 1. 建立專案資料夾
|
||||
|
||||
```bash
|
||||
mkdir -p ~/convertx-cn && cd ~/convertx-cn
|
||||
```
|
||||
|
||||
### 2. 建立配置檔
|
||||
|
||||
建立 `docker-compose.yml`：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
container_name: convertx-cn
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- TZ=Asia/Taipei
|
||||
- JWT_SECRET=請更換為一個長且隨機的字串
|
||||
```
|
||||
|
||||
### 3. 啟動服務
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 驗證安裝
|
||||
|
||||
### 檢查容器狀態
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
# 應該看到 convertx-cn 容器正在運行
|
||||
|
||||
docker logs convertx-cn
|
||||
# 應該看到 "🦊 Elysia is running at http://localhost:3000"
|
||||
```
|
||||
|
||||
### 健康檢查
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/healthcheck
|
||||
# 應該返回 "OK"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 首次設定
|
||||
|
||||
### 建立帳號
|
||||
|
||||
首次訪問時，系統會顯示註冊頁面。第一個註冊的帳號即為管理員。
|
||||
|
||||
### 關閉公開註冊
|
||||
|
||||
如果只有您使用，建議關閉公開註冊：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常見啟動問題
|
||||
|
||||
| 問題 | 解決方法 |
|
||||
| ------------------ | ---------------------------------------------- |
|
||||
| Port 被占用 | 改用其他 port，如 `-p 8080:3000` |
|
||||
| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
|
||||
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
|
||||
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
|
||||
| 權限錯誤 | 執行 `chmod -R 777 ./data` |
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- 📖 [Docker 詳細配置](../deployment/docker.md)
|
||||
- ⚙️ [環境變數設定](../configuration/environment-variables.md)
|
||||
- 🔒 [安全性設定](../configuration/security.md)
|
||||
- 🔧 [反向代理設定](../deployment/reverse-proxy.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue