translate-site

使用 AI 翻译多语言网站

同一网站可以运行两套翻译系统，本技能涵盖这两套系统：

部分	包含内容	章节
Rosey 语言环境 JSON（rosey/locales/{code}.json）	共享 UI，以及任何带有 data-rosey 标记的页面文本——导航、页脚、标题、按钮、面包屑，以及（对于非拆分页面）整个页面正文	第 1 部分
内容集合文件（blog_fr/、content_fr/ 等）	每种语言环境的正文内容和 frontmatter（标题、描述、替代文本、页面构建器文本），由 SSG 按对应语言原生渲染	第 2 部分

大多数 Rosey 网站只需要第 1 部分。 只有当项目确实包含按语言环境划分的内容目录时，才使用第 2 部分：按目录拆分（make-site-multilingual 技能的第 8 阶段）或 Hugo 语言（其 Hugo 配置 A 和 B）。在 Rosey 网站上，按目录拆分的 页面 需要两者：正文来自内容集合文件（第 2 部分），共享 UI 来自语言环境 JSON（第 1 部分）。不使用 Rosey 的 Hugo 网站（配置 A）只需要第 2 部分。

本技能面向 AI 编码 Agent 编写，但适用于任何能够读取和写入 JSON 的 AI 工具。

适用场景

• 语言环境文件中存在未翻译的条目（value 仍等于 original，且该条目并非有意保留）
• 源字符串发生变化，导致现有翻译过时
• 需要从头开始批量翻译一种新语言环境
• 需要翻译按语言环境划分的内容目录（blog_fr/、blog_de/）中的正文和 frontmatter

不适用场景

• 网站尚无可翻译的目标语言——既没有 rosey/locales/，也没有按语言环境划分的内容目录。请先使用 make-site-multilingual 进行设置。
• 向构建中添加新语言环境——这属于流水线和配置变更，同样应使用 make-site-multilingual
• 翻译由人工团队或外部服务提供——本技能只涵盖使用 AI 填充文件

目录

文件	涵盖内容
SKILL.md（本文件）	适用的部分，以及文件格式为何适合 AI 翻译
locale-files.md	第 1 部分，大多数网站只需要这一部分 — rosey/locales/{code}.json
content-directories.md	第 2 部分 — 按语言环境划分的内容目录，仅适用于按目录拆分的网站
scripts/README.md	两部分共用的 prepare/merge 脚本

为什么 Rosey 文件非常适合 AI

Rosey 区域设置文件采用扁平 JSON 格式，每个条目都遵循可预测的三字段结构。这为 Agent 提供了三项特性，让翻译高效又安全：

1. 增量处理——write-locales 添加的新条目会将 value 设为源文本。比较 value 和 original，即可立即找出未翻译的内容；已翻译的条目会保持不变。无需比较差异、外部状态或跟踪数据库。
2. 确定性 / 幂等性——相同的处理流程运行两次会产生相同的输出。不会重新翻译已有内容，也可以通过 git diff 检查。
3. 上下文丰富——键名会标明文本出现的位置（nav:about、index:hero:title、blog:recent-posts），无需截图即可消除简短文本（“More”“Back”“Home”）的歧义。

数据格式本身_就是_状态管理：读取 JSON 文件，找出 value === original 的条目，翻译后写回文件。唯一的例外是有意保留为原文的条目（例如品牌名称）；merge-translation.mjs 会将这些条目记录在 rosey/translate-site-keep.json 中，以免再次提供这些条目。

经验与注意事项

本节会持续更新。翻译过程中发现新的模式、问题或改进时，请先询问用户，再将内容添加到此处。请参阅仓库 README 中的关键约定 → 持续更新的文档。