1. 前置条件：先配好大模型服务

AI 翻译不是开箱即用，它依赖外部大模型服务，必须先配置对应的服务地址和 API Key。没配置的话翻译任务不会真正执行。

另外注意：翻译是异步任务，不是请求内同步完成。提交后会在后台排队执行，避免长时间占用请求连接。

2. 翻译任务的五种状态

任务会记录重试次数、下次重试时间和最后的错误信息。翻译卡住时看这几个字段，比反复重提有用得多。

3. 翻译一直失败的排查顺序

1. 确认 API Key 有效且有余额。这是最常见的原因，错误信息通常在 last_error 里。
2. 确认服务器能访问大模型服务。内网隔离环境连不上，任务会一直重试直到 failed 或 expired。
3. 看重试次数。次数持续增长而状态在 retry 徘徊，基本可以确定是上游不可用，不是配置小错。
4. 看任务是否过期。expired 一般是排队太久或进程重启导致的，重新提交即可。
5. 确认内容规模。超长内容可能超出模型单次处理能力，任务会记录源内容大小，可以作为参考。

4. 为什么旧翻译结果不会盖掉新内容

这是设计上有意为之的保护：每个翻译任务都会记录源内容的哈希。如果原文在翻译过程中被修改了，已经产出的旧翻译结果不会被发布覆盖到新内容上。

实际影响：你改了原文之后，之前那个翻译任务的结果会被视为过期，需要重新翻译。这不是 bug，是防止译文与原文不一致。

5. 多语言站点的其他能力

• 繁体中文支持：内置支持，不需要额外配置。
• 多语言导航与页面语言切换：默认主题已支持，自定义主题需要自己接。
• 多语言页面内容管理：同一页面可以按语言维护不同版本。

6. 注意事项

• 不要把 API Key 写进日志或配置文件提交到仓库。生产环境尤其要管好。
• 翻译质量不等于发布质量。机翻结果建议人工过一遍再发布，尤其是产品名、专业术语和品牌词。
• 翻译消耗的是你的模型额度。批量翻译长文之前先估算成本。
• 翻译任务有租约机制。任务被某个实例领走后有租约时间，进程中途崩溃时任务不会永久卡死，但恢复会有延迟。