1a8548ff66
README 改動： - 新增 Docker Run 快速啟動區塊 - 重新編排為 10 個標準區塊 - 加入作業系統資料夾提醒表格 - 精簡進階設定為連結列表 - 減少 emoji 使用 docs 改動： - i18n.md 新增語言選擇器 UI 規範 - getting-started.md 去重並加入返回連結 - 標題與連結一致化
270 lines
7.1 KiB
Markdown
270 lines
7.1 KiB
Markdown
# 多語言支援（i18n）
|
||
|
||
ConvertX-CN 支援 **65 種語言**，是目前最完整的多語言檔案轉換服務。
|
||
|
||
---
|
||
|
||
## 支援語言列表
|
||
|
||
### 東亞語言（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` | 馬其頓文 | Македонски |
|
||
|
||
### 波羅的海語言（3 種）
|
||
|
||
| 代碼 | 語言 | 原生名稱 |
|
||
| ---- | ---------- | -------- |
|
||
| `lt` | 立陶宛文 | Lietuvių |
|
||
| `lv` | 拉脫維亞文 | Latviešu |
|
||
| `et` | 愛沙尼亞文 | Eesti |
|
||
|
||
### 其他歐洲語言（4 種）
|
||
|
||
| 代碼 | 語言 | 原生名稱 |
|
||
| ---- | ------------ | -------- |
|
||
| `el` | 希臘文 | Ελληνικά |
|
||
| `sq` | 阿爾巴尼亞文 | Shqip |
|
||
| `ga` | 愛爾蘭文 | Gaeilge |
|
||
| `cy` | 威爾斯文 | Cymraeg |
|
||
|
||
### 中東語言（4 種）
|
||
|
||
| 代碼 | 語言 | 原生名稱 |
|
||
| ---- | -------- | -------- |
|
||
| `ar` | 阿拉伯文 | العربية |
|
||
| `he` | 希伯來文 | עברית |
|
||
| `fa` | 波斯文 | فارسی |
|
||
| `tr` | 土耳其文 | Türkçe |
|
||
|
||
### 南亞語言（10 種）
|
||
|
||
| 代碼 | 語言 | 原生名稱 |
|
||
| ---- | ------------ | -------- |
|
||
| `hi` | 印地文 | हिन्दी |
|
||
| `bn` | 孟加拉文 | বাংলা |
|
||
| `ta` | 泰米爾文 | தமிழ் |
|
||
| `te` | 泰盧固文 | తెలుగు |
|
||
| `mr` | 馬拉地文 | मराठी |
|
||
| `gu` | 古吉拉特文 | ગુજરાતી |
|
||
| `kn` | 卡納達文 | ಕನ್ನಡ |
|
||
| `ml` | 馬拉雅拉姆文 | മലയാളം |
|
||
| `ne` | 尼泊爾文 | नेपाली |
|
||
| `si` | 僧伽羅文 | සිංහල |
|
||
|
||
### 東南亞語言（8 種）
|
||
|
||
| 代碼 | 語言 | 原生名稱 |
|
||
| ----- | -------- | ---------------- |
|
||
| `th` | 泰文 | ไทย |
|
||
| `vi` | 越南文 | Tiếng Việt |
|
||
| `id` | 印尼文 | Bahasa Indonesia |
|
||
| `ms` | 馬來文 | Bahasa Melayu |
|
||
| `fil` | 菲律賓文 | Filipino |
|
||
| `my` | 緬甸文 | မြန်မာ |
|
||
| `km` | 高棉文 | ខ្មែរ |
|
||
| `lo` | 寮文 | ລາວ |
|
||
|
||
### 非洲語言（4 種）
|
||
|
||
| 代碼 | 語言 | 原生名稱 |
|
||
| ---- | ---------- | --------- |
|
||
| `af` | 南非語 | Afrikaans |
|
||
| `sw` | 斯瓦希里文 | Kiswahili |
|
||
| `am` | 阿姆哈拉文 | አማርኛ |
|
||
| `zu` | 祖魯文 | isiZulu |
|
||
|
||
---
|
||
|
||
## 語言切換
|
||
|
||
### 方法一：介面切換
|
||
|
||
1. 在網站右上角的導航列找到語言圖示（🌐）
|
||
2. 點擊後選擇偏好語言
|
||
3. 語言偏好會自動保存到 Cookie 中
|
||
|
||
### 方法二：URL 參數
|
||
|
||
```
|
||
http://localhost:3000/?lang=ja
|
||
```
|
||
|
||
### 方法三：瀏覽器設定
|
||
|
||
ConvertX-CN 會自動偵測瀏覽器的語言設定。
|
||
|
||
---
|
||
|
||
## 自動偵測
|
||
|
||
首次訪問時，系統會根據以下優先順序選擇語言：
|
||
|
||
1. Cookie 中儲存的語言偏好
|
||
2. URL 參數中的 `lang` 值
|
||
3. 瀏覽器的 `Accept-Language` 標頭
|
||
4. 預設語言（繁體中文 `zh-TW`）
|
||
|
||
---
|
||
|
||
## 新增語言
|
||
|
||
如要添加新語言支援，請按以下步驟：
|
||
|
||
### 1. 建立翻譯檔案
|
||
|
||
在 `src/locales/` 目錄新增語言檔案，例如 `xx.json`：
|
||
|
||
```json
|
||
{
|
||
"common": {
|
||
"appName": "ConvertX-CN",
|
||
"poweredBy": "Powered by",
|
||
"version": "v{version}",
|
||
"loading": "...",
|
||
...
|
||
},
|
||
"nav": {
|
||
"history": "...",
|
||
"account": "...",
|
||
...
|
||
},
|
||
...
|
||
}
|
||
```
|
||
|
||
### 2. 在 index.ts 中註冊
|
||
|
||
編輯 `src/i18n/index.ts`：
|
||
|
||
```typescript
|
||
// 導入新語言檔案
|
||
import xx from "../locales/xx.json";
|
||
|
||
// 在 SupportedLocale 類型中添加
|
||
export type SupportedLocale = "en" | "zh-TW" | ... | "xx";
|
||
|
||
// 在 supportedLocales 陣列中添加
|
||
export const supportedLocales: LocaleConfig[] = [
|
||
// ...
|
||
{ code: "xx", name: "Language Name", nativeName: "原生名稱" },
|
||
];
|
||
|
||
// 在 translations 物件中註冊
|
||
const translations: Record<SupportedLocale, TranslationData> = {
|
||
// ...
|
||
xx: xx as TranslationData,
|
||
};
|
||
```
|
||
|
||
### 3. 測試
|
||
|
||
```bash
|
||
bun run dev
|
||
# 訪問 http://localhost:3000/?lang=xx
|
||
```
|
||
|
||
---
|
||
|
||
## 語言選擇器 UI 規範
|
||
|
||
為確保語言切換體驗一致，ConvertX-CN 的語言選擇器遵循以下規範：
|
||
|
||
### 視覺設計
|
||
|
||
| 項目 | 規範 |
|
||
| ------------ | ----------------------------- |
|
||
| 圖示大小 | 與旁邊文字高度一致（h-6 w-6） |
|
||
| 下拉選單背景 | 完全不透明（bg-neutral-800） |
|
||
| 捲動條 | 明確可見的 scrollbar 樣式 |
|
||
| 最大高度 | 320px，超過則顯示捲動條 |
|
||
|
||
### 行為規範
|
||
|
||
- Setup / Login / 主頁使用同一套語言選擇器組件
|
||
- 語言切換後自動重新載入頁面
|
||
- 語言偏好儲存於 Cookie，跨頁面保持一致
|
||
- 預設根據瀏覽器語言自動偵測
|
||
|
||
### 已知問題修復（v0.1.9）
|
||
|
||
- 語言圖示尺寸過小 → 已修復
|
||
- 下拉選單半透明 → 已修復
|
||
- 捲動條不明顯 → 已新增 scrollbar 樣式
|
||
|
||
---
|
||
|
||
## 翻譯 Fallback
|
||
|
||
如果某個翻譯鍵缺失，系統會：
|
||
|
||
1. 嘗試使用英文（`en`）翻譯
|
||
2. 如果英文也缺失，顯示鍵名（如 `nav.history`）
|
||
|
||
---
|
||
|
||
## 貢獻翻譯
|
||
|
||
歡迎提交 Pull Request 來新增或改進翻譯！
|
||
|
||
### 翻譯指南
|
||
|
||
1. **完整翻譯**：確保所有鍵都有翻譯
|
||
2. **保留佔位符**：`{version}`、`{count}` 等佔位符不要翻譯
|
||
3. **自然表達**：使用該語言的自然表達方式
|
||
4. **一致性**：同一個詞在不同地方使用相同翻譯
|
||
5. **測試**：在實際介面中測試翻譯效果
|
||
|
||
### 提交流程
|
||
|
||
1. Fork 此專案
|
||
2. 建立新語言檔案或修改現有翻譯
|
||
3. 測試確認無誤
|
||
4. 提交 Pull Request
|