i18n 與本地化
概述
此公開收錄副本將 plugins/antigravity-awesome-skills/skills/i18n-localization 從 https://github.com/sickn33/antigravity-awesome-skills 封裝成原生的 Omni Skills 編輯格式,同時保留其原始來源。
當操作者需要保持上游工作流程、支援檔案和儲存庫上下文完整無缺,同時讓公開驗證器和私有增強器繼續正常的 downstream 流程時使用此技能。
此收錄副本保持上游檔案完整,並使用 metadata.json 中的 external_source 區塊以及 ORIGIN.md 作為審查的來源證明錨點。
i18n 與本地化 > 國際化 (i18n) 和本地化 (L10n) 最佳實務。---
未完美對應到公開標題的匯入來源區段仍保留在下方或支援檔案中。值得注意的匯入區段:1. 核心概念, 3. 實作模式, 4. 檔案結構, 6. 常見問題, 7. RTL 支援, 8. 檢查清單。
何時使用此技能
將此區段用作觸發過濾器。它應在操作者載入檔案、執行指令或開啟拉取請求之前,明確界定啟用範圍。
- 專案類型 - 需要 i18n?
- 公開網頁應用程式 - ✅ 是
- SaaS 產品 - ✅ 是
- 內部工具 - ⚠️ 可能
- 單區域應用程式 - ⚠️ 考慮未來
- 個人專案 - ❌ 選擇性
操作表
| 情況 | 從這裡開始 | 為什麼重要 |
|---|---|---|
| 首次使用 | metadata.json | 在觸碰複製的工作流程前,透過 external_source 區塊確認儲存庫、分支、提交和匯入路徑 |
| 來源證明審查 | ORIGIN.md | 為審查者提供匯入來源的純文字審計軌跡 |
| 工作流程執行 | scripts/i18n_checker.py | 從最能實際改變執行的最小複製檔案開始 |
| 支援上下文 | scripts/i18n_checker.py | 在不載入整個套件的情況下,添加下一個最相關的複製來源檔案 |
| 交接決策 | ## 相關技能 | 當任務偏離時,協助操作者切換到更強大的原生技能 |
工作流程
此工作流程同時兼顧編輯和操作目的。它讓匯入的來源對操作者保持有用,同時滿足下游增強器流程所使用的公開收錄標準。
- 確認使用者目標、匯入工作流程的範圍,以及此技能是否仍是該任務的正確路由器。
- 在載入任何複製的上游支援檔案之前,先閱讀概述和來源證明檔案。
- 僅載入能實際改變目前請求結果的參考資料、範例、提示或腳本。
- 執行上游工作流程,同時在操作筆記中明確保持來源證明和來源邊界。
- 根據上游期望及可在複製檔案中指出的證據來驗證結果。
- 當工作超出此匯入工作流程的核心範圍時,升級或交接給相關技能。
- 在合併或關閉之前,記錄使用了哪些內容、更改了哪些內容,以及審查者仍需驗證的內容。
匯入的工作流程備註
匯入:1. 核心概念
| 術語 | 含義 |
|---|---|
| i18n | 國際化 - 讓應用程式可翻譯 |
| L10n | 本地化 - 實際翻譯內容 |
| Locale | 語言 + 區域 (en-US, tr-TR) |
| RTL | 從右至左書寫的語言(阿拉伯語、希伯來語) |
範例
範例 1:直接要求上游工作流程
使用 @i18n-localization-v2 來處理 <task>。從複製的上游工作流程開始,僅載入能改變結果的檔案,並在回答中保持來源證明可見。
說明: 當操作者需要匯入的工作流程,但不需要整個儲存庫時,這是最安全的起點。
範例 2:要求進行來源驗證的審查
根據 metadata.json 和 ORIGIN.md 審查 @i18n-localization-v2,然後說明您會先載入哪些複製的上游檔案以及原因。
說明: 在需要精確、可稽核的來源選擇說明時,請在審查或疑難排解之前使用此範例。
範例 3:在執行前縮小複製的支援檔案範圍
使用 @i18n-localization-v2 處理 <task>。僅載入能改變結果的複製參考資料、範例或腳本,並在繼續之前明確命名檔案。
說明: 這使技能與漸進式揭露保持一致,而不是預設載入整個複製套件。
範例 4:建構審查者套件
使用複製的上游檔案加上來源證明來審查 @i18n-localization-v2,然後在合併前總結任何差距。
說明: 當拉取請求等待人工審查,且您想要一個可重複的稽核套件時,這非常有用。
最佳實務
將產生的公開技能視為圍繞上游儲存庫的可審查包裝層。目標是保持來源證明明確,並僅載入能實際改善執行的複製來源材料。
- 使用翻譯鍵,而非原始文字
- 按功能命名空間管理翻譯
- 支援複數形式
- 按語言環境處理日期/數字格式
- 從一開始就規劃 RTL
- 對複雜字串使用 ICU 訊息格式
- 在元件中硬編碼字串
匯入的操作備註
匯入:5. 最佳實務
要 ✅
- 使用翻譯鍵,而非原始文字
- 按功能命名空間管理翻譯
- 支援複數形式
- 按語言環境處理日期/數字格式
- 從一開始就規劃 RTL
- 對複雜字串使用 ICU 訊息格式
不要 ❌
- 在元件中硬編碼字串
- 串接已翻譯的字串
- 假設文字長度(德文長 30%)
- 忘記 RTL 版面配置
- 在同一檔案中混合語言
疑難排解
問題:操作者跳過了匯入的上下文,回答過於籠統
症狀: 結果忽略了 plugins/antigravity-awesome-skills/skills/i18n-localization 中的上游工作流程,未提及來源證明,或完全未使用任何複製的來源檔案。
解決方案: 重新開啟 metadata.json、ORIGIN.md 和最相關的複製上游檔案。先檢查 external_source 區塊,然後在繼續之前重新說明來源證明。
問題:審查時感覺匯入的工作流程不完整
症狀: 審查者可以看到產生的 SKILL.md,但無法快速判斷哪些參考資料、範例或腳本對當前任務重要。
解決方案: 指出證明您所採取路徑的確切複製參考資料、範例、腳本或資產。如果差距確實存在,請在拉取請求中記錄下來,而不是隱藏它。
問題:任務偏離到不同的專業領域
症狀: 匯入的技能從正確的地方開始,但工作變成了偵錯、架構、設計、安全性或發佈編排,這些由原生技能處理得更好。 解決方案: 使用相關技能區段刻意進行交接。保持匯入的來源證明可見,以便下一個技能繼承正確的上下文,而不是從頭開始。
相關技能
@00-andruia-consultant- 當此匯入技能建立上下文後,工作更適合由該原生專業技能處理時使用。@00-andruia-consultant-v2- 當此匯入技能建立上下文後,工作更適合由該原生專業技能處理時使用。@10-andruia-skill-smith- 當此匯入技能建立上下文後,工作更適合由該原生專業技能處理時使用。@10-andruia-skill-smith-v2- 當此匯入技能建立上下文後,工作更適合由該原生專業技能處理時使用。
其他資源
將此支援矩陣及其下方的連結檔案,作為此匯入技能的操作者套件。它們應反映真實的複製來源材料,而非一般的支架。
| 資源系列 | 提供給審查者的內容 | 範例路徑 |
|---|---|---|
references | 從上游複製的參考備註、指南或背景資料 | references/n/a |
examples | 從上游複製的實際範例或可重複使用的提示 | examples/n/a |
scripts | 改變執行或驗證的上游輔助腳本 | scripts/i18n_checker.py |
agents | 真正屬於匯入套件的路由或委派備註 | agents/n/a |
assets | 從原始套件複製的支援資產或結構描述 | assets/n/a |
匯入的參考備註
匯入: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
└── ...
匯入:6. 常見問題
| 問題 | 解決方案 |
|---|---|
| 缺少翻譯 | 回退到預設語言 |
| 硬編碼字串 | 使用 linter/checker 腳本 |
| 日期格式 | 使用 Intl.DateTimeFormat |
| 數字格式 | 使用 Intl.NumberFormat |
| 複數形式 | 使用 ICU 訊息格式 |
匯入:7. RTL 支援
/* CSS Logical Properties */
.container {
margin-inline-start: 1rem; /* Not margin-left */
padding-inline-end: 1rem; /* Not padding-right */
}
[dir="rtl"] .icon {
transform: scaleX(-1);
}
匯入:8. 檢查清單
發佈前:
- 所有面向使用者的字串都使用翻譯鍵
- 所有支援的語言都有語言環境檔案
- 日期/數字格式使用 Intl API
- 已測試 RTL 版面配置(如果適用)
- 已設定回退語言
- 元件中沒有硬編碼字串
匯入:腳本
| 腳本 | 目的 | 指令 |
|---|---|---|
scripts/i18n_checker.py | 偵測硬編碼字串與缺少的翻譯 | python scripts/i18n_checker.py <project_path> |
匯入:限制
- 僅在任務明確符合上述描述的範圍時使用此技能。
- 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
- 如果缺少所需的輸入、權限、安全邊界或成功標準,請停止並要求澄清。