---

name: dy-skill-i18n description: 處理前端國際化翻譯工作。當用戶提到需要做國際化、i18n、翻譯、多語言支援時使用此 skill。主要功能：1) 識別程式碼中的硬編碼靜態文字；2) 判斷是否應使用現有公共翻譯或需要新增；3) 將翻譯新增到對應的語言檔案中；4) 將硬編碼替換為國際化呼叫；5) 檢查翻譯完整性和正確性。

---

國際化翻譯 Skill

目錄

• 核心原則
• 工作流程
• 常見問題處理
• 翻譯準確性要求
• 注意事項
• 驗證與錯誤處理

---

概述

此 skill 用於處理前端專案的國際化翻譯工作。當你需要將程式碼中的硬編碼中文（或英文）文字轉換為國際化支援時使用。

前提：以實際專案結構為準，不破壞現有專案規則。

---

核心原則

1. 以實際專案結構為準 - 不假設固定目錄結構，根據專案現有配置靈活調整
2. 配置放對應位置 - 公共翻譯放公共目錄，模組翻譯放模組目錄，不混淆
3. 優先複用現有翻譯 - 已有相同含義的翻譯時直接使用，不要重複新增
4. 只翻譯靜態文字 - 不翻譯後端介面返回的資料、字典/列舉中的內容
5. 不破壞現有規則 - 所有修改基於專案現有規則，不改變現有結構

---

工作流程

Step 1: 瞭解專案結構

首先探索專案的國際化配置：

1. 查詢語言檔案目錄（常見名稱：lang, locales, i18n, language, messages）
2. 確認目錄結構模式：
3. 有模組區分：是否存在 common/, module/, 或按模組名劃分的子目錄
4. 無模組區分：所有翻譯是否都在一個或少數幾個檔案中
5. 確認檔案命名規範（如 zh_CN.ts, zh-CN.ts, en.ts, en_US.ts 等）
6. 確認國際化呼叫方式（如 $t(), t(), useI18n() 等）
7. 確認支援的語言種類（是否只有中英文，還是支援更多語言）
8. 確認是否使用了 vue-i18n 的特殊功能（複數、插值等）

Step 2: 識別需要翻譯的內容

✅ 需要翻譯：

• 靜態顯示的中文/英文字串
• 按鈕文字、提示資訊、表單標籤
• 表格列標題、對話方塊標題
• 佔位符文字、選項文字

❌ 不需要翻譯：

• 從後端 API 返回的資料
• 字典/列舉中獲取的內容
• 變數和動態計算的值
• 數字、日期格式（需要使用專門的格式化方法）
• 技術性錯誤資訊（後端返回的 error message）

Step 3: 判斷翻譯放哪裡

根據專案實際結構判斷翻譯應該新增到哪裡：

情況A: 專案有模組區分

lang/
├── common/        # 公共翻譯
│   ├── zh.ts
│   └── en.ts
├── module/        # 模組翻譯
│   ├── product/
│   ├── order/
│   └── ...
└── index.ts

決策規則：

• 如果是通用性質的翻譯（如：新增、編輯、刪除、搜尋、重置、確定、取消、請輸入、請選擇等）→ 放 common/
• 如果是特定業務模組的翻譯（如：產品名稱、訂單狀態，品牌分類等）→ 放對應模組目錄

情況B: 專案無模組區分

lang/
├── zh_CN.ts
├── en_US.ts
└── index.ts

決策規則：

• 所有翻譯都直接新增到對應的語言檔案中
• 使用有字首的 key 區分不同模組，如 product.*, order.*, common.*

情況C: 其他結構

根據專案實際結構靈活處理：

• 可能存在多個語言檔案（按語言分、按模組分、混合分）
• 可能使用 JSON 格式或 TS 格式
• 總之遵循專案現有模式，不打破現有結構

Step 4: 新增翻譯

1. 檢查現有翻譯 - 先搜尋是否已有相同含義的翻譯，有則複用
2. 新增翻譯 key - 如果沒有，新增新的翻譯
3. 確保所有支援的語言一致 - 新增時同步新增所有支援的語言，保持 key 路徑一致

新增位置判斷：

IF 專案有 common/ 或類似的公共目錄 THEN
  IF 翻譯是通用性質的 THEN
    新增到公共目錄
  ELSE
    新增到對應模組目錄
ELSE
  新增到主語言檔案中，使用模組字首區分

Step 5: 替換硬編碼

根據專案實際的呼叫方式替換。常見使用方式如下：

<!-- Template 中使用 $t -->
{{ $t("key.path") }}

<!-- 在 script 中使用 -->
<script setup>
const { t } = useI18n();
const text = t("key.path");
</script>

<!-- 屬性繫結 -->
<el-input :placeholder="t('key.path')" />

Step 6: 檢查驗證

1. 完整性檢查：
2. 所有支援的語言翻譯都已新增

3. key 路徑在所有語言檔案中一致

4. 正確性檢查：

5. 翻譯 key 正確

6. 頁面顯示正常

7. 遺漏檢查：

8. 掃描檔案確認沒有遺漏的硬編碼
9. 檢查相似場景是否需要同樣處理

---

常見問題處理

Q1: 如何判斷是公共翻譯還是模組翻譯？

通用性質 = 任何模組都可能用到
- 操作類：新增、編輯、刪除、檢視、匯入、匯出、提交、稽核
- 提示類：確定、取消、關閉，儲存、成功、失敗
- 佔位符類：請輸入、請選擇、開始日期、結束日期
- 表格類：序號、操作、狀態

模組特有 = 只有特定模組使用
- 產品名稱、產品編碼、產品分類
- 訂單號、訂單狀態
- 客戶名稱、客戶電話

Q2: 專案沒有模組目錄怎麼辦

直接新增到主語言檔案中，使用模組字首區分：

// zh_CN.ts
export default {
  common: {
    action: { add: "新增", edit: "編輯" },
  },
  product: {
    name: "產品名稱",
    code: "產品編碼",
  },
  order: {
    no: "訂單號",
    status: "訂單狀態",
  },
};

Q3: 已有公共翻譯但想保持模組獨立性

如果業務確實需要獨立管理（如不同模組由不同人維護），可以在模組目錄中重複定義，但建議優先複用公共翻譯。

Q4: 如何處理動態引數/插值

如果翻譯中需要動態引數（如使用者名稱、數量、時間等）：

1. 在 key 中使用佔位符：

typescript // zh_CN.ts export default { deleteSuccess: "刪除成功，共 {count} 條記錄", welcome: "歡迎 {username} 登入系統", selectedCount: "已選擇 {n} 項", };

1. 在元件中傳遞引數：

```vue

{{ $t("deleteSuccess", { count: deletedCount }) }}

```

1. 注意事項：
2. 遵循專案現有的插值語法（佔位符格式可能不同，如 {count} 或 %{count}）
3. 佔位符命名應簡潔明瞭
4. 確保所有語言中佔位符名稱一致

Q5: 如何處理複數形式

如果專案使用 vue-i18n 的複數功能：

// zh_CN.ts（中文通常不需要複數變化，使用相同形式）
export default {
  itemCount: "{n} 個專案 | {n} 個專案",
};

// en_US.ts
export default {
  itemCount: "{n} item | {n} items",
};

使用方式：

{{ $t("itemCount", { n: count }, count) }}

vue-i18n 會根據 count 的值自動選擇單數或複數形式。

注意：如果專案沒有使用複數功能，將複數和單數分別定義為不同的 key，如 itemCount 和 itemCount_plural。

Q6: 如何處理日期/數字/貨幣格式化

日期、數字、貨幣通常需要專門的格式化方法，不要使用簡單的翻譯：

1. 使用專案現有的格式化方法：
2. 查詢專案中是否有現成的格式化工具

3. 如使用 dayjs, Intl.NumberFormat 等

4. 如果確實需要翻譯日期格式：

typescript // 僅翻譯格式說明文字，不翻譯實際日期 dateFormat: { year: '年', month: '月', day: '日' }

1. 數字和貨幣： typescript // 建議使用專門的格式化，不走翻譯 // 如：Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })

Q7: 如何處理 UI 框架元件的國際化

對於 Element Plus、Ant Design 等 UI 框架的元件：

1. 遵循專案配置 - 檢視專案是否已經全域性配置了框架的 i18n
2. 元件自帶屬性 - 很多元件有內建的 i18n 屬性（如 empty-text, confirm-btn-text 等）
3. 使用專案配置 - 如果專案有全域性的元件文案配置，優先使用

<!-- Element Plus 示例 -->
<el-table :data="list" :empty-text="$t('common.table.empty')">
</el-table>

Q8: 如何處理後端返回的錯誤資訊

1. 如果後端返回的是國際化 key - 直接使用，無需翻譯
2. 如果後端返回原始錯誤資訊 - 建議：
3. 在前端建立錯誤碼對映表

4. 或讓後端支援國際化 key 返回

5. 如果是業務性質的提示 - 可以翻譯： typescript // 錯誤碼對映 error: { 1001: '使用者名稱不存在', 1002: '密碼錯誤', 1003: '賬號已被鎖定' }

Q9: 專案需要支援多種語言怎麼辦

1. 確認支援的語言種類 - 檢視專案現有語言檔案
2. 所有語言同步新增 - 新增翻譯時，必須同時新增所有支援的語言
3. 遵循語言程式碼規範 - 使用專案現有的語言程式碼格式（如 zh-CN vs zh_CN）

Q10: 翻譯 key 衝突怎麼辦

1. 檢查現有 key - 確認是否真的衝突
2. 使用更具體的路徑 - 新增模組字首區分
3. 與專案成員協商 - 如果是公共 key 的修改，需溝通

Q11: 如何處理部分國際化的遺留程式碼

專案中可能存在部分已國際化但風格不一致的程式碼：

1. 保持現有風格 - 不強制統一，避免大規模改動
2. 新新增的遵循規範 - 新翻譯使用規範寫法
3. 必要時可重構 - 如果發現明顯問題，可提出建議

Q12: 舊翻譯 key 廢棄怎麼辦

1. 保留舊翻譯 - 暫時保留，避免線上報錯
2. 標記廢棄 - 添加註釋說明已廢棄
3. 後續清理 - 定期清理未使用的廢棄翻譯

Q13: 如何處理 slot 中的文字

對於 scoped slot 中的靜態文字：

<!-- 轉換前 -->
<template #default="{ row }">
  <span>產品名稱：{{ row.name }}</span>
</template>

<!-- 轉換後 -->
<template #default="{ row }">
  <span>{{ $t("product.name") }}：{{ row.name }}</span>
</template>

Q14: script 中如何使用翻譯

<script setup>
// useI18n 通常由專案自動匯入，無需手動 import
// 如專案無自動匯入，則需要：import { useI18n } from 'vue-i18n'

const { t } = useI18n();

// 在方法中使用
function handleClick() {
  const message = t("common.message.success");
  ElMessage.success(message);
}

// 在計算屬性中使用
const statusText = computed(() => {
  return t(`product.status.${status.value}`);
});
</script>

Q15: v-html 和 $t 結合使用需要注意什麼

謹慎使用 v-html：

<!-- 不推薦：可能有 XSS 風險 -->
<span v-html="$t('message.withHtml')"></span>

<!-- 推薦：分開處理 -->
<span>{{ $t('message.prefix') }}<a :href="url">{{ $t('message.link') }}</a></span>

如果必須使用 v-html，確保內容來自可信來源。

Q16: 函式式元件中如何使用翻譯

對於使用 render 函式或 JSX 的元件：

// 使用 this.$t（需要確保元件可訪問到 i18n 例項）
export default {
  render() {
    return h("span", this.$t("key.path"));
  },
};

// 或者通過 provide/inject 傳遞翻譯函式
// 父元件
const { t } = useI18n();
provide("i18n", { t });

// 子元件
const { t } = inject("i18n");
return h("span", t("key.path"));

Q17: keep-alive 快取元件翻譯切換問題

使用 keep-alive 快取的元件在切換語言後可能不會重新渲染：

1. 監聽語言變化 - 在 activated 生命週期中強制重新整理

<script setup>
import { watch } from "vue";
import { useI18n } from "vue-i18n";

const { locale } = useI18n();

// 監聽語言變化，強制重新整理
watch(locale, () => {
  // 強制元件重新渲染
  refreshData();
});
</script>

1. 使用 key 變化 - 為 keep-alive 元件新增 key

<keep-alive>
  <component :is="component" :key="locale" />
</keep-alive>

Q18: 非同步元件的翻譯載入

非同步元件的翻譯需要在主應用或單獨載入：

1. 如果專案使用全域性翻譯 - 非同步元件會自動繼承
2. 如果需要單獨載入 - 使用 vue-i18n 的懶載入功能

// 懶載入翻譯
const messages = {
  en: () => import("./locales/en.json"),
  zh: () => import("./locales/zh.json"),
};

---

翻譯準確性要求

作為經驗豐富的翻譯專家，你需要遵循以下嚴格要求：

1. 理解上下文語境

翻譯前必須理解文字的使用場景：

場景	示例	翻譯註意事項
按鈕文字	"提交"、"確認"、"取消"	簡潔有力，通常用動詞
表單標籤	"產品名稱"、"建立時間"	名詞短語，明確指示
佔位符	"請輸入名稱"、"請選擇日期"	引導性語句
提示資訊	"操作成功"、"儲存失敗"	結果導向，說明狀態
對話方塊標題	"新增產品"、"編輯品牌"	動作 + 物件
表格列	"狀態"、"建立人"、"更新時間"	簡潔名詞

2. 根據場景選擇準確翻譯

同一個中文詞在不同場景可能有不同譯法：

示例：中文 "狀態"
├── 表格列標題 → "Status"
├── 業務流程中 → "State" 或 "Process Status"
├── 裝置狀態 → "Device Status"
└── 訂單狀態 → "Order Status"

示例：中文 "確認"
├── 按鈕文字 → "Confirm" 或 "Submit"
├── 二次確認提示 → "Are you sure?"
└── 確認框標題 → "Confirmation"

示例：中文 "檢視"
├── 表格操作列 → "View"
├── 檢視詳情 → "Details"
├── 檢視記錄 → "View Record"
└── 檢視圖片 → "Preview"

3. 保持翻譯一致性

• 相同含義 → 相同翻譯：整個專案中，相同含義的文字必須使用相同的翻譯
• 相同場景 → 相同模式：類似場景使用類似的翻譯結構和用詞
• 建立術語表：對於專業術語，建立統一的翻譯標準

✅ 正確：所有"產品名稱"都翻譯為 "Product Name"
❌ 錯誤：有時翻譯為 "Product Name"，有時翻譯為 "Name"

4. 專業術語處理

• 行業標準術語：使用公認的英文術語
• 產品特定術語：保持與產品文件一致

  想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

• 縮寫和縮寫詞：如需使用縮寫，應在首次出現時提供全稱

示例：
- SKU → Stock Keeping Unit（庫存單位）
- MDM → Master Data Management（主資料管理）
- CRM → Customer Relationship Management（客戶關係管理）

5. key 命名規範

遵循專案的命名規範，專案沒有特殊規定時參考以下原則：

命名原則：
- 使用小寫字母
- 使用點分隔層級
- 保持簡潔但有意義
- 避免縮寫（除非是公認的縮寫）

層級結構建議：
- 動作相關：{模組}.action.{具體動作}
  product.action.add, product.action.edit, product.action.delete

- 欄位相關：{模組}.{實體}.{欄位名}
  product.product.name, product.product.code

- 提示相關：{模組}.message.{型別}
  product.message.success, product.message.error

- 佔位符：common.placeholder.{型別}
  common.placeholder.input, common.placeholder.select

公共部分：common.{型別}.{具體項}
  common.action.add, common.action.edit
  common.table.index, common.table.action
  common.message.success, common.message.error

6. 長度和空間考慮

• 英文翻譯通常比中文短，但也要考慮UI空間
• 避免過長的翻譯導致佈局問題
• 必要時可以使用更簡潔的表達

7. 複數和單數

• 注意英文的單複數形式
• 根據實際場景選擇單複數形式
• 如果專案使用 vue-i18n 複數功能，按規範使用

8. 大小寫規範

• 按鈕文字：首字母大寫（Save, Cancel, Confirm）
• 表格列標題：首字母大寫（Product Name, Status）
• 佔位符文字：首字母小寫（please enter, please select）
• 標題和標籤：首字母大寫
• 遵循專案現有規範

9. 標點符號

• 英文使用英文標點（, . 而不是 ，）
• 但按鈕文字、標籤等通常不加句號
• 提示資訊根據語氣決定是否加句號

---

翻譯決策流程

當遇到翻譯時，按以下流程決策：

1. 理解文字含義和用途
   ↓
2. 檢視專案現有翻譯庫
   ├── 已有相同翻譯？→ 直接複用
   └── 沒有？→ 繼續
   ↓
3. 分析使用場景
   ├── 什麼型別的UI元素？
   ├── 在什麼上下文中使用？
   └── 使用者期望什麼語氣？
   ↓
4. 選擇最準確的翻譯
   ↓
5. 判斷翻譯放哪裡
   ├── 通用性質？→ 公共目錄
   └── 模組特有？→ 模組目錄
   ↓
6. 檢查一致性
   ├── 是否與現有術語衝突？
   └── 是否需要更新術語表？

---

注意事項

1. 不修改專案結構 - 只在現有結構中新增內容，不建立新目錄（除非專案本身就需要）
2. 保持風格一致 - 使用專案現有的命名風格（camelCase, kebab-case, SCREAMING_SNAKE_CASE 等）
3. 驗證替換結果 - 修改後測試頁面顯示，確保沒有破壞現有功能
4. 公共翻譯不放模組 - 通用性質的翻譯不要放到模組目錄中
5. 模組翻譯不放公共 - 特定業務模組的翻譯不要放到公共目錄中
6. 所有語言同步 - 專案支援的所有語言都要同步更新
7. 不破壞現有 - 所有修改基於現有規則，不改變現有結構

---

驗證與錯誤處理

驗證翻譯質量

修改完成後，必須驗證：

1. 語義準確性：翻譯是否準確表達原意？
2. 場景合適性：在當前場景下是否自然？
3. 一致性檢查：類似文字是否使用類似翻譯？
4. 拼寫和語法：英文翻譯是否有拼寫錯誤或語法問題？
5. UI適配性：翻譯後是否超出UI空間？

驗證方法

1. 執行時檢查：
2. 切換語言測試頁面顯示

3. 檢查控制台是否有 missing translation 警告

4. 程式碼檢查：

5. 搜尋是否還有遺漏的硬編碼

6. 確認所有 key 都已正確新增

7. 如果專案有 lint 工具：按專案規範執行

錯誤處理

1. 翻譯錯誤：
2. 立即修正錯誤翻譯

3. 檢查是否影響其他使用該翻譯的地方

4. 遺漏翻譯：

5. 補充遺漏的翻譯

6. 檢查是否還有其他遺漏

7. 格式問題：

8. 保持與專案現有格式一致

9. 使用專案的格式化工具（如果有）

10. 如果出現問題：

11. 使用 git 回滾到修改前
12. 檢查問題原因後重新修改

這個 Skill 質量很好，內容非常全面詳細。它把國際化翻譯的各種情況都考慮到了，包括怎麼處理特殊場景、怎麼保證翻譯準確一致，實用性很強。美中不足的是對新手來說可能有點複雜，上手需要一定時間；另外缺少自動化檢測建議，目前主要靠人工檢查。總體來說這是一個專業度高、考慮周全的 Skill。