Localization Test

localization-test

⚙️ 執行前先讀 modules/config-loader.md。

為什麼需要

多語言 App 常見問題：

• 字串漏譯 → 英文 fallback 出現在 UI（不專業）
• 字串溢出 → 德文 / 法文比英文長 30%，按鈕爆框
• RTL 渲染錯 → 阿拉伯 / 希伯來文整個 layout 應該鏡像
• 格式錯 → 日期 03/05 在美式是 3 月 5 日，歐式是 5 月 3 日
• 複數錯 → 「1 item / 2 items」直接套到俄文（俄文有 3 種複數）
• Locale 切換 bug → 切了 locale 但部分頁面沒更新

→ 本 skill 系統性檢查上述所有問題。

適用場景

• ✅ App 上架多國市場（≥ 3 種語言）
• ✅ 出海前 release 守門
• ✅ 加新語言時做 baseline check
• ✅ 中國 App 出海要含繁中/簡中/英文/日文

不適用場景

• ❌ 只有單一語言
• ❌ 翻譯品質審查 — 那是語言專家工作，不是 QA

6 大檢查維度

1. 翻譯完整性（Missing keys）

掃描資源檔（iOS .strings / Android strings.xml / Flutter .arb / i18n .json）：

# 找漏譯
diff <(jq -r 'keys[]' i18n/en.json | sort) \
     <(jq -r 'keys[]' i18n/ja.json | sort)

報告：日文版漏 23 個 key。

2. 字串長度溢出

各語言相對英文的平均長度（給設計用：）

掃 UI snapshot（用 visual-regression-gen 的 baseline）+ 量化文字寬度。

3. RTL 渲染

對 RTL 語言（ar / he / fa / ur）：

• Layout 應 mirror（icon 左右翻轉）
• 文字對齊右
• 但數字 / 英文夾雜仍 LTR 顯示
• 圖示不該翻轉（電池 / 信號）

跑 Playwright 截 RTL screenshot 對比：

test('RTL layout for Arabic', async ({ page, browserName }) => {
  await page.goto('/', { locale: 'ar-SA' });
  await expect(page).toHaveScreenshot('home-ar.png');
});

4. 日期 / 數字 / 貨幣格式

驗 Intl.DateTimeFormat / Intl.NumberFormat 是否被正確使用：

❌ 偵測 hard-coded format：new Date().toLocaleString() 不傳 locale → 隨機。

5. Pluralization 複數規則

// ❌ Bad
`You have ${count} ${count > 1 ? 'items' : 'item'}`

// ✅ Good (i18n library)
i18n.t('items_count', { count })
// 自動處理 ru: 1 item / 2 items / 5 items (3 種複數)

6. Locale 切換不重啟

驗使用者切 locale 後：

• 所有開啟的頁面立即更新
• 不需要重啟 App
• Push notification token 不重置（保留訂閱）

執行流程

Phase 1: 偵測 i18n 框架

Phase 2: 自動跑 6 大檢查

對每個 locale 跑：

• 漏譯：diff against base locale
• 長度：scan UI snapshot
• RTL：visual diff
• 格式：grep code for hard-coded
• 複數：grep count > 1 ? pattern
• 切換：UI test 自動切 + verify

Phase 3: 報告

# Localization Test Report · my-app · 2026-05-22

## 📊 整體
- Supported locales: en, zh-TW, zh-CN, ja, de, ar
- Missing translations: 28 (across 6 locales)
- Length overflow: 12 (mostly de in buttons)
- RTL issues: 4 (icon mirroring incorrect)
- Format issues: 6 (hard-coded date format)
- Pluralization issues: 3 (using `count > 1`)
- Locale switch issues: 0 ✅

## 🔴 Critical

### Missing translations - ja.json (23 keys)
- `auth.session_expired`
- `cart.empty_state`
- ...

### Length overflow - "Sign In" button (de)
- en: "Sign In" (60 px)
- de: "Anmelden" (95 px)
- 按鈕設計寬 80 px → 溢出
- 修法: 按鈕設計改 min-width: 120 px

## 🟡 Recommendations

- [ ] 補齊 23 個日文翻譯 key
- [ ] 12 個 button 改 min-width
- [ ] 4 個 icon 加 RTL aware logic
- [ ] 6 個日期格式改用 Intl.DateTimeFormat

⚠️ 安全護欄

• ❌ 不評論翻譯品質（語意是否到位）— 那是語言專家工作
• ✅ 只報「結構性問題」（漏字 / 溢出 / 格式 / RTL）
• ✅ Visual regression 對比需要先有 baseline

設定依賴

範例

詳見 examples.md