i18n-localization

i18n 與在地化

國際化 (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(_("Welcome to our app"))

---

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>

使用時機

此技能適用於執行概述中所述的工作流程或動作。

限制

• 僅在任務明確符合上述範圍時使用此技能。
• 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
• 若缺少必要輸入、權限、安全邊界或成功標準，請停止並要求澄清。