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
- 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 wheredata-roseyand regions interact.
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 thetranslate-siteskill), 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-roseyelement, 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.