Tutorial 5 Localization zh HK

教程 5 · 本地化（i18n）

🌎 語言： 繁體中文（香港） — 查看全部 33 種語言

目標： 理解 LockedIn CLI 如何支援 33 種語言，並練習指導智能體再加入一種。 本地化非常適合智能體：工作足夠機械，便於委派；同時又有測試門禁、佈局規則和語法審查等 真實約束，可以訓練你的審查能力。

← 上一章：教程 4：提示與審查 · 返回 首頁

---

這裏的“已本地化”是甚麼意思

用西班牙語、印地語、日語、簡體中文或任何內置語言執行 CLI，所有內容都會變化： 啟動畫面、幫助表、每個指令的輸出、聊天會話，甚至法律細則。不只是笑話，而是整個可見介面。

lockedin --lang zh-HK post
LOCKEDIN_LANG=hi lockedin
lockedin --lang zh aura

語言在啟動時自動偵測，優先次序如下：

1. --lang 旗標（--lang zh-HK、--lang=fr、-l ja）
2. LOCKEDIN_LANG 環境變數
3. 地區設定（LC_ALL / LC_MESSAGES / LANG，然後是作業系統 / 執行時地區設定）
4. 英語後備

normalizeLang() 通常使用地區設定的主要子標籤。因此 de-DE 選擇 de，但 tlh 不會誤選 tl；真實別名 fil 和 tgl 會映射到他加祿語 tl，挪威語 nb 和 nn 映射到 no，舊印尼語代碼 in 映射到 id，舊希伯來語代碼 iw 映射到 he。 兩個地區代碼會原樣保留，而不折疊到主要子標籤：pt-BR / pt_BR 選擇規範地區代碼， 通用 pt 保持向後兼容的巴西葡萄牙語套件（兩者共享 pools/UI）；en-SG / en_SG 保留新加坡英語，通用 en 仍為英語。香港繁體中文也是同類例外： zh-HK、zh_HK.UTF-8 和 zh-Hant-HK 選擇 zh-HK，通用 zh 與中國內地標籤 選擇簡體中文 zh。

會話中切換——/language 面板。 CLI 一直可以用 --lang 或 LOCKEDIN_LANG 以其他語言啟動，現在也能在會話途中切換。輸入 /language（別名 /lang、/languages） 會按代碼列出全部 33 種語言，並以各自文字顯示；/language el 會切換本會話餘下部分。 重點是逃生出口：切換後，面板先以新語言重繪，再用剛離開的語言輸出確切返回方法—— 當前輸入 /language en，下次執行 lockedin --lang en。這樣即使誤入 日本語 或 ಕನ್ನಡ 也不會被困住。連續切換兩次時，還會提供 LOCKEDIN_LANG 指定的語言。 --lang 和 LOCKEDIN_LANG 的行為不變。與 /a11y 一樣，它是真實工具，不是諷刺內容。

核心思想：語言套件

所有可翻譯文字都位於語言套件中，每種語言一個，結構如下：

{ meta: { lang: 'zh-HK', name: '繁體中文（香港）', dir: 'ltr' },
  pools: { HOOKS: [ /* 約 25 項 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: '黑話密度：', /* 標籤、標題 */ } }

• pools 是第 2 章介紹的內容陣列。
• ui 是介面文字：標籤、標題和小模板。

英語參考包位於 src/lockedin.js；其余 32 個模組位於 src/content/*.js： ar、bn、bo、de、el、en-SG、es、eu、fa、fi、fr、he、hi、 id、is、it、ja、kn、ms、nl、no、pl、pt、pt-BR、ru、sv、 tl、tr、uk、ur、zh 和 zh-HK（pt-BR 重用 pt 的 pools/UI，但單獨註冊）。 每個包都註冊到 BUNDLES；SUPPORTED_LANGS 由這些鍵生成，renderHelp() 輸出生成的程式碼列表， 任何 UI 包都不會硬編碼該列表。

setLang('fr');       // 讓活動語言指向法語包
// L = 活動 pools，U = 活動 ui
pick(L.HOOKS)        // 法語開場
U.buzzwordDensity    // "Densité de jargon : "

每個渲染器都讀取 L 和 U，絕不硬編碼文字，因此僅呼叫 setLang 就能切換整個體驗。

安全網：鍵一致性

加入語言之所以安全，依靠這條不變量：

每個語言套件都必須暴露與英語完全相同的 pools 和 ui 鍵。

測試會對全部 33 個語言套件強制執行。如果在英語中新增 UI 字串，卻忘記翻譯到烏克蘭語， npm test 會變紅並指出缺失鍵，因此不可能靜默交付半翻譯語言。

難點：終端機佈局

不同語言會以不同方式考驗終端機佈局：

• 日語、簡體中文和香港繁體中文使用東亞寬字元 / 全寬字元。vw() 將它們計為兩列， wrap() 會硬拆沒有空格的長標記，使 CJK 文字留在卡片和框內。
• 印地語和卡納達語使用非間距 / 包圍組合標記（Mn / Me），例如元音符號和輔音抑制符。 vw() 將其計為零列，不會虛增寬度。
• box() 會先包裝正文行再填充，因此長翻譯橫幅不會沖破邊框。
• 每個語言套件設定 sentenceEnd 和 listSep，例如 . / 。 與 , / 、， 讓生成器組合的句子自然。

新增語言時，卡片頭字串 cardSubtitle、cardMeta、cardFooter 必須保持 ≤ 60 個可見列。阿拉伯語、波斯語、希伯來語和烏爾都語設定 meta.dir: 'rtl'。 預設輸出不含雙向文字控制符，因為部分終端機會把它們顯示成方框標籤。只有明確設定 LOCKEDIN_BIDI=on，才會在換行後啟用平衡隔離符，同時保留 ANSI、ASCII 指令和邏輯復制順序。 無障礙輸出始終移除控制符。沒有明確啟用時，混合 RTL/LTR 排列可能較簡單；絕不能探測或推斷支援。

隱蔽難點：原始使用者輸入周圍的語法

一些 UI 模板會用 {cap} 等占位符插入使用者原句。不要逐槽機械翻譯；占位符可能是一整句使用者文字， 而不是整齊的名詞，最終句子仍須符合語法。

真實案例：日語模板若直接在 {cap} 後加 は，當 {cap} 是完整從句時會很別扭。 解決方案不是“更努力地直譯”，而是重構模板，例如加入名詞化結構或移動占位符，讓任意使用者輸入都適配。

✅ 和你的智能體一起試試——加入一種語言

選擇你能校對的語言，並先寫規格：

加入丹麥語（da）。 創建 src/content/da.js，作為 { meta, pools, ui } 語言套件，鍵與英語完全相同，翻譯每個條目（每個內容池約 25 項，以及全部 UI 字串）。 在 src/lockedin.js 的 BUNDLES 中註冊 da。--lang da 和 da-* 地區設定都應選中它。 卡片頭字串不得超過寬度限制。npm test 必須保持綠色，並加入與現有本地化測試相仿的 丹麥語不變量和偵測測試。

然後執行第 3–4 章的循環：

1. 先規劃。 “寫程式碼前，說明會改哪些檔案，以及怎樣保持英語鍵一致性。”
2. 測試優先。 “先加入失敗測試：da 偵測、da 鍵一致性，以及丹麥語 reflect/connect 不變量。暫時不要創建語言套件。”
3. 實作。 “把現有語言套件逐鍵翻譯為 src/content/da.js，註冊它並讓測試通過。 隨機性只能使用 pick / shuffle。”
4. 門禁與審查。 執行 npm test 和 lockedin --lang da post，再閱讀差異： 是否每個鍵都翻譯？卡片邊框是否對齊？帶 {cap} 的模板能否容納原始使用者從句？

較小的熱身練習：

• “為全部 33 個語言套件各加入一個 TAGLINE，保持數量相同。”
• “檢查卡納達語 cardFooter 是否 ≤ 60 可見列，並說明如何測量組合標記。”
• “指出刪除 ja.js 中一個 ui 鍵時會失敗的測試。”

---

接下來

• 瀏覽 src/content/es.js，它仍是創建新語言套件的友好模板。
• 重讀 docs/HANDOFF.md 中的“Adding a language”。
• 欣賞 指令參考 中的多語言笑話。

完整教程到此結束。你現在可以在測試門禁後指導 AI 智能體構建功能並進行本地化， 支援 33 種語言，也隨時可以繼續擴展。同意嗎？👇 本