給未來的 AI 代理 / 譯者：把 zh-TW 技術文章翻成
en/ja/zh-CN時，
重複踩過的坑。這份檔案記錄實際 review 出過的 bug 與判斷依據，
避免下次又用「全域 regex 批次轉換」自信地引入同一類錯誤。
ja 譯文字元錯誤：用「繁體中文 → 日文新字體」的 map，但 map 參雜了質→质、兩→两、簡→简。zh-CN 譯文殘留繁體字：prose 中漏轉，或反過來把專有名詞（書名、人名）[...]、<img alt="...">、中文成語| 系統 | 例：「質」 | 例：「兩/两」 | 例：「簡/简」 |
|---|---|---|---|
| 繁體中文（zh-TW 原文） | 質 | 兩 | 簡 |
| 簡體中文（zh-CN 目標） | 质 | 两 | 简 |
| 日文新字體（ja 目標） | 質（不簡化） | 両 | 簡（不簡化） |
關鍵陷阱：「日文新字體 ≠ 簡體中文」。有些字日文有簡化（學→学、氣→気），
但很多字日文不簡化（質、簡、繁、長、高、骨、鬼、門、開、間、問、決、飯、館、飲、馬、機、橋、樹...）。
直接套「繁→簡」的 map 會把這些字轉成簡體中文，在日文裡是錯字。
不要自己心算、不要從記憶拼湊 map。唯一可信的來源是「常用漢字新舊字體對照表」：
學→学 氣→気 數→数 殘→残 體→体 兩→両（注意是 両 不是 两）變→変 經→経 傳→伝 寫→写 廣→広 樣→様 點→点 發→発 覺→覚營→営 燒→焼 醫→医 鐵→鉄 聲→声 賣→売 畫→画 帶→帯 專→専號→号 觀→観 說→説 讀→読 續→続 關→関 餘→余 與→与 嚴→厳靈→霊 靜→静 顯→顕 驗→験 髮→髪 鬥→闘 攝→摂 釋→釈 錢→銭綠→緑 緣→縁 繼→継 舉→挙 舊→旧 處→処 蟲→虫 雙→双 雜→雑齒→歯 澤→沢 濟→済 壓→圧 鹽→塩 腦→脳 膽→胆 臟→臓 廳→庁產→産 權→権 歸→帰 歷→歴 淺→浅 淚→涙 團→団 圓→円 圖→図擇→択 據→拠 收→収 齡→齢 恆→恒 惡→悪 惱→悩 懷→懐 戀→恋戰→戦 戲→戯 戶→戸 拜→拝 單→単 譯→訳 讓→譲 豐→豊 邊→辺閱→閲 狀→状 獨→独 效→効 區→区 國→国 會→会 當→当 實→実參→参 險→険 擔→担 來→来 屢→屡
| 錯誤轉換 | 為什麼錯 | 正確 |
|---|---|---|
質→质 | 质 是簡體中文，日文用 質 | 保持 質 |
兩→两 | 两 是簡體中文，日文新字體是 両 | 兩→両 |
簡→简 | 简 是簡體中文，日文用 簡 | 保持 簡 |
繁→繁 | （這條沒錯，但常被誤列為需轉換） | 保持 繁 |
官方對照表的「舊字體」欄用的是日本舊字體，跟繁體中文字形可能不同：
舉 vs 日舊 擧 → 日新 挙雞 vs 日舊 鷄 → 日新 鶏豬 vs 日舊 猪 → 日新 猪鬥 vs 日舊 鬪 → 日新 闘所以「繁中 舉 → 日新 挙」仍是對的（不管舊字長怎樣，新字就是 挙）。
判斷對錯只看目標新字是否為合法日文新字體，不要看「舊字欄有沒有列繁中字形」。
症狀清單（review 多次抓到）：
當然→当然 轉了，但隔壁 未來、本當、來年、配當、行き來たり 沒轉。因為 map 裡有 當 但沒有 來。人月神話、無瑕的程式碼）、Huli 文章標題、輕鬆學會嘸蝦米、簡碼/最簡碼）被轉成不正確的字形。每次 review 後「補一條規則」，map 越長越不可靠。正確做法：
1. 從官方對照表匯入完整 trad→jp map（一次）
2. 用 grep / lint 找出所有 proper noun（書名清單、人名、產品名）→ 加入保留清單
3. 批次轉換 prose（跳過 code block、inline code、markdown 連結 [text]、img alt）
4. 轉完後用「目標字是否在官方新字體集合」反查，挑出非法轉換
5. 人工抽檢（特別是成語、網路用語、動詞搭配）
zh-CN 譯文的繁簡陷阱常見漏網：常態分配（應 常态分配）、這里（混用，應 这里）、知识點（應 知识点）、樣子（應 样子）。
人月神話、無瑕的程式碼、提升程式設計師的面試力 等程式自學十年心得、前端引路人計畫 等。輕鬆學會嘸蝦米（官網頁面名）、簡碼/最簡碼（輸入法術語）。reviewer 對書名「簡繁混雜」的立場是「partially acceptable as proper nouns」——
因為這就是台灣書名原貌。
02-framework、04-cli、05-p5-js、10-one-year 等 code block 內的繁體中文
註解（如 // 或是已經沒這麼潮的寫法、timeline block），按 AGENTS.md rule 2
完全保留，不要轉。
[text](url)[Warp 支援的指令]、[筆者的推薦連結] 這類連結文字是 prose，要翻。
但外部文章標題（[簡易 Regular Expression 入門指南 - Huli]）是該文章的
真實標題，保留原文較準確（reviewer 也標 debatable）。
<img alt="...">alt 是圖片無法載入時的替代文字 + 螢幕閱讀器朗讀內容，屬於人類可讀文字，要翻。
alt="圖 1" → en: Image 1 / ja: 図 1 / zh-CN: 图 1alt="嘸蝦米 demo" → en: Boshiamy demo / ja: 嘸蝦米 デモ嘸蝦米 是輸入法專有名詞，三語都保留）| 原文 | 直譯（錯） | 建議 |
|---|---|---|
香（網路用語「很棒/羨慕」） | 香る（日文是「飄香」，意思完全不同） | 意譯，如 魅力的な |
煩瑣 | 麗麗（不是日文詞） | 煩雑 / 複雑 / ややこしい |
履試不爽（每次都這樣） | 屢試不爽（中文成語直接搬） | 毎回確実に |
拼事業的心態 | 事業を拼っているマインド（拼 不是日文動詞） | 事業に打ち込むというマインド |
免費 | 免費（中文寫法） | 無料（日文自然說法） |
述語動詞直接連名詞（事業に打ち込むマインド）聽起來卡，
用 〜というマインド（那樣的心態）或 〜しているマインド 更自然。
fenced code block（```）和 inline code（`` ）內容一字不動：
// 或是已經沒這麼潮的寫法）保留2021/04 （MTR05） 開始全職學習）保留Spance 應為 Space）在 inline code 內也保留——除非使用者明確要求修Rasycast（prose 中的錯字，應 Raycast）要修，並同步所有譯文。
判斷準則：在 backtick 內 → 保留；在散文中 → 修。
08-vue-composition-api-and-react-hook、11-vim-for-beginners 原文是全英文
（作者當年練習英文寫作）。處理方式（需與 maintainer 確認）：
.md 重命名為 .en.md（作為 en 譯文）.md（zh-TW 原文，把英文翻成繁中）ja、zh-CN 譯文07-could-i-be-a-mentor-enough.md 原文 date: 2022-06-31 是無效日曆日期
（6 月只有 30 天）。守門腳本會擋下。需改成 2022-06-30（與 maintainer 確認）。
每次 review 都抓到「上一輪引入的新 bug」。根因是：
□ 對每個轉過的字，反查官方新字體表，確認目標字合法
□ grep 確認保留清單裡的 proper noun 沒被動到
□ grep 確認 code block 內容與原文逐字一致
□ 抽檢 3-5 段 prose，確認段落內用字一致（沒有「隔壁字沒轉」的矛盾）
□ check-translations.js --all 通過
供未來 reference，這些是 commit ddcc906 實際引入、被 review 抓到的問題：
質→质 共 10 處（質 是日文，质 是簡體中文）：01-article.ja.md:142、02-framework.ja.md:30,78、04-cli.ja.md:50、09-how-to-speed-up-typing.ja.md:91、10-one-year...:230、13-boshiamy.ja.md:30、14-2023-wrapped.ja.md:36、15-raycast-101.ja.md:210,212兩→两 共 3 處（两 是簡體，日文新字體是 両）：14-2023-wrapped.ja.md:94,96、15-raycast-101.ja.md:4314-2023-wrapped.ja.md:68,263保險科技會社 → 保険科技会社），與 commit message 矛盾來 大量未轉（來→来 是日文新字體最常見轉換，map 完全漏掉）：14-2023-wrapped.ja.md:50,88,90,92,104,160,213 等香るエンジニア（L66）— 香 是網路用語，香る 是飄香，需意譯設定が麗麗しすぎる（L149）— 麗麗 不是日文詞，應 煩雑屢試不爽（L108）— 中文成語直接搬，應意譯 毎回確実に事業に打ち込むマインド（L219,223）— 連體修飾卡，事業に打ち込むというマインド簡→簡 51 處還原（前一輪錯誤轉成 简，這輪 revert）免費→無料（14、13）擔當→担当、實戰→実戦、會社→会社、參考→参考簡碼/最簡碼 還原為品牌詞嘸蝦米 demo alt 翻譯