他花了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的人——作者没说什么，只是平静地记了一笔"可能也应该被归档"。开源生态的残酷浪漫，尽在不言中。
热门跟贴