我们的博客「ゆるろぐ」最近悄悄上线了英文版。本文将分享其背后的实现过程,尤其是我们如何解决“在 SSR 站点上实现多语言化,会不会导致 API 成本失控?”这一问题。
前提:使用 EmDash 作为 CMS
本博客基于 Astro 构建的 CMS EmDash 运行。在管理后台撰写文章,前端则由 Astro 进行服务端渲染(SSR)。
其直观的操作方式与 WordPress 相似,据说也被称为“WordPress 的精神继承者”。
EmDash 原生提供了“多语言内容”机制,可以为文章、页面、菜单以及分类法(分类与标签)等按语言分别创建记录。只需通过 translationOf 字段指定“这篇英文文章是该日文文章的翻译”,即可将其作为同一篇文章的其他语言版本进行处理。
从 microCMS 迁移到 EmDash + Cloudflare 的实践
说到多语言化,如果使用 SSG 其实很简单,
通常来说,如果要通过 API 自动化多语言翻译,使用 SSG(静态站点生成)会相对简单。
- 在构建时只调用一次翻译 API
- 将结果缓存为静态文件
- 之后只需提供该 HTML 即可
因此,无论文章数量增加多少,API 成本只会在每次构建时产生。频率也容易控制,缓存处理也很简单。
但是 ゆるろぐ 是 SSR。那么每次请求都要调用 API 吗?
问题就在这里。EmDash 的 CMS 页面按规范全部采用 SSR(output: "server")渲染。这不是通过静态构建预先生成页面的方式,而是每次收到请求时,都从 CMS 的 API 和数据库获取最新内容并进行渲染的机制。
那么,如果采用“显示英文页面时,实时让 Gemini 进行翻译后输出”这种朴素的实现,会怎样呢?
- 每次请求都会产生翻译 API 费用
- 延迟也会增加(需要等待 LLM 的响应)
- 同一篇文章可能每次都返回略有不同的翻译结果(缺乏可复现性)
这种做法完全行不通。即便是SSR,如果采用“每次请求都调用API”的方式,成本和用户体验都会崩溃。
解决方案:将翻译从“请求时”移至“内容创建时”
答案很简单:不在请求时进行翻译。
具体来说,我们搭建了如下的流程。
- 在EmDash的管理后台撰写并发布日文文章
- 仅运行一次翻译脚本(
scripts/translate.mjs)- 通过EmDash的API获取日文文章的Portable Text(结构化富文本)
- 提取需要翻译的文本部分,并发送至Gemini API(
gemini-3.6-flash) - 图片和Amazon商品卡片等区块不做翻译,直接原样保留
- 将翻译结果作为新的英文文章保存至EmDash的数据库
- 通过指定原始日文文章的 ID,将其链接为同一文章组的英文版本
translationOf - 内容将以草稿形式保存,审核后即可发布。
- 通过指定原始日文文章的 ID,将其链接为同一文章组的英文版本
也就是说,翻译结果不是“即时生成”的内容,而是作为“已保存在 CMS 中的另一种语言内容”来处理。
这样一来,SSR 的请求处理本身与平时的文章展示没有任何区别。只需通过 EmDash 常规的多语言查询(getEmDashEntry(..., { locale: "en" })),即可从数据库中取出已保存的英文内容。对 Gemini API 的调用仅在翻译文章时进行一次,访问时完全不会产生任何请求。
整体结构如下
翻译的执行时机 | 请求时的 API 成本 | |
|---|---|---|
SSG + 按需翻译 | 构建时 | 零成本(静态文件分发) |
SSR + 实时翻译(反面示例) | 每次请求时 | 文章数 × 访问次数,每次都会触发 😱 |
SSR + 将预翻译内容保存到数据库(本次采用的方案) | 创建内容时(仅一次) | 零 |
如果要把 SSG 中“构建时统一缓存”的思路带入 SSR 的世界,那么“将翻译完成的内容持久化保存到数据库中”就是它的替代方案,这就是这次的发现。即使是 SSR,内容本身也不需要持续动态生成,只要预先完成翻译这一“重”处理,内容分发本身就和普通 CMS 页面一样轻量。
本地与生产环境数据库不同,我多次遇到“数据怎么没了!?”的情况
这次实现中,最让人疲惫的其实是这一点。EmDash 的本地开发环境和生产环境分别使用各自独立的数据库。这说起来是理所当然的,但正因如此,我多次体验到“刚才还在的功能不见了!”的状况。
症状大致是这样
- 页头的 nav 突然变空了
- footer 中的 Categories 列表消失了
- 文章页的侧边栏小组件消失了
- 明明自己做好的本地菜单项和小组件,又恢复到了原来的样子
而且所有问题都发生在“明明刚才还正常运行”的时候,所以一开始我还怀疑是不是自己弄坏了什么,一边怀疑一边排查原因。
原因 1:将生产数据库拉取到本地的处理(pull.sh)
开发过程中,出于“也想在本地看到生产环境最新数据”的考虑,我多次运行了将生产数据库整体导入本地的脚本。这样做会导致本地数据库被生产环境的状态(即英文文章仍是草稿、或尚未发布的菜单结构)完全覆盖。
也就是说,当我想在本地确认“生产环境尚未公开的功能”时,刚执行完 pull,数据就又回到了与生产环境相同的状态,之前在本地推进的工作会暂时看不到了,这种情况确实发生过。
原因 2:每次重新登录本地管理后台时运行的“seed”处理
另一个原因是,用于重新登录本地管理后台的机制(开发用的绕过登录)会顺带每次都重新读取 seed.json(初始数据定义文件)。
这一点比较麻烦,
- 菜单项・小组件 → 会被强制覆盖为与种子数据“完全一致”(即本地手动添加的内容会被清除)
- 分类・标签等分类法 → 由于“已存在的内容会被跳过”,因此不会被清除
这是一种会因项目不同而表现各异的机制。因此就出现了“分类保留着,但菜单和小组件每次都会消失”这种看似不可思议的现象。
已采取的应对措施
要彻底消除这种双重覆盖结构(通过pull覆盖与通过种子数据覆盖)较为困难,因此作为实际可行的折中方案,
- 将
seed.json中演示用的示例内容(菜单项、小组件、分类等)全部清空 - 每次重新进入本地环境时,都通过API重新创建所需的菜单和小组件
以此方式进行了应对。这并非根治方案,只是缓解措施,但至少能够避免“被意外的演示数据覆盖”这类问题。
总结
- EmDash 原生就是一款支持按语言区域分别管理内容的多语言 CMS
- 在 SSG 中,只需“构建时翻译、再缓存”即可,但在 SSR 中,“每次都翻译”会让费用急剧增加。
- 解决方案是:不在请求时翻译,而是在内容创建时只执行一次翻译,并将结果作为普通 CMS 内容保存到数据库中。
- 所用的翻译引擎为 Gemini API(
gemini-3.6-flash)。 - 不过,在为 CMS 做多语言化时,仅仅理顺翻译流程还不够,还需要注意“本地与生产环境使用不同数据库”本身就会产生新的陷阱。
- 尤其是那种“在本地提前处理生产环境尚不存在的状态”的开发方式,很容易受到环境同步机制(pull、seed、缓存等)副作用的影响。
这次的经验教训是:只要事先掌握好“何时进行翻译”以及“环境同步何时、覆盖什么”这两个时机的设计,即使是 SSR,也能在不被运行成本和事故困扰的情况下实现多语言支持。
您的网站也来试试多语言化怎么样?
主要从事标记(Markup)工作,并使用 JavaScript、React 和 Next.js 进行前端开发。看到自己参与的网站顺利上线,我会非常开心!爱好是弹吉他。喜欢猫和烤红薯🐱🍠
Hirappi
前端工程师 / 2022年入职