使用 Gemini 翻译 Next.js 网站，且不破坏生产环境

如今机器翻译成本极低，花不到一杯咖啡的钱就能把整个网站翻译成十种语言。真正的难题从来不是模型本身，而是周边的琐事：弄清楚哪些内容需要翻译，在模型错误进入生产环境前将其拦截，以及避免因为改了一个错别字就花钱重新翻译 500 个页面。对于本站这样支持十种语言且每个页面均已翻译的项目，本文将详细介绍 Scribe 是如何解决上述每一个问题的。## 只翻译有变动的内容每个可翻译文档都会根据其可翻译内容生成一个哈希值，这些内容包括标记过的 frontmatter 字段和 MDX 正文。每份存储的译文都会记录生成它的哈希值。翻译任务列表非常简单，就是所有哈希值不匹配或尚未翻译的（文档，语言）组合。这样就能带来两个非常实用的特性：- 在一个文件中修复错别字，只会让所有语言版本中的这一个文档过期。- 连续运行两次 scribe translate，第二次不会执行任何多余操作。在产生任何费用之前，使用 scribe translate --dry-run 会打印出任务列表，并附带每个项目的预估 token 数和成本。举个例子，我们将同一天发布的更新汇总在变更日志中，在正式提交前，系统显示有 18 个待处理项目，预估成本仅为 0.07 美元。## 借助 Batch API 享受半价默认情况下，翻译任务通过 Gemini Batch API 运行，其输入和输出 token 的计费标准仅为交互式费率的 50%。所有请求都会提前规划并一次性提交，然后统一进行轮询。任务在提交的瞬间就会持久化保存在 SQLite 数据库中。这意味着你可以在轮询期间随时退出，之后再次运行 scribe translate 即可从上次中断的地方继续。提示词（Prompt）的结构也经过精心设计，确保英文内容在所有目标语言中形成完全相同的前缀。当一个页面被翻译成九种语言时，Gemini 隐式的上下文缓存机制会为重复的输入 token 提供折扣。针对特定语言的指令放置在提示词的末尾，这样就不会破坏共享的前缀。## 存储前验证，而非部署后模型偶尔会返回一些错误内容：无效的 MDX、幻觉产生的字段或被截断的字符串。能让我们从容应对这一切的原则很简单：未经验证的内容绝不能进入存储库。每个响应都会被解析为 MDX，并对照文档的 Zod 规范进行重新检查。响应失败只会导致该项目失败，而不会影响整个网站。在任务运行结束时，失败的项目会被重试一次，验证错误信息会反馈给模型，这通常能修复大部分问题。如果重试依然失败，系统会报告该问题并保持未翻译状态，在此期间你的构建版本将继续为该语言区域提供英文内容。## 翻译与创译的较量字面直译读起来就像说明书一样干瘪。Scribe 内置的提示词则将这项任务定位为创译（transcreation）。模型会化身为母语为目标语言的营销文案专家，为你打造本地化版本的内容。它不仅传达每一句话的真实意图，拒绝死板地照搬原文语法，还能巧妙重构文字游戏和成语，告别生硬直译，同时严格遵循目标语言的本土排版规范。你可以在配置文件中通过 translate.context（说明网站主题、需要保留英文的品牌术语）和 translate.rules（内部风格约束）来做进一步引导。如需了解完整选项，请参阅翻译指南。## 实际成本揭秘本站包含一个落地页、一个文档版块、一个变更日志，现在又新增了博客，所有内容均翻译成了九种非英语语言。从头开始完整翻译一遍只需几美元。而日常编辑后的增量运行成本更是低至几美分。多语言网站真正昂贵的成本从来不是 token，而是繁琐的协调工作。基于哈希值的过期机制彻底消除了这些不必要的协调负担。建议先阅读快速入门指南，然后一边参考 CLI 手册，一边运行你的首次翻译任务。