Back to Details

make-site-multilingual

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Get a Site Ready for Rosey (+ the RCC)

让站点适配 Rosey（+ the RCC）

Step-by-step workflow for making a single-language site translatable with Rosey, and — optionally — wiring up the Rosey CloudCannon Connector (RCC) so editors can translate inline in CloudCannon's Visual Editor.
将单语言站点改造成可通过 Rosey 翻译的分步工作流，并可选择接入 Rosey CloudCannon Connector (RCC)，让编辑者能够在 CloudCannon 的 Visual Editor 中进行内联翻译。

When to use

何时使用

  • A single-language site needs to become translatable — the main workflow, setup.md
  • The site already has an i18n system (astro-i18n, next-intl, dictionaries + 
    t()
    ) that should be replaced with Rosey — migrating-from-i18n.md
  • The site runs RCC v1 and should move to v2 — rcc-v1-to-v2-upgrade.md
  • A Rosey-ready site needs the CloudCannon inline-translation layer added — setup.md § Phase 5
  • 单语言站点需要支持翻译——主要工作流：setup.md
  • 站点已有 i18n 系统（astro-i18n、next-intl、dictionaries + 
    t()
    ），需要替换为 Rosey——migrating-from-i18n.md
  • 站点正在使用 RCC v1，需要迁移至 v2——rcc-v1-to-v2-upgrade.md
  • 已经适配 Rosey 的站点需要添加 CloudCannon 内联翻译层——setup.md § Phase 5

When not to use

何时不要使用

  • Filling in translations on a site that is already Rosey-ready — that's 
    translate-site
  • General CloudCannon configuration unrelated to locales — that's 
    cloudcannon-configuration
  • Setting up editable regions themselves — that's 
    cloudcannon-visual-editing
    . This skill covers only where 
    data-rosey
    and regions interact.
  • 为已经适配 Rosey 的站点填写翻译内容——应使用 
    translate-site
  • 与 locale 无关的 CloudCannon 常规配置——应使用 
    cloudcannon-configuration
  • 设置 editable regions 本身——应使用 
    cloudcannon-visual-editing
    。本 skill 仅涵盖 
    data-rosey
    与 regions 的交互。

Contents

目录

FileCovers
SKILL.md (this file)When this skill applies, the two layers, starting point, SSG detection
setup.mdThe main workflow — nine phases, audit through locale picker, checklist
tagging.mdPhase 3 in full — every 
data-rosey
/ 
-ns
/ 
-root
authoring rule
gotchas.mdPreventative one-line rules, framework-agnostic and SSG-specific
troubleshooting.mdSymptom → cause → fix for things that build cleanly and translate wrongly
migrating-from-i18n.mdReplacing an existing i18n system, before the main workflow
rcc-v1-to-v2-upgrade.mdMoving a site from RCC v1 to v2 — an alternative to the main workflow
astro/overview.mdAstro implementations, plus the Astro i18n migration supplement
hugo/overview.mdHugo: choosing one of three setups, root derivation, setup C (Rosey only)
hugo/native-multilingual.mdHugo setup A: Hugo languages and 
i18n
tables, no Rosey
hugo/hybrid.mdHugo setup B: Hugo languages for content, Rosey for UI strings
eleventy/overview.mdEleventy implementations, incl. taxonomy scoping and link localization
scripts/fix-rosey-pages.mjsPostbuild fix for canonical and 
og:url
on Rosey-generated pages
文件涵盖内容
SKILL.md（当前文件）本 skill 的适用场景、两层架构、起点、SSG detection
setup.md主要工作流——九个阶段，涵盖从审计到 locale picker 以及 checklist
tagging.md完整 Phase 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.mdAstro 实现，以及 Astro i18n 迁移补充说明
hugo/overview.mdHugo：三种配置方案的选择、root derivation、仅使用 Rosey 的配置 C
hugo/native-multilingual.mdHugo 配置 A：Hugo languages 和 
i18n
表，不使用 Rosey
hugo/hybrid.mdHugo 配置 B：内容使用 Hugo languages，UI 字符串使用 Rosey
eleventy/overview.mdEleventy 实现，包括 taxonomy 范围限定和链接本地化
scripts/fix-rosey-pages.mjs修复 Rosey 生成页面的 canonical 和 
og:url
的 postbuild 脚本

The two layers

两层架构

Keep these separate in your head. They are installed together but do different jobs, and only the first is required.
  1. Rosey-ready (required). Rosey is an open-source, framework-agnostic tool that operates on your built HTML. You tag translatable elements with 
    data-rosey
    , and a postbuild pipeline generates a key/value file per locale (
    rosey/locales/{code}.json
    ) and builds translated copies of the site at 
    /{locale}/
    URLs. This works on any SSG with no CMS. Once a site is Rosey-ready, translations can be filled in by AI (see the 
    translate-site
     skill), by hand, or by any external service.
  2. The RCC visual-editing layer (optional). The RCC is a client-side script that bridges those locale files to CloudCannon's Visual Editor, giving editors a floating locale switcher and inline ProseMirror editors on every 
    data-rosey
    element, with stale-translation detection. It requires CloudCannon as the CMS. If the site isn't on CloudCannon, skip every RCC/CloudCannon step and translate the locale files another way.
The bulk of this skill (tagging, the pipeline, locale files) is the required Rosey layer. Steps that belong only to the optional RCC layer are marked (RCC layer).
请在概念上将二者分开。它们会一起安装，但职责不同，且只有第一层是必需的。
  1. Rosey-ready（必需）。 Rosey 是一款开源、与框架无关的工具，直接作用于构建后的 HTML。你使用 
    data-rosey
    标记可翻译元素，postbuild pipeline 会为每个 locale 生成一个 key/value 文件（
    rosey/locales/{code}.json
    ），并在 
    /{locale}/
    URL 下构建站点的翻译副本。它适用于任何 SSG，无需 CMS。站点适配 Rosey 后，可以通过 AI（参见 
    translate-site
     skill）、手动方式或任意外部服务填写翻译。
  2. RCC 可视化编辑层（可选）。 RCC 是一个客户端脚本，将这些 locale 文件桥接到 CloudCannon 的 Visual Editor，为编辑者提供浮动式 locale switcher，并在每个 
    data-rosey
    元素上提供内联 ProseMirror 编辑器，同时支持过期翻译检测。它要求以 CloudCannon 作为 CMS。如果站点未部署在 CloudCannon 上，请跳过所有 RCC/CloudCannon 步骤，改用其他方式翻译 locale 文件。
此 skill 的大部分内容（标记、pipeline、locale 文件）属于必需的 Rosey 层。仅属于可选 RCC 层的步骤会标记为 (RCC layer)。

Which starting point are you in?

当前处于哪个起点？

SituationWhere to go
Single-language site, no translation system yetStart at setup.md — the main workflow
Site already uses an i18n system (astro-i18n, next-intl, path-based routing, dictionaries + 
t()
)		Do migrating-from-i18n.md first, then setup.md
Site already uses RCC v1 (form-based YAML editing, 
generateRoseyId
, 
data-rosey-tagger
)		Follow rcc-v1-to-v2-upgrade.md instead — a distinct, self-contained path
情况应从哪里开始
单语言站点，尚无翻译系统从 setup.md 开始——主要工作流
站点已使用 i18n 系统（astro-i18n、next-intl、基于路径的路由、dictionaries + 
t()
）		先执行 migrating-from-i18n.md，再执行 setup.md
站点已使用 RCC v1（基于表单的 YAML 编辑、
generateRoseyId
、
data-rosey-tagger
）		改用 rcc-v1-to-v2-upgrade.md——这是一条独立且自包含的路径

SSG detection and framework-specific guidance

SSG detection 与框架专属指南

After auditing the site (Phase 1), identify the SSG and read the matching 
<ssg>/overview.md
for framework-specific implementation details:
SSGFile to read
Astroastro/overview.md
Hugohugo/overview.md
Eleventy (11ty)eleventy/overview.md
Hugo: read 
hugo/overview.md
before Phase 2. It asks which of three setups the site needs, and one of them (Hugo's own multilingual system) replaces the Rosey workflow entirely.
These files contain root derivation patterns, content-block namespacing examples, the array-item component rule, split-by-directory details, locale picker examples, and framework-specific gotchas. The phase docs reference them where needed.
完成站点审计（Phase 1）后，识别 SSG，并阅读对应的 
<ssg>/overview.md
，了解框架专属的实现细节：
SSG需要阅读的文件
Astroastro/overview.md
Hugohugo/overview.md
Eleventy (11ty)eleventy/overview.md
Hugo：Phase 2 前阅读 
hugo/overview.md
。 该文件要求判断站点需要三种配置中的哪一种，其中一种（Hugo 自带的多语言系统）会完全取代 Rosey 工作流。
这些文件包含 root derivation 模式、content-block 命名空间示例、数组项组件规则、按目录拆分细节、locale picker 示例，以及框架专属的 gotchas。Phase 文档会在需要时引用它们。