readme-i18n

readme-i18n 技能總覽

readme-i18n 會做什麼

readme-i18n 是一個專門用來把單一 GitHub 風格 README.md 轉成可維護多語 README 組合的技能。它不是一般用途的 app 本地化工具。它的核心工作是翻譯來源 README、建立像 README.zh.md 這類同層檔案、保留 Markdown 與 repo 的運作機制，並在所有語言版本中新增或統一共用的語言切換器。

誰適合使用 readme-i18n

這個技能很適合維護者、開源貢獻者，以及處理 repository 文件的 AI 代理。因為實際需求通常不只是「翻譯文字」，而是「交付在 GitHub 上仍能正常運作的多語 README 檔案」。如果你在意 badges、連結、code fences、檔名，以及語言切換器都要維持一致，那麼 readme-i18n 會比一般翻譯提示更適合作為起點。

真正要解決的工作

大多數 README 翻譯失敗的地方不在字彙，而在結構。使用者真正需要的是一套工作流程，能夠：

• 把單一檔案當成 source-of-truth
• 讓各語言版本的章節順序保持一致
• 原樣保留 commands、paths、code 與 link 的運作方式
• 一致更新每一個語言版本
• 避免出現重複或失效的語言切換器

這就是 readme-i18n skill 的實際價值。

為什麼這個技能和一般 prompt 不一樣

最大的差異在於判斷邏輯。這個技能會告訴代理哪些內容必須精準保留、什麼情況下只問一次釐清問題、如何從現有檔案推斷慣例，以及如何就地更新 selector，而不是再新增一個。附帶的參考文件對導入尤其有幫助，因為它們能減少 selector 放置位置與可安全翻譯的 Markdown 處理方式上常見的猜測成本。

如何使用 readme-i18n 技能

readme-i18n 的安裝情境

請在你已經使用的 Skills 相容環境中，從 xixu-me/skills repository 安裝這個技能。如果你的環境支援直接從 GitHub 安裝，常見方式是：

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

如果你的環境以其他方式管理 skills，請使用 repo URL https://github.com/xixu-me/skills/tree/main/skills/readme-i18n 作為來源參考，並從 skills/readme-i18n 載入此技能。

第一次使用前建議先讀哪些檔案

對這個技能來說，最快、資訊密度最高的閱讀順序是：

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

這個順序很重要。SKILL.md 提供整體工作流程；selector reference 說明預期的區塊格式與放置位置；preservation checklist 則明確列出哪些內容必須保持不變。

readme-i18n 需要哪些輸入

當你提供以下資訊時，這個技能的效果最好：

• 來源 README 路徑，通常是 README.md
• 來源語言
• 目標語言或多個目標語言
• 術語表，或明確列出不可翻譯的詞
• 如果 repo 已有 README 在地化，請提供既有檔名慣例

如果你省略目標語言，這個技能會先檢查現有的翻譯檔、selector、檔名、issues 或 repo 慣例來判斷。若語言仍不明確，它應該只詢問一次，而不是自行捏造目標語言。

值得先知道的預設假設

在執行 readme-i18n 之前，以下文件化的預設行為很實用，也值得先了解：

• 根目錄的 README.md 會被視為 source-of-truth，除非你另有說明
• 若沒有歧義，預設來源語言為 English
• 章節順序應與來源檔保持一致
• 若 repo 已有多語命名方式，應沿用，而不是硬套新的命名規則

這些預設讓 readme-i18n 在既有 repo 中，比空白的翻譯請求更安全。

如何寫出效果更好的 readme-i18n 提示

弱的請求會像是：「把我的 README 翻成中文。」

更好的 readme-i18n usage 提示會是：

• 將 README.md 從 English 翻譯成 Simplified Chinese
• 建立 README.zh.md
• 保留 commands、paths、badge URLs、code fences 與 relative links
• 在兩個檔案頂部加入語言切換器
• heading 順序完全一致
• 不要翻譯產品名稱 AcmeCLI 或 env vars
• 如果找到既有檔名慣例，請遵循

這種更具體的描述，會直接提升輸出品質，因為它正好對應到這個技能對保留規則與 selector 的要求。

readme-i18n 的實際翻譯工作流程範例

一個實用的 readme-i18n for Translation 工作流程如下：

1. 找出 source-of-truth README。
2. 檢查是否已存在翻譯版本。
3. 偵測 repo 的檔名模式與目前使用的 selector 樣式。
4. 只翻譯人類可讀的自然語言內容。
5. 原樣保留 code、commands、URLs 與 file paths。
6. 在每個版本頂部附近新增或統一一個 selector 區塊。
7. 驗證所有檔案之間的 links、格式與一致性。

正確的心智模型不是「翻譯文字」，而是「維護一個 README 家族」。

語言切換器應該如何運作

這個技能中最有價值的支援檔案之一，就是 selector reference。它建議在每個 README 版本的頂部附近放置一個 selector 區塊，通常是在標題與 badge 區之後，並使用穩定標記：

<!-- README-I18N:START -->
<!-- README-I18N:END -->

這些標記很重要，因為未來再次執行時，就能就地更新 selector。當前語言應該被強調且不加連結；其他語言則應加上連結。各語言版本中的語言順序也應保持一致。

哪些內容必須原樣保留

preservation checklist 是這份 readme-i18n guide 中最關鍵、也最影響導入成敗的部分。實務上，以下內容不要翻譯：

• inline code
• fenced code blocks
• commands、flags、env vars、paths
• badge URLs 與 query params
• image source paths
• table structure
• raw HTML mechanics

可見的敘述文字可以翻譯，但讓 README 正常運作的機制必須保留。

readme-i18n 會尊重哪些常見 repo 慣例

如果 repo 已經使用不同於預設的命名方式，例如：

• README.md
• README.zh.md
• README.es.md

那麼這個技能應該保留既有命名方式。這對於已經有部分在地化、CI 參照，或貢獻者對檔名已有期待的 repo 特別重要。

readme-i18n 最能省下時間的情境

當下列導入阻礙出現時，這個技能的價值最高：

• 你需要維持多個已在地化的 README 檔案同步
• repo 已經有混亂或重複的語言切換器
• 過去的翻譯曾破壞 Markdown 或 links
• 你希望更新流程可重複執行，而不是每次都手動修改

如果你只是想快速私下看懂某份 README，大概翻一下即可，那這個技能可能比你實際需要的流程還重。

readme-i18n 技能 FAQ

readme-i18n 適合新手嗎？

適合，前提是你的目標明確就是 README 在地化。這個技能把任務收斂成清楚的輸入項目與保留規則，比自己摸索整套翻譯流程更容易。不過新手仍然需要檢查輸出內容，尤其是 link 目標、headings，以及 selector 是否一致。

什麼時候應該用 readme-i18n，而不是一般翻譯 prompt？

當翻譯後的 README 會正式 commit 進 repo 時，就應該使用 readme-i18n。一般 prompt 很可能翻太多、改動 code examples、破壞 badge links，或忘記處理跨檔案導覽。當你更在意輸出正確性而不是速度時，這個技能會更合適。

readme-i18n 只適用於 GitHub repositories 嗎？

它主要針對 GitHub 風格的 repository README 與 Markdown 慣例做了最佳化。在其他 Git 託管平台上也仍然可能有幫助，但它的假設最適合 README.md 為核心的開源 repo，而不是完整文件網站或產品本地化系統。

readme-i18n 能處理完整文件集嗎？

不能。這是一個以 README 為核心的工作流程。如果你需要處理網站、app 或整套文件的 i18n，readme-i18n skill 就太窄了。它最擅長的是讓單一 repository 的 landing document 與其各語言對應檔保持一致。

可以使用哪些語言？

這個技能本身不限定語言，只要你明確指定目標語言，或 repo 已經清楚表明要支援哪些語言即可。它明確避免在 repo 證據不足時，自行推測或捏造目標語言。

readme-i18n 可以更新既有的多語 README 架構嗎？

可以，而且這正是它最適合的用途之一。它的設計就是要檢查現有翻譯檔與 selector、保留命名慣例，並把既有切換器統一整理，而不是再額外加出第二套。

什麼情況下 readme-i18n 不適合？

遇到以下情況就可以跳過：

• 你只需要非正式的閱讀用翻譯
• 你的文件不在 README 裡
• 你需要針對大型文件群做術語管理
• 你的 repo 不希望在 README 檔案中放語言切換連結

這些情況下，較輕量的 prompt，或更完整的文件在地化流程，通常會更適合。

如何改進 readme-i18n 技能的使用效果

給 readme-i18n 更明確的來源限制

更好的輸入，才能得到更好的 README 版本。建議提供：

• 精確的來源檔案路徑
• 精確的目標 locale
• 明確列出永遠不要翻譯的詞
• 語言名稱偏好的自稱形式
• 現有翻譯檔是要覆寫，還是只更新

這能降低最常見的失敗模式：翻譯本身沒錯，但 repo 行為出錯。

為名稱與技術術語提供 glossary

如果你的 README 包含產品名稱、CLI commands、package names，或特定領域術語，請明確列出。readme-i18n 本來就會盡量保留字面內容，但短小的 glossary 仍能顯著提升 headings、功能描述與範例中的一致性。

明確告訴技能哪些地方不要動

提升 readme-i18n usage 品質最有效的方法之一，就是先劃清硬性邊界：

• 所有 code blocks 必須逐位元組完全一致
• 保留 relative links
• 除非有要求，否則不要重新命名檔案
• 不要更改 badge targets
• 不要重排 sections

這些指示和 preservation checklist 高度一致，能有效避免那些「看似貼心、實際有害」的改動。

commit 前先檢查 selector 的放置位置

常見的輸出問題之一，就是語言切換器放得彆扭，或重複出現。請對照 references/language-selector-reference.md 檢查產出的 selector：

• 每個檔案只存在一個 selector
• 各語言版本的放置位置一致
• 當前語言是粗體，而不是連結
• 連結正確指向實際存在的同層檔名

這是很小的一步，但回報很高。

檢查在地化 headings 與 anchors

翻譯後的 headings 可能會改變某些平台依 heading 文字自動產生 fragment IDs 的方式。這個技能會盡量保留 heading hierarchy，但你仍應在翻譯後測試內部 heading links，尤其是長篇 README 更要注意。

從來源變更重新迭代，而不是零散手改

如果你希望長期維護，應持續把 README.md 當成 source-of-truth，並在來源更新後重新執行 readme-i18n，而不是分別手動修改每個在地化檔案。這樣才能長期維持 section order、selector 內容與術語的一致性。

第一次執行後做左右對照驗證

第一次產出之後，請用 source 與 target 檔案逐項比對：

• section 數量相同
• code block 數量相同
• tables 與 list structure 相同
• images 與 badges 相同
• selector links 可正常運作

這種檢查結構的方法，比逐句重讀更快抓出結構性退化問題。

之後的 readme-i18n 執行請明講 repo 慣例

如果你的 repo 有非標準的多語模式，下一次呼叫 readme-i18n 時，請直接在 prompt 裡寫清楚。例如：

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

當 repo 慣例是被明確說出，而不是靠推斷時，這個技能會可靠得多。