i18n-workflow

我的功能

• 提供多語言開發的標準化流程
• 確保五種語言 (繁中、簡中、英、日、韓) 的一致性
• 管理翻譯檔案的新增、更新和維護
• 協助實現語言持久化和即時切換

何時使用我

在以下情況下使用此技能：

• 新增使用者可見的文字或訊息時
• 修改現有文字內容時
• 新增新功能需要多語言支援
• 檢查翻譯完整性和一致性
• 設定語言切換功能

支援語言

本專案支援五種語言：

• 繁體中文 (zh-TW) – 預設語言
• 簡體中文 (zh-CN)
• 英文 (en)
• 日文 (ja)
• 韓文 (ko)

檔案結構

src/i18n/
├── config.ts               # i18next 配置
└── locales/
    ├── zh-TW.json         # 繁體中文（預設）
    ├── zh-CN.json         # 簡體中文
    ├── en.json            # 英文
    ├── ja.json            # 日文
    └── ko.json            # 韓文

使用 i18next

在元件中使用

'use client';

import { useTranslation } from 'react-i18next';

export default function Component() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('common.appName')}</h1>
      <p>{t('stats.speed')}</p>
      <button>{t('actions.save')}</button>
    </div>
  );
}

語言切換

'use client';

import { useTranslation } from 'react-i18next';
import { useAtom } from 'jotai';
import { languageAtom } from '@/store/dataAtoms';

export default function LanguageSelector() {
  const { i18n } = useTranslation();
  const [language, setLanguage] = useAtom(languageAtom);

  const handleLanguageChange = (lang: string) => {
    i18n.changeLanguage(lang);
    setLanguage(lang as SupportedLanguage);
  };

  return (
    <select
      value={language}
      onChange={(e) => handleLanguageChange(e.target.value)}
    >
      <option value="zh-TW">繁體中文</option>
      <option value="zh-CN">简体中文</option>
      <option value="en">English</option>
      <option value="ja">日本語</option>
      <option value="ko">한국어</option>
    </select>
  );
}

新增翻譯流程

重要原則

⚠️ 必須同時更新所有五個語言檔案

每次新增或修改翻譯時，必須確保所有語言檔案都有對應的翻譯內容。

步驟

1. 確定翻譯 Key 結構

使用點號分隔的命名空間結構：

category.subcategory.key

範例：

• common.appName – 通用類別的應用程式名稱
• stats.speed – 統計類別的速度
• actions.save – 動作類別的儲存

2. 在所有語言檔案中新增翻譯

// zh-TW.json
{
  "newFeature": {
    "title": "新功能標題",
    "description": "新功能說明",
    "button": "確認"
  }
}

// zh-CN.json
{
  "newFeature": {
    "title": "新功能标题",
    "description": "新功能说明",
    "button": "确认"
  }
}

// en.json
{
  "newFeature": {
    "title": "New Feature Title",
    "description": "New feature description",
    "button": "Confirm"
  }
}

// ja.json
{
  "newFeature": {
    "title": "新機能タイトル",
    "description": "新機能の説明",
    "button": "確認"
  }
}

// ko.json
{
  "newFeature": {
    "title": "새 기능 제목",
    "description": "새 기능 설명",
    "button": "확인"
  }
}

3. 在元件中使用

'use client';

import { useTranslation } from 'react-i18next';

export default function NewFeature() {
  const { t } = useTranslation();

  return (
    <div>
      <h2>{t('newFeature.title')}</h2>
      <p>{t('newFeature.description')}</p>
      <button>{t('newFeature.button')}</button>
    </div>
  );
}

翻譯檔案結構規範

命名空間分類

{
  "common": {
    "appName": "應用程式名稱",
    "loading": "載入中...",
    "error": "錯誤訊息"
  },
  "navigation": {
    "home": "首頁",
    "about": "關於",
    "settings": "設定"
  },
  "stats": {
    "speed": "速度",
    "acceleration": "加速度",
    "weight": "重量",
    "handling": "操控性"
  },
  "actions": {
    "save": "儲存",
    "cancel": "取消",
    "confirm": "確認",
    "delete": "刪除"
  },
  "messages": {
    "success": "操作成功",
    "error": "操作失敗",
    "warning": "警告訊息"
  }
}

保持結構一致

所有語言檔案必須保持相同的 JSON 結構：

// ✅ 正確 - 所有語言有相同的 key
// zh-TW.json
{
  "user": {
    "profile": "個人資料",
    "settings": "設定"
  }
}

// en.json
{
  "user": {
    "profile": "Profile",
    "settings": "Settings"
  }
}

// ❌ 錯誤 - 結構不一致
// zh-TW.json
{
  "user": {
    "profile": "個人資料",
    "settings": "設定"
  }
}

// en.json
{
  "user": {
    "profile": "Profile"
    // 缺少 settings
  }
}

語言持久化

使用 Jotai atomWithStorage

// store/dataAtoms.ts
import { atomWithStorage } from "jotai/utils";

export const languageAtom = atomWithStorage<SupportedLanguage>(
  "mario-kart-language",
  "zh-TW",
);

語言持久化 Hook

// hooks/useLanguagePersistence.ts
"use client";

import { useEffect } from "react";
import { useAtom } from "jotai";
import { useTranslation } from "react-i18next";
import { languageAtom } from "@/store/dataAtoms";

export function useLanguagePersistence() {
  const [language] = useAtom(languageAtom);
  const { i18n } = useTranslation();

  useEffect(() => {
    if (language && i18n.language !== language) {
      i18n.changeLanguage(language);
    }
  }, [language, i18n]);
}

翻譯品質原則

1. 準確性

• 翻譯必須準確傳達原意
• 避免使用機器翻譯的生硬表達
• 符合目標語言的語言習慣

2. 一致性

• 相同概念使用相同翻譯
• 建立專案術語表
• 統一專有名詞的翻譯

3. 簡潔性

• 避免冗長的翻譯
• 使用簡潔清晰的表達
• 考慮 UI 空間限制

4. 文化適應

• 考慮不同文化背景
• 避免文化敏感內容
• 適應當地使用習慣

動態翻譯

帶參數的翻譯

// zh-TW.json
{
  "greeting": "你好，{{name}}！",
  "itemCount": "共 {{count}} 個項目"
}

// 使用
const { t } = useTranslation();

<p>{t('greeting', { name: '使用者' })}</p>
<p>{t('itemCount', { count: 10 })}</p>

複數形式處理

// en.json
{
  "items": "{{count}} item",
  "items_other": "{{count}} items"
}

const { t } = useTranslation();

<p>{t('items', { count: 1 })}</p>  // "1 item"
<p>{t('items', { count: 5 })}</p>  // "5 items"

檢查清單

在提交翻譯前，請確認：

• 所有五個語言檔案都已更新
• JSON 格式正確，沒有語法錯誤
• 所有語言檔案結構一致
• 翻譯準確且符合語言習慣
• 使用 t() 函式而非硬編碼文字
• 語言切換功能正常運作
• localStorage 正確儲存語言設定
• 測試所有語言的顯示效果

常見問題

Q: 如何處理長文字翻譯？

A: 將長文字拆分為多個 key，或使用換行符號：

{
  "longText": "這是第一段文字。\n這是第二段文字。"
}

Q: 如何處理 HTML 標籤？

A: 使用 Trans 組件：

import { Trans } from 'react-i18next';

<Trans i18nKey="richText">
  This is <strong>bold</strong> text.
</Trans>

Q: 如何確保翻譯完整性？

A: 建立自動化腳本檢查所有語言檔案是否有相同的 key 結構。

Q: 如何處理圖片中的文字？

A: 為不同語言準備不同的圖片，根據當前語言動態載入。

測試流程

1. 手動測試

# 啟動開發伺服器
pnpm dev

# 測試步驟：
1. 切換到每種語言
2. 檢查所有頁面的文字顯示
3. 確認語言設定被正確儲存
4. 重新載入頁面確認語言保持

2. JSON 格式驗證

# 使用 JSON linter 檢查語法
pnpm lint

3. 翻譯覆蓋率檢查

建立腳本檢查所有語言檔案的 key 是否一致：

// scripts/check-i18n.ts
const fs = require("fs");

const languages = ["zh-TW", "zh-CN", "en", "ja", "ko"];
const locales = {};

languages.forEach((lang) => {
  locales[lang] = JSON.parse(
    fs.readFileSync(`src/i18n/locales/${lang}.json`, "utf-8"),
  );
});

// 檢查 key 一致性
// ... 實作邏輯

最佳實踐

1. 早期國際化

從專案開始就使用 t() 函式，避免後期大規模重構。

2. 翻譯文件化

建立翻譯指南文件，說明專案特定的術語翻譯。

3. 版本控制

使用 Git 追蹤翻譯檔案變更，便於審查和回溯。

4. 團隊協作

• 指定語言負責人審核翻譯
• 使用 Pull Request 審查翻譯變更
• 建立翻譯討論群組

5. 持續優化

• 收集使用者反饋
• 定期審查和優化翻譯
• 保持翻譯與功能同步更新

參考資源

• i18next 官方文件
• react-i18next 文件
• Google 國際化指南
• W3C 國際化最佳實踐