convertor/docs/國際化說明.md

多語言支援（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：

{
  "common": {
    "appName": "ConvertX-CN",
    "poweredBy": "Powered by",
    "version": "v{version}",
    "loading": "...",
    ...
  },
  "nav": {
    "history": "...",
    "account": "...",
    ...
  },
  ...
}

2. 在 index.ts 中註冊

編輯 src/i18n/index.ts：

// 導入新語言檔案
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. 測試

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