多语言站点的一次踩坑记录：界面语言不等于文章语言

这次给站点补多语言时，最开始以为只要在 Footer 加一个语言切换器，再让 AI 翻译文章就够了。实际跑下来，问题比想象中多一些。

最核心的一点是：界面语言、主题配置语言、文章正文语言，不能混成同一个概念。

• 界面语言：导航、Footer、按钮、日期等 UI 文案。
• 主题配置语言：Hero 描述、一言、Footer 的「关于 / 更多 / 联系」等主题字段。
• 文章语言：一篇文章真实存在的正文版本。

如果只有日文界面，但文章没有日文译文，不能把它伪装成日文文章，也不能让链接直接 404。

这次遇到的问题

最开始，语言切换会把语言直接带进 URL，例如 /ja/posts/...。但一篇文章未必有对应的日文版本，于是出现了一个很割裂的体验：

1. 用户切到日文界面；
2. 点击一篇只有中文的文章；
3. 页面进入日文路由；
4. 找不到日文内容，最终 404。

另一个问题是，系统曾把文章内容自动识别为英文。这样一来，发布或通知跳转时会进入英文路径；而后台只配置了英文为翻译目标时，一篇英文原文不会再被翻译成中文，于是中文站也没有可看的版本。

繁体中文也暴露了一个典型问题：zh-TW 被错误归一成了 zh。看起来只是一个语言代码细节，结果却影响了主题配置、文章查询和 API 校验：

• theme/yohaku.zh-TW 明明存在；
• 聚合接口却去找 theme/yohaku.zh；
• Footer 因而退回简体中文；
• 后来即使前端能跳到 zh-TW，接口又因为只允许两位语言码而拒绝请求。

目前采用的方案

站点保留五种界面语言：

zh
zh-TW
en
ja
ko

后台 AI 翻译的目标语言也配置为这五种。

但它不是每篇文章都生成五份副本，而是：

目标翻译语言 = 已配置的全部语言 − 当前文章的原文语言

例如：

这样既不会重复翻译原文，也能保证每一种站点语言都有真实内容版本，避免切换后出现 404。

原文语言要由作者声明

不要再让系统根据正文自动猜测文章语言。

现在文章编辑器里应有一个「内容语言 / 原文语言」字段。作者发布时选择真实原文语言；没有特别选择时默认简体中文。

这很重要，因为原文语言会影响：

• 自动翻译时应排除哪个语言；
• 翻译任务的内容哈希；
• 后续更新文章时哪些译文需要重新生成；
• 通知、跳转和内容可用性判断。

AI 可以在翻译过程中观察语言，但不能反过来悄悄覆盖作者声明的原文语言。

主题配置也要按语言覆盖

简体中文主题配置作为基础配置即可，其他语言只维护需要翻译的字段，例如：

不需要复制颜色、布局、字体等视觉配置。这样以后改主题样式时，只改基础配置即可。

繁体中文需要使用统一的 canonical code：

不能在某些地方写 zh-TW，另一些地方又把它折叠成 zh。否则主题覆盖、文章翻译和 API 查询会各自得到不同答案。

仍然需要注意的边界

自动生成多语言译文的前提是：翻译任务最终成功。

如果某个语言的翻译失败，最好在后台任务中心可见并支持重试，而不是让前台静默出现空页面。对于已经存在的旧文章，可以在配置完成后手动发起全量翻译任务；之后文章更新保存时，系统再增量补齐过期或缺失的译文。

这次最大的收获是：多语言不是给 URL 加一个前缀，也不是简单的翻译按钮。

它需要一条清晰的契约：

只要内容、界面、主题三层使用同一套规范化语言代码，多语言体验才不会在切换时突然断掉。