docs: README 重構 + i18n UI 規範 + 文件連結整理

README 改動:
- 新增 Docker Run 快速啟動區塊
- 重新編排為 10 個標準區塊
- 加入作業系統資料夾提醒表格
- 精簡進階設定為連結列表
- 減少 emoji 使用

docs 改動:
- i18n.md 新增語言選擇器 UI 規範
- getting-started.md 去重並加入返回連結
- 標題與連結一致化
This commit is contained in:
Your Name 2026-01-20 17:00:21 +08:00
parent bf8784ed82
commit 1a8548ff66
3 changed files with 133 additions and 57 deletions

144
README.md
View file

@ -2,42 +2,47 @@
# ConvertX-CN # ConvertX-CN
**開箱即用的全功能檔案轉換服務** **開箱即用的全功能檔案轉換服務** — 一個 Docker 命令5 分鐘部署完成
[![Docker Pulls](https://img.shields.io/docker/pulls/convertx/convertx-cn?style=flat&logo=docker)](https://hub.docker.com/r/convertx/convertx-cn) [![Docker Pulls](https://img.shields.io/docker/pulls/convertx/convertx-cn?style=flat&logo=docker)](https://hub.docker.com/r/convertx/convertx-cn)
[![GitHub Release](https://img.shields.io/github/v/release/pi-docket/ConvertX-CN)](https://github.com/pi-docket/ConvertX-CN/releases) [![GitHub Release](https://img.shields.io/github/v/release/pi-docket/ConvertX-CN)](https://github.com/pi-docket/ConvertX-CN/releases)
--- ---
## 這是什麼 ## 為什麼選擇 ConvertX-CN
自架的檔案轉換服務,支援 **1000+ 格式**,包含影音、圖片、文件、電子書等。 - 支援 **1000+ 格式**(影音、圖片、文件、電子書)
已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器與中日韓字型,**一個 Docker 命令就能跑**。 - 已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器
- 預載中日韓字型與 OCR 語言包
- 支援 65 種介面語言
--- ---
## 快速部署 ## 快速啟動Docker Run
### 1. 建立資料夾
```bash ```bash
# 1. 建立資料夾
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
# 2. 啟動容器
docker run -d \ docker run -d \
--name convertx-cn \ --name convertx-cn \
--restart unless-stopped \
-p 3000:3000 \ -p 3000:3000 \
-v ./data:/app/data \ -v ./data:/app/data \
-e JWT_SECRET=your-secret-key-at-least-32-chars \ -e TZ=Asia/Taipei \
-e JWT_SECRET=請改成你自己的隨機字串至少32字元 \
convertx/convertx-cn:latest convertx/convertx-cn:latest
# 3. 開啟瀏覽器
# http://localhost:3000
``` ```
開啟 `http://localhost:3000` 註冊即可使用。 > 首次下載約 4-6 GB請耐心等待。
> Windows 用戶請先 `mkdir C:\convertx-cn\data`,並將 `./data` 改為 `C:\convertx-cn\data`
--- ---
## ✅ 推薦方式(Docker Compose ## Docker Compose(推薦
建立 `docker-compose.yml` 建立 `docker-compose.yml`
@ -53,67 +58,104 @@ services:
- ./data:/app/data - ./data:/app/data
environment: environment:
- TZ=Asia/Taipei - TZ=Asia/Taipei
- JWT_SECRET=your-secret-key-at-least-32-chars - JWT_SECRET=請改成你自己的隨機字串至少32字元
``` ```
| 參數 | 說明 | 必要 | 啟動:
| ------------ | ---------------------------------- | ---- |
| `./data` | 存放檔案的資料夾,必須先建立 | ✅ |
| `JWT_SECRET` | 登入驗證金鑰,不設會每次重啟被登出 | ✅ |
| `TZ` | 時區(預設 UTC | — |
### 3. 啟動
```bash ```bash
docker compose up -d docker compose up -d
``` ```
| 參數 | 說明 | 更多範例 → [docs/docker-compose/](docs/docker-compose/)
| ------------ | ------------------ |
| `./data` | 資料夾,需先建立 |
| `JWT_SECRET` | 登入金鑰,必須設定 |
首次下載約 4-6 GB。
--- ---
## 支援格式 ## 重要:資料夾說明
| 類型 | 轉換器 | 格式數 | `./data` 是你**主機上的實體資料夾**,用於存放上傳檔案、轉換結果與使用者資料。
| ------ | -------------------------- | ------ |
| 影音 | FFmpeg | 400+ |
| 圖片 | ImageMagick, libvips | 200+ |
| 文件 | LibreOffice, Pandoc | 150+ |
| 電子書 | Calibre | 40+ |
| 向量圖 | Inkscape, resvg, Potrace | 20+ |
| 資料 | Dasel (JSON/YAML/TOML/XML) | 10+ |
完整列表 → [docs/converters.md](docs/converters.md) | 作業系統 | 建立指令 |
| ------------- | ----------------------------- |
| Linux / macOS | `mkdir -p ~/convertx-cn/data` |
| Windows (PS) | `mkdir C:\convertx-cn\data` |
| Windows (CMD) | `mkdir C:\convertx-cn\data` |
> 若不先建立Docker 會建立匿名 volume導致資料難以存取或備份。
---
## 必要參數
| 參數 | 說明 |
| ------------ | ---------------------------------- |
| `./data` | 主機資料夾,必須先建立 |
| `JWT_SECRET` | 登入驗證金鑰,不設會每次重啟被登出 |
其他環境變數 → [docs/config/environment.md](docs/config/environment.md)
--- ---
## 常見問題 ## 常見問題
| 問題 | 解法 | | 問題 | 解法 |
| ------------ | ---------------------------------------------- | | -------------------- | ---------------------------------------------- |
| 登入後被踢回 | 設定 `HTTP_ALLOWED=true``TRUST_PROXY=true` | | 登入後又被踢回登入頁 | 加上 `HTTP_ALLOWED=true``TRUST_PROXY=true` |
| 資料消失 | 確認 `./data:/app/data` 已掛載 | | 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
| 重啟後登出 | 設定固定 `JWT_SECRET` | | 重啟後登出 | 設定固定 `JWT_SECRET` |
更多 → [docs/faq.md](docs/faq.md) 更多問題 → [docs/faq.md](docs/faq.md)
---
## 支援格式
| 轉換器 | 用途 | 格式數 |
| ----------- | ------ | ------ |
| FFmpeg | 影音 | 400+ |
| ImageMagick | 圖片 | 200+ |
| LibreOffice | 文件 | 60+ |
| Pandoc | 文件 | 100+ |
| Calibre | 電子書 | 40+ |
| Inkscape | 向量圖 | 20+ |
完整列表 → [docs/converters.md](docs/converters.md)
---
## 語言支援
支援 **65 種語言**,包含繁體中文、簡體中文、英文、日文、韓文等。
語言會根據瀏覽器設定自動偵測,也可透過右上角選單手動切換。
詳細說明 → [docs/i18n.md](docs/i18n.md)
---
## 版本與更新
```bash
docker compose down
docker compose pull
docker compose up -d
```
- 版本說明 → [docs/versions/](docs/versions/)
- 更新指南 → [docs/deployment/update.md](docs/deployment/update.md)
- Changelog → [CHANGELOG.md](CHANGELOG.md)
--- ---
## 進階文件 ## 進階文件
| 主題 | 連結 | | 文件 | 說明 |
| ---------------- | -------------------------------------------------------- | | -------------------------------------- | ------------------------- |
| 環境變數 | [docs/config/environment.md](docs/config/environment.md) | | [環境變數](docs/config/environment.md) | 所有可用參數 |
| 安全性設定 | [docs/config/security.md](docs/config/security.md) | | [安全性設定](docs/config/security.md) | HTTP_ALLOWED、TRUST_PROXY |
| 反向代理 / HTTPS | [docs/deployment.md](docs/deployment.md) | | [反向代理](docs/deployment.md) | Nginx / Traefik / Caddy |
| Docker Compose | [docs/docker-compose/](docs/docker-compose/) | | [Docker 進階](docs/docker.md) | 自訂 Build |
| 版本選擇 | [docs/versions/](docs/versions/) | | [FAQ](docs/faq.md) | 疑難排解 |
| 更新方法 | [docs/deployment/update.md](docs/deployment/update.md) |
--- ---
@ -123,4 +165,6 @@ docker compose up -d
--- ---
## License
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) [MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)

View file

@ -1,5 +1,9 @@
# 快速開始 # 快速開始
> 本文件提供完整部署步驟。若只需最快啟動,請參考 [README](../README.md)。
---
## 系統需求 ## 系統需求
| 需求 | 最低 | 建議 | | 需求 | 最低 | 建議 |
@ -11,26 +15,28 @@
--- ---
## 事前準備(可選) ## 事前準備
如果您想預先建立資料夾結構 建立資料夾(重要)
```bash ```bash
mkdir -p data mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
``` ```
> 💡 Docker 會自動建立 `data` 資料夾,此步驟為可選 > `data` 資料夾是主機上的實體資料夾,用於存放上傳檔案與轉換結果。
--- ---
## 最快方式:一行指令 ## 最快方式:Docker Run
```bash ```bash
docker run -d \ docker run -d \
--name convertx-cn \ --name convertx-cn \
--restart unless-stopped \
-p 3000:3000 \ -p 3000:3000 \
-v ./data:/app/data \ -v ./data:/app/data \
-e TZ=Asia/Taipei \ -e TZ=Asia/Taipei \
-e JWT_SECRET=你的隨機字串至少32字元 \
convertx/convertx-cn:latest convertx/convertx-cn:latest
``` ```
@ -40,8 +46,6 @@ docker run -d \
2. 輸入 Email 和密碼 2. 輸入 Email 和密碼
3. 完成!開始使用 3. 完成!開始使用
> ✅ **預設開放註冊**,無需設定環境變數
--- ---
## 推薦方式Docker Compose ## 推薦方式Docker Compose

View file

@ -213,6 +213,34 @@ bun run dev
--- ---
## 語言選擇器 UI 規範
為確保語言切換體驗一致ConvertX-CN 的語言選擇器遵循以下規範:
### 視覺設計
| 項目 | 規範 |
| ------------ | ----------------------------- |
| 圖示大小 | 與旁邊文字高度一致h-6 w-6 |
| 下拉選單背景 | 完全不透明bg-neutral-800 |
| 捲動條 | 明確可見的 scrollbar 樣式 |
| 最大高度 | 320px超過則顯示捲動條 |
### 行為規範
- Setup / Login / 主頁使用同一套語言選擇器組件
- 語言切換後自動重新載入頁面
- 語言偏好儲存於 Cookie跨頁面保持一致
- 預設根據瀏覽器語言自動偵測
### 已知問題修復v0.1.9
- 語言圖示尺寸過小 → 已修復
- 下拉選單半透明 → 已修復
- 捲動條不明顯 → 已新增 scrollbar 樣式
---
## 翻譯 Fallback ## 翻譯 Fallback
如果某個翻譯鍵缺失,系統會: 如果某個翻譯鍵缺失,系統會: