Set up Rosey

This page walks you through setting up Rosey on CloudCannon from scratch. By the end, you'll have a multilingual static site that generates locale-specific output as part of your CloudCannon build.

Install Rosey#

In your Terminal, navigate to your website project and initialize npm using the following command.

npm init

Still in your Terminal, install Rosey using the following command.

npm install rosey

Tag translatable content#

Add data-rosey attributes to the HTML elements in your site templates that you want Rosey to translate. The attribute value is a key that Rosey uses to look up the translation in your locale files. Choose key names that are descriptive and unique within your site.

Rosey can translate three types of content: text, images, and HTML attributes.

For text content, you can add data-rosey to any element to translate its inner text.

<h1 data-rosey="hero.heading">Welcome to our site</h1>
<p data-rosey="hero.subheading">We build great things.</p>

For images, you can add data-rosey to an <img> element to swap the image itself per locale.

<img data-rosey="hero.image" src="/images/hero-en.jpg" alt="A team working together" />

For HTML attributes, you can use data-rosey-attr and data-rosey-attr-value to translate attribute values such as alt text or meta descriptions.

<img src="/images/hero.jpg" alt="A team working together" data-rosey-attr="alt" data-rosey-attr-value="hero.image-alt" />
<meta name="description" content="We build great things." data-rosey-attr="content" data-rosey-attr-value="meta.description" />

Configure Rosey#

Create a rosey.yml file at the root of your project to tell Rosey where your built site lives and which attribute to look for.

source: _site
tag: data-rosey

The value of the source key tells Rosey where to find your SSG's built output. If you are using an SSG like Eleventy or Jekyll, the output will be _site (like the example above); however, you should set this to the appropriate value for your project.

The value of the tag key should match the HTML attribute on elements in your files.

Test locally#

Before adding locale files, you can verify that Rosey can read your tagged content by running a local build.

npx rosey build --serve

Rosey will build your Site and start a local server. At this stage your Site will have no translations yet, but this confirms that Rosey is reading your output directory correctly.

Generate your base locale file#

Run the rosey generate command in your Terminal to produce a base locale JSON file. Rosey scans your built Site for all data-rosey tagged elements and outputs a JSON file listing every translatable string.

npx rosey generate

This produces rosey/base.json by default. The file lists each key with its source text:

{
  "hero.heading": { "original": "Welcome to our site" },
  "hero.subheading": { "original": "We build great things." }
}

Create locale files#

Create a file in rosey/locales/ for each language you want to support. The filename should be a locale code (⁠fr.json, de.json, es.json, etc.). Copy the structure from base.json and add translated values.

{
  "hero.heading": {
    "original": "Welcome to our site",
    "value": "Bienvenue sur notre site"
  },
  "hero.subheading": {
    "original": "We build great things.",
    "value": "Nous construisons de grandes choses."
  }
}

Set up the postbuild script#

Rosey runs as a postbuild step on CloudCannon. Create a .cloudcannon/postbuild script to run Rosey after every build.

echo "Translating site with Rosey"
mv ./_site ./_untranslated_site
npx rosey build --source _untranslated_site --dest _site

Replace _site with your SSG's output directory if it differs. If your Site includes Chinese, Japanese, or Korean content, add the --wrap flag to the rosey build command for correct word-wrapping:

npx rosey build --source _untranslated_site --dest _site --wrap

Because Rosey moves your output files to language-prefixed paths, the Visual Editor needs to be configured to find your pages after a build. The next step covers how to do this.

Add locale files as a CloudCannon Collection#

To make your locale files editable in CloudCannon, add them as a Collection in your Configuration File. This lets your team open and edit individual locale files in the Data Editor.

collections_config:
  translations:
    path: rosey/locales

{
  "collections_config": {
    "translations": {
      "path": "rosey/locales"
    }
  }
}

Each locale file (⁠fr.json, de.json, etc.) will appear as a separate item in the Collection, where your team can update translation values directly in CloudCannon.

Check for stale translations#

Rosey uses the original field in each locale file to detect stale translations. When your source text changes, you can run rosey check to find any locale entries that need updating.

npx rosey check

Rosey outputs a checks.json report. Each locale gets a summary, a states count for every status — "current", "outdated", "missing", and "unused" are always reported, even when zero — and a per-key status.

{
  "de": {
    "current": false,
    "baseTotal": 2,
    "total": 2,
    "states": {
      "current": 0,
      "outdated": 1,
      "missing": 1,
      "unused": 0
    },
    "keys": {
      "hero.heading": "outdated",
      "hero.subheading": "missing"
    }
  },
  "fr": {
    "current": true,
    "baseTotal": 2,
    "total": 2,
    "states": {
      "current": 2,
      "outdated": 0,
      "missing": 0,
      "unused": 0
    },
    "keys": {
      "hero.heading": "current",
      "hero.subheading": "current"
    }
  }
}

Review this file after updating your content to see which translations need attention.

Attributes reference#

Rosey uses the following data-* attributes on your HTML elements:

<h1 data-rosey="hero.title">Welcome to our site</h1> 
<p data-rosey="hero.subtitle">We build great things.</p> 

<body data-rosey-ns="home"> 
  <h1 data-rosey="title">Home page title</h1> 
  <div data-rosey-ns="contact-info"> 
    <h2 data-rosey="title">Contact us</h2> 
  </div>
</body>

<body data-rosey-ns="home"> 
  <h1 data-rosey="title">Home page title</h1> 
  <section data-rosey-root="features"> 
    <h2 data-rosey="title">Our features</h2> 
  </section>
  <section data-rosey-root=""> 
    <p data-rosey="tagline">Built for you.</p> 
  </section>
</body>

<img src="/images/hero.jpg" alt="A team working together"
  data-rosey-attr="alt"
  data-rosey-attr-value="hero.image-alt" /> 
<meta name="description" content="We build great things."
  data-rosey-attr="content"
  data-rosey-attr-value="meta.description" /> 

In the next step of this guide, we'll look at the URL configuration options available to you — including how to update your Collection URLs so the Visual Editor can find your pages, and how to control where your default language is served.