make-site-multilingual

为 Rosey（及 RCC）准备网站

逐步介绍如何使用 Rosey 让单语言网站支持翻译，以及如何（可选）接入 Rosey CloudCannon Connector (RCC)，让编辑人员可以在 CloudCannon 的 Visual Editor 中直接翻译。

适用场景

• 需要让单语言网站支持翻译——主要工作流见 setup.md
• 网站已有 i18n 系统（astro-i18n、next-intl、字典 + t()），需要改用 Rosey——见 migrating-from-i18n.md
• 网站正在使用 RCC v1，需要升级到 v2——见 rcc-v1-to-v2-upgrade.md
• Rosey 就绪的网站需要添加 CloudCannon 行内翻译层——见 setup.md § Phase 5

不适用场景

• 为已经准备好使用 Rosey 的网站填写翻译——请使用 translate-site
• 配置与语言区域无关的常规 CloudCannon 设置——请使用 cloudcannon-configuration
• 设置可编辑区域本身——请使用 cloudcannon-visual-editing。本技能仅介绍 data-rosey 与区域的交互方式。

目录

文件	内容
SKILL.md（本文件）	本技能的适用场景、两层结构、起点、SSG 检测
setup.md	主要工作流——九个阶段，从审查到语言选择器，以及检查清单
tagging.md	完整介绍阶段 3——所有 data-rosey / -ns / -root 编写规则
gotchas.md	预防性单行规则，适用于各种框架和特定 SSG
troubleshooting.md	针对构建成功但翻译错误的问题，说明症状 → 原因 → 修复方法
migrating-from-i18n.md	在主要工作流开始前，替换现有 i18n 系统
rcc-v1-to-v2-upgrade.md	将网站从 RCC v1 升级到 v2——主要工作流的替代方案
astro/overview.md	Astro 实现，以及 Astro i18n 迁移补充说明
hugo/overview.md	Hugo：选择三种设置之一、根路径推导、设置 C（仅 Rosey）
hugo/native-multilingual.md	Hugo 设置 A：使用 Hugo 语言和 i18n 表，不使用 Rosey
hugo/hybrid.md	Hugo 设置 B：使用 Hugo 语言处理内容，使用 Rosey 处理 UI 字符串
eleventy/overview.md	Eleventy 实现，包括分类法范围限定和链接本地化
scripts/fix-rosey-pages.mjs	构建后修复 Rosey 生成页面的规范链接和 og:url

两个层级

请在脑中将它们区分开来。它们会一起安装，但用途不同，而且只有第一个是必需的。

1. Rosey-ready（必需）。 Rosey 是一款开源、与框架无关的工具，作用于你构建后的 HTML。你可以使用 data-rosey 标记可翻译元素，然后通过构建后处理流程为每个地区生成键值文件（rosey/locales/{code}.json），并在 /{locale}/ URL 下构建网站的翻译版本。这适用于任何无需 CMS 的 SSG。网站完成 Rosey-ready 配置后，可以通过 AI（参见 translate-site 技能）、手动方式或任何外部服务填充翻译。

2. RCC 可视化编辑层（可选）。 RCC 是一段客户端脚本，可将这些地区文件接入 CloudCannon 的 Visual Editor，为编辑人员提供浮动的地区切换器，并在每个 data-rosey 元素上提供内联 ProseMirror 编辑器，同时检测过期翻译。它需要将 CloudCannon 用作 CMS。如果网站不使用 CloudCannon，请跳过所有 RCC/CloudCannon 步骤，并通过其他方式翻译地区文件。

本技能的大部分内容（标记、处理流程、地区文件）都属于必需的 Rosey 层。仅属于可选 RCC 层的步骤会标注为 （RCC 层）。

你属于哪种起始情况？

情况	接下来阅读
单语言网站，尚未使用翻译系统	从 setup.md 开始 — 主工作流
网站已使用 i18n 系统（astro-i18n、next-intl、基于路径的路由、词典 + t()）	先阅读 migrating-from-i18n.md，然后阅读 setup.md
网站已使用 RCC v1（基于表单的 YAML 编辑、generateRoseyId、data-rosey-tagger）	改为按照 rcc-v1-to-v2-upgrade.md 操作 — 这是一条独立、完整的升级路径

SSG 检测和框架专属指南

审核网站后（第 1 阶段），请识别 SSG，并阅读相应的 <ssg>/overview.md，了解框架专属的实现细节：

SSG	要阅读的文件
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy (11ty)	eleventy/overview.md

Hugo：请在第 2 阶段前阅读 hugo/overview.md。 其中会询问网站需要以下三种配置中的哪一种，而其中一种（Hugo 自带的多语言系统）会完全取代 Rosey 工作流。

这些文件包含根目录推导模式、内容块命名空间示例、数组项组件规则、按目录拆分的详细说明、地区选择器示例，以及框架专属注意事项。阶段文档会在需要时引用这些文件。