他花了40%時間搭好基礎路由,卻在剩下的60%里發現:每個"解決方案"都在文檔沒寫的地方藏著代價。
這是EdgeKits.dev作者的真實經歷。從簡單的文件夾組織,到運行時翻譯數據,他走完了Astro國際化生態的完整光譜。這篇指南是他"希望當時就有"的地圖。
![]()
第一層:文件夾即方案
最樸素的起點——src/content/blog/en/和src/content/blog/es/。Astro 5-6的原生路由支持這個模式,配置幾行就能跑通。
適合內容型站點:博客、文檔、營銷頁。翻譯單位是整篇文檔,作者是內容編輯,修改頻率以周或月計。
但這里藏著第一個認知陷阱。Astro社區把"國際化"當作一個話題討論,實際上它是兩個完全獨立的問題。
內容層與界面層:被混淆的雙軌制
第一層是內容(Content):整頁的Markdown/MDX,frontmatter驅動,非技術作者維護。
第二層是界面(UI):按鈕標簽、表單占位符、驗證錯誤、Toast提示。翻譯單位是鍵值對,作者是開發者,每次發版都可能改動。
不同的翻譯單元、不同的作者、不同的節奏、不同的存儲、不同的運行時。混在一起選工具,結果就是"總感覺哪里不對"。
作者最初的方案是ui.ts字典——TypeScript文件里硬編碼鍵值對。干凈,直到它不再干凈。
第二層:打包字典的隱性成本
ui.ts是Astro官方推薦的界面翻譯方案。編譯時類型安全,IDE自動補全,對開發者友好。
但代價在部署側暴露:每次修改"立即開始"按鈕的文案,都要觸發完整構建。作者承諾自己的"精簡部署流程"逐漸臃腫。
更隱蔽的問題是運行時。這些字典被打包進服務端代碼,隨著功能迭代,業務邏輯包逐漸被翻譯代碼侵占。
第三層:Paraglide的樹木與森林
轉向Paraglide JS v2時,客戶端樹搖(tree-shaking)看起來是完美解藥——只打包當前語言需要的代碼。
但作者算了筆服務端賬:每新增一個語言區域(locale),每新增一個命名空間,翻譯代碼就往服務端包里堆一點。樹搖救不了服務端。
這是文檔不會印出來的成本結構。
第四層:生態工具的生死簿
2026年的Astro i18n生態,兩個社區方案命運分化。
astro-i18next已歸檔。astro-i18n-aut還在維護,但作者的評價很直接:"可能也應該被歸檔"。
第三方工具的維護狀態,是技術選型時容易低估的變量。
第五層:表單驗證的交叉火力
當Zod 4遇上React Hook Form,界面翻譯的復雜度再升一級。驗證錯誤信息既要符合當前語言,又要與表單狀態同步。
這不是Astro獨有的問題,但Astro的群島架構(Islands Architecture)讓 hydration 邊界處的翻譯傳遞變得微妙。
第六層:CMS引發的部署悖論
內容管理系統登場后,矛盾轉移了。營銷團隊要求"改個標題不用等發版",于是翻譯數據外遷。
但外遷帶來新張力:如果走運行時獲取,首屏延遲上升;如果走構建時拉取,又退回"每次改文案都要重構建"的老路。
作者稱之為"部署跑步機"——看似在前進,實際在原地消耗。
第七層:運行時數據,構建時代碼
最終形態:翻譯作為運行時數據,而非構建時代碼。邊緣原生鍵值存儲(Edge-Native KV)成為基礎設施假設。
這不是所有項目都需要。但作者給出了清晰的升級信號:當你的業務邏輯包開始被翻譯代碼擠壓,當CMS編輯的每一次保存都在觸發無意義的構建,當你發現自己在為"改個按鈕文案"寫CI腳本——就是時候了。
如何判斷你在哪一層
作者的建議很務實:不要為想象中的規模預設架構。從文件夾方案開始,當特定癥狀出現時再向上遷移。
每個層級都有解,每個解都有代價。文檔印的是功能列表,沒印的是成本結構。
這篇指南的價值不在于推薦某個工具,而在于建立評估框架:你的翻譯單元是什么,誰在生產它們,以什么節奏變動,最終在哪里運行。
想清楚這些,工具選擇會自己浮出水面。
至于那些還在維護astro-i18n-aut的人——作者沒說什么,只是平靜地記了一筆"可能也應該被歸檔"。開源生態的殘酷浪漫,盡在不言中。
特別聲明:以上內容(如有圖片或視頻亦包括在內)為自媒體平臺“網易號”用戶上傳并發布,本平臺僅提供信息存儲服務。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.