Get a Site Ready for 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.
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
When not to use
Contents
| File |
Covers |
| SKILL.md (this file) |
When this skill applies, the two layers, starting point, SSG detection |
| setup.md |
The main workflow — nine phases, audit through locale picker, checklist |
| tagging.md |
Phase 3 in full — every data-rosey / -ns / -root authoring rule |
| gotchas.md |
Preventative one-line rules, framework-agnostic and SSG-specific |
| troubleshooting.md |
Symptom → cause → fix for things that build cleanly and translate wrongly |
| migrating-from-i18n.md |
Replacing an existing i18n system, before the main workflow |
| rcc-v1-to-v2-upgrade.md |
Moving a site from RCC v1 to v2 — an alternative to the main workflow |
| astro/overview.md |
Astro implementations, plus the Astro i18n migration supplement |
| eleventy/overview.md |
Eleventy implementations, incl. taxonomy scoping and link localization |
| hugo/overview.md |
Hugo implementations (partial — see the coverage note in that file) |
The two layers
Keep these separate in your head. They are installed together but do different jobs, and only the first is required.
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.
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).
Which starting point are you in?
| Situation |
Where to go |
| Single-language site, no translation system yet |
Start 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 |
SSG detection and framework-specific guidance
After auditing the site (Phase 1), identify the SSG and read the matching <ssg>/overview.md for framework-specific implementation details:
| SSG |
File to read |
| Astro |
astro/overview.md |
| Eleventy (11ty) |
eleventy/overview.md |
| Hugo |
hugo/overview.md |
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.
1---2name: make-site-multilingual3description: Get a site ready for Rosey translation, with the CloudCannon connector (RCC) as an optional visual-editing layer. Use when the user wants to add multilingual support, internationalize a site, set up Rosey, replace an existing i18n system (astro-i18n, next-intl, path-based routing, etc.), or upgrade from RCC v1 to v2.4---56# Get a Site Ready for Rosey (+ the RCC)78Step-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.910## When to use1112- A single-language site needs to become translatable — the main workflow, [setup.md](setup.md)13- The site already has an i18n system (astro-i18n, next-intl, dictionaries + `t()`) that should be replaced with Rosey — [migrating-from-i18n.md](migrating-from-i18n.md)14- The site runs RCC v1 and should move to v2 — [rcc-v1-to-v2-upgrade.md](rcc-v1-to-v2-upgrade.md)15- A Rosey-ready site needs the CloudCannon inline-translation layer added — [setup.md § Phase 5](setup.md#phase-5-add-the-rcc--cloudcannon-layer-optional)1617## When not to use1819- **Filling in translations** on a site that is already Rosey-ready — that's [`translate-site`](../translate-site/SKILL.md)20- **General CloudCannon configuration** unrelated to locales — that's [`cloudcannon-configuration`](../cloudcannon-configuration/SKILL.md)21- **Setting up editable regions themselves** — that's [`cloudcannon-visual-editing`](../cloudcannon-visual-editing/SKILL.md). This skill covers only where `data-rosey` and regions interact.2223## Contents2425| File | Covers |26| -------------------------------------------------- | --------------------------------------------------------------------------- |27| **SKILL.md** (this file) | When this skill applies, the two layers, starting point, SSG detection |28| [setup.md](setup.md) | **The main workflow** — nine phases, audit through locale picker, checklist |29| [tagging.md](tagging.md) | **Phase 3 in full** — every `data-rosey` / `-ns` / `-root` authoring rule |30| [gotchas.md](gotchas.md) | Preventative one-line rules, framework-agnostic and SSG-specific |31| [troubleshooting.md](troubleshooting.md) | Symptom → cause → fix for things that build cleanly and translate wrongly |32| [migrating-from-i18n.md](migrating-from-i18n.md) | Replacing an existing i18n system, before the main workflow |33| [rcc-v1-to-v2-upgrade.md](rcc-v1-to-v2-upgrade.md) | Moving a site from RCC v1 to v2 — an alternative to the main workflow |34| [astro/overview.md](astro/overview.md) | Astro implementations, plus the Astro i18n migration supplement |35| [eleventy/overview.md](eleventy/overview.md) | Eleventy implementations, incl. taxonomy scoping and link localization |36| [hugo/overview.md](hugo/overview.md) | Hugo implementations (partial — see the coverage note in that file) |3738## The two layers3940Keep these separate in your head. They are installed together but do different jobs, and only the first is required.41421. **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`](../translate-site/SKILL.md) skill), by hand, or by any external service.43442. **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.4546The 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)**.4748## Which starting point are you in?4950| Situation | Where to go |51| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |52| Single-language site, no translation system yet | Start at [setup.md](setup.md) — the main workflow |53| Site already uses an i18n system (astro-i18n, next-intl, path-based routing, dictionaries + `t()`) | Do [migrating-from-i18n.md](migrating-from-i18n.md) first, then [setup.md](setup.md) |54| Site already uses **RCC v1** (form-based YAML editing, `generateRoseyId`, `data-rosey-tagger`) | Follow [rcc-v1-to-v2-upgrade.md](rcc-v1-to-v2-upgrade.md) instead — a distinct, self-contained path |5556## SSG detection and framework-specific guidance5758After auditing the site (Phase 1), identify the SSG and read the matching `<ssg>/overview.md` for framework-specific implementation details:5960| SSG | File to read |61| --------------- | ---------------------- |62| Astro | `astro/overview.md` |63| Eleventy (11ty) | `eleventy/overview.md` |64| Hugo | `hugo/overview.md` |6566These 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.
cloudcannon