translate-site

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Translate a Multilingual Site with AI

使用 AI 翻译多语言站点

Two translation systems can run on the same site, and this skill covers both:

Part	What it holds	Section
Rosey locale JSON ( `rosey/locales/{code}.json` )	Shared UI and any page text tagged with `data-rosey` — nav, footer, headings, buttons, breadcrumbs, and (for non-split pages) whole page bodies	Part 1
Content collection files ( `blog_fr/` , `content_fr/` …)	Per-locale body content + frontmatter (title, description, alt text, page-builder text) that the SSG renders natively per locale	Part 2

Most Rosey sites only need Part 1. Only reach for Part 2 if the project actually has per-locale content directories: split-by-directory (the

make-site-multilingual

skill, Phase 8), or Hugo languages (its Hugo setups A and B). On a Rosey site, a split-by-directory page needs both: its body comes from a content collection file (Part 2), its shared UI from the locale JSON (Part 1). A Hugo site without Rosey (setup A) needs only Part 2.

This skill is written for AI coding agents, but the process works with any AI tool that reads and writes JSON.

同一站点可以运行两套翻译系统，本 skill 涵盖两者：

部分	包含内容	章节
Rosey locale JSON（ `rosey/locales/{code}.json` ）	共享 UI，以及任何通过 `data-rosey` 标记的页面文本——导航、页脚、标题、按钮、面包屑，以及非拆分页面的完整页面正文	第 1 部分
Content collection 文件（ `blog_fr/` 、 `content_fr/` 等）	按 locale 划分的正文内容和 frontmatter（title、description、alt text、page-builder 文本），SSG 会按 locale 原生呈现	第 2 部分

大多数 Rosey 站点只需要第 1 部分。 只有项目实际包含按 locale 划分的内容目录时，才需要第 2 部分：split-by-directory（

make-site-multilingual

skill 的第 8 阶段），或 Hugo languages（其 Hugo setup A 和 B）。在 Rosey 站点上，split-by-directory 的 page 需要两者：正文来自 content collection 文件（第 2 部分），共享 UI 来自 locale JSON（第 1 部分）。不含 Rosey 的 Hugo 站点（setup A）只需要第 2 部分。

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

When to use

使用场景

Locale files have untranslated entries (
```
value
```
still equals
```
original
```
, and the entry wasn't deliberately kept)
A source string changed and its translations are now stale
A new locale needs bulk-translating from scratch
Per-locale content directories (
```
blog_fr/
```
,
```
blog_de/
```
) need their bodies and frontmatter translated

Locale 文件包含未翻译条目（
```
value
```
仍等于
```
original
```
，且该条目并非有意保持不变）
源字符串发生变化，导致其翻译内容过期
需要从头批量翻译一个新 locale
按 locale 划分的内容目录（
```
blog_fr/
```
、
```
blog_de/
```
）需要翻译其正文和 frontmatter

When not to use

不适用场景

The site has nothing to translate into yet — no
```
rosey/locales/
```
, and no per-locale content directories. Set it up with
```
make-site-multilingual
```
first.
Adding a new locale to the build — that is a pipeline and config change, also
```
make-site-multilingual
```
Translations come from a human team or an external service — this skill only covers filling the files with AI

站点尚无可翻译的目标 locale——不存在
```
rosey/locales/
```
，也没有按 locale 划分的内容目录。请先使用
```
make-site-multilingual
```
进行配置。
向构建中添加新 locale——这属于 pipeline 和配置变更，也应使用
```
make-site-multilingual
```
。
翻译由人工团队或外部服务提供——本 skill 仅负责使用 AI 填充文件。

File	Covers
SKILL.md (this file)	Which part applies, and why the file format suits AI translation
locale-files.md	Part 1, most sites need only this — `rosey/locales/{code}.json`
content-directories.md	Part 2 — per-locale content directories, only if the site is split-by-directory
scripts/README.md	The prepare/merge scripts both parts drive

文件	涵盖内容
SKILL.md（本文件）	哪一部分适用，以及为什么这种文件格式适合 AI 翻译
locale-files.md	第 1 部分，大多数站点只需要这一部分—— `rosey/locales/{code}.json`
content-directories.md	第 2 部分——按 locale 划分的内容目录，仅适用于采用 split-by-directory 的站点
scripts/README.md	两部分都会使用的 prepare/merge 脚本

Why Rosey files are ideal for AI

为什么 Rosey 文件适合 AI 翻译

Rosey locale files are flat JSON with a predictable three-field structure per entry. That gives an agent three properties that make translation efficient and safe:

Incremental — new entries from
```
write-locales
```
have
```
value
```
set to the source original. Comparing
```
value
```
to
```
original
```
instantly identifies what's untranslated; already-translated entries are left untouched. No diffing, no external state, no tracking database.
Deterministic / idempotent — running the same pass twice produces the same output. No re-translation of existing work, reviewable
```
git diff
```
.
Context-rich — keys encode where text appears (
```
nav:about
```
,
```
index:hero:title
```
,
```
blog:recent-posts
```
), which disambiguates short strings ("More", "Back", "Home") without a screenshot.

The data format is the state management: read a JSON file, find entries where

value === original

, translate them, write the file. The one exception is an entry deliberately left the same as its original (a brand name);

merge-translation.mjs

records those in

rosey/translate-site-keep.json

so they aren't offered again.

Rosey locale 文件是扁平 JSON，每个条目都采用可预测的三字段结构。这使 Agent 具备以下三项特性，能够高效且安全地完成翻译：

增量式——
```
write-locales
```
生成的新条目会将
```
value
```
设置为源 original。比较
```
value
```
与
```
original
```
即可立即识别未翻译内容；已经翻译的条目保持不变。无需进行 diff，无需外部状态，也无需跟踪数据库。
确定性 / 幂等性——同一流程运行两次会生成相同的输出。不会重新翻译已有成果，并且可以通过
```
git diff
```
审查变更。
上下文丰富——key 会编码文本出现的位置（
```
nav:about
```
、
```
index:hero:title
```
、
```
blog:recent-posts
```
），无需截图即可区分含义相近的短字符串（“更多”、“返回”、“首页”）。

数据格式本身就是状态管理机制：读取 JSON 文件，找出

value === original

的条目，进行翻译，然后写回文件。唯一的例外是有意与 original 保持一致的条目（品牌名称）；

merge-translation.mjs

会将这些条目记录在

rosey/translate-site-keep.json

中，避免再次将其作为待翻译项提供。

Learnings and Gotchas

经验与注意事项

This section is a living document. When you discover new patterns, issues, or improvements while translating, ask the user before appending them here. See the repo README's Key conventions → Living documents.

本节是持续维护的文档。如果在翻译过程中发现新的模式、问题或改进，请在将内容追加到此节之前询问用户。请参阅仓库 README 中的 Key conventions → Living documents（关键约定 → 活文档）。