跳轉到

D-20260704-02｜i18n 統一自寫 SW 與語系前綴路由接縫

2026-08-16 關聯追補：字典交付形狀已由 D-20260816-11 修訂為 lazy bundle chunks；自寫 Service Worker、install 全量 precache 與 cache-first 語意不變。

背景與驅動力

語系清單複審撈出兩處結構性矛盾：其一，程式架構/i18n.md 殘留 ngsw-config.json 孤例，但全 corpus 的 Service Worker 已是自寫模型（install／activate／fetch 分路 ＋SW_BYPASS_PATHS＋CACHE_NAME），Angular ngsw 與自寫 SW 互斥。其二，程式架構/seo.md 承諾語系化 URL（SSG 四語系 × 約 2500 路由 ＋hreflang 全覆蓋），但 SPA 路由全無前綴、語系偵測序不看 URL——SEO 登陸頁會 router 查無此路由。

考慮過的選項

  • SW 面：ngsw 與自寫 SW 互斥、無並存空間，僅有統一一途（收斂形）。
  • 前綴面：僅靠 JSON 動態切換（使用者原認知）——hreflang 需每語言獨立 URL，經釐清「前綴 ＝ 給爬蟲的門牌、非切換機制」後不成立；裁方案 A 補路由接縫（採納）。

決定

  • i18n 資源統一走自寫 SW：/assets/i18n/*.json 全語系列入 install 預快取 ＋cache-first 分路；升版失效靠 CACHE_NAME 換名；廢 ngsw 孤例。
  • 語系前綴路由接縫（方案 A）：SEO 以語系前綴路徑為爬蟲門牌；運行時剝前綴、setLang、導向無前綴路由，站內導航一律無前綴；語系偵測序首位插「URL 前綴（若有）」、detectLang 補 URL 判斷。
  • i18n 驗證基準改 zh-TW（撰寫源；原 en 基準會把新 key 反報為 zh-TW 多 key）；en 缺 key 升 error（en 是 fallback 鏈前提）。

後果與影響

SW 快取模型單一化，語系檔的離線與升版行為與全站一致；SEO 與 SPA 路由縫隙閉合、hreflang 全覆蓋目標可達成；CI 判讀方向與「zh-TW 先寫、en 必補」的撰寫流程對齊。細節權威見 語系清單.md。