i18n 與本地化
選擇性閱讀規則
從以下文件開始:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
然後僅載入符合使用者實際任務的繼承文件、腳本、資產或範例。
國際化(i18n)和本地化(L10n)的最佳實務。
1. 核心概念
| 術語 | 意義 |
|---|---|
| i18n | 國際化 - 讓應用程式可翻譯 |
| L10n | 本地化 - 實際的翻譯 |
| Locale | 語言 + 地區(en-US、tr-TR) |
| RTL | 從右到左的語言(阿拉伯語、希伯來語) |
2. 何時使用 i18n
| 專案類型 | 需要 i18n? |
|---|---|
| 公開網頁應用程式 | ✅ 是 |
| SaaS 產品 | ✅ 是 |
| 內部工具 | ⚠️ 可能 |
| 單一地區應用程式 | ⚠️ 考慮未來需求 |
| 個人專案 | ❌ 選擇性 |
3. 實作模式
React (react-i18next)
import { useTranslation } from 'react-i18next';
function Welcome() {
const { t } = useTranslation();
return <h1>{t('welcome.title')}</h1>;
}
Next.js (next-intl)
import { useTranslations } from 'next-intl';
export default function Page() {
const t = useTranslations('Home');
return <h1>{t('title')}</h1>;
}
Python (gettext)
from gettext import gettext as _
print(_("歡迎使用我們的應用程式"))
4. 檔案結構
locales/
├── en/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
├── tr/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
└── ar/ # RTL
└── ...
5. 最佳實務
應該做 ✅
- 使用翻譯鍵,而不是原始文字
- 按功能命名空間來組織翻譯
- 支援複數形式
- 根據地區設定處理日期/數字格式
- 從一開始就規劃 RTL 支援
- 對於複雜字串使用 ICU 訊息格式
不應該做 ❌
- 在元件中硬編碼字串
- 串接已翻譯的字串
- 假設文字長度(德語長度約增加 30%)
- 忘記 RTL 版面配置
- 在同一個檔案中混用語言
6. 常見問題
| 問題 | 解決方案 |
|---|---|
| 缺少翻譯 | 回退到預設語言 |
| 硬編碼字串 | 使用 linter/檢查腳本 |
| 日期格式 | 使用 Intl.DateTimeFormat |
| 數字格式 | 使用 Intl.NumberFormat |
| 複數形式 | 使用 ICU 訊息格式 |
7. RTL 支援
/* CSS 邏輯屬性 */
.container {
margin-inline-start: 1rem; /* 而非 margin-left */
padding-inline-end: 1rem; /* 而非 padding-right */
}
[dir="rtl"] .icon {
transform: scaleX(-1);
}
8. 檢查清單
出貨前請確認:
- 所有面向使用者的字串皆使用翻譯鍵
- 所有支援語言的語言檔均已存在
- 日期/數字格式使用 Intl API
- RTL 版面配置已測試(如適用)
- 已設定回退語言
- 元件中沒有硬編碼字串
腳本
| 腳本 | 用途 | 命令 |
|---|---|---|
scripts/i18n_checker.py | 檢測硬編碼字串與遺漏的翻譯 | python scripts/i18n_checker.py <project_path> |