Set up the Rosey CloudCannon Connector

In this part of the guide, you will install the Rosey CloudCannon Connector, modify your CloudCannon Configuration File to define a Dataset for each locale, and update your postbuild script. For more information, see the full documentation on GitHub or contact our friendly support team.

Install and initialize the Connector#

In your Terminal, install the Rosey CloudCannon Connector into your project using the following command.

npm install rosey-cloudcannon-connector

Run the init command in your terminal to install dependencies, generate the configuration required in your CloudCannon Configuration File for each locale, and create a .cloudcannon/postbuild script.

npx rosey-cloudcannon-connector init

Your terminal will present some interactive prompts to help you initialize the Connector. You can skip these prompts by passing flags to accept default configuration options. Here are some common flags that might speed up the process:

• --locales, followed by the locale codes in a comma-separated list, generates the Dataset configuration the Connector requires in your CloudCannon Configuration File.
• --collection generates the optional collections_config entry in your CloudCannon Configuration File for editing locale files in the Data Editor or Content Editor Sidebar.

npx rosey-cloudcannon-connector init --locales fr,de --collection

Locale files as Datasets

The Rosey CloudCannon Connector needs a data_config entry in your CloudCannon Configuration File for each locale. CloudCannon's data API uses these entries to read and write locale JSON files, and the Connector uses them to discover available locale data at runtime.

The init command generates these entries automatically based on the locale codes you provide with --locales, or the ones you enter at the interactive prompt. For a complete list of locale codes, please read the ISO 639 language code list on Wikipedia.

data_config:
  locales_fr:
    path: rosey/locales/fr.json
  locales_de:
    path: rosey/locales/de.json

{
  "data_config": {
    "locales_fr": {
      "path": "rosey/locales/fr.json"
    },
    "locales_de": {
      "path": "rosey/locales/de.json"
    }
  }
}

You need one entry for each locale file you want the Connector to surface in the Visual Editor. If you add a new locale later, add its data_config entry before adding the locale file to rosey/locales/.

Locale files as a Collection

Adding a Collection for your translations is optional. You might have made one earlier in this guide to edit locale files in the Data Editor, however there is some extra configuration when the Rosey CloudCannon Connector is installed.

The init command allows you to generate the optional collections_config entry in your CloudCannon Configuration File for editing locale files in the Data Editor or Visual Editor Sidebar. This is independent of the Connector — it doesn't affect how the Connector functions, but it's useful when a translation doesn't appear visually on the page (for example, alt text, meta descriptions, or other HTML attribute values that can't be clicked in the Visual Editor).

collections_config:
  translations:
    path: rosey/locales
    name: Locales
    icon: translate
    disable_add: true
    disable_add_folder: true
    disable_file_config: true
    _inputs:
      value:
        type: html
        label: Translation
        cascade: true
      original:
        hidden: true
        cascade: true
      _base_original:
        disabled: true
        cascade: true

{
  "collections_config": {
    "translations": {
      "path": "rosey/locales",
      "name": "Locales",
      "icon": "translate",
      "disable_add": true,
      "disable_add_folder": true,
      "disable_file_config": true,
      "_inputs": {
        "value": {
          "type": "html",
          "label": "Translation",
          "cascade": true
        },
        "original": {
          "hidden": true,
          "cascade": true
        },
        "_base_original": {
          "disabled": true,
          "cascade": true
        }
      }
    }
  }
}

Ensure there is an entry for each locale file you want to be able to update through the Visual Editor.

Stale translation detection#

Each locale entry stores three fields that the Rosey CloudCannon Connector and the build process use to track whether a translation is current: value (the translated text), original (the source text when the translation was last confirmed), and _base_original (the current source text from base.json, updated by write-locales on every build).

A translation is stale when original and _base_original differ. When source content changes, the next build updates _base_original to the new text while leaving original and value untouched. For example, a translator confirms a French translation when the heading reads "Welcome to Jetstream":

{
  "hero:title": {
    "original": "Welcome to Jetstream",
    "_base_original": "Welcome to Jetstream",
    "value": "Bienvenue chez Jetstream"
  }
}

After a team member updates the heading to "Welcome to Jetstream — Software for the future", the next build updates _base_original but leaves original and value unchanged:

{
  "hero:title": {
    "original": "Welcome to Jetstream",
    "_base_original": "Welcome to Jetstream — Software for the future",
    "value": "Bienvenue chez Jetstream"
  }
}

Because original and _base_original no longer match, the Connector highlights the element with an amber dashed border and increments the count badge on the locale switcher. You can resolve the stale indicator by editing the translation in the Visual Editor — the Connector automatically updates original to match _base_original on save. If the source change doesn't affect the meaning, you can mark the translation as reviewed instead, which clears the indicator without changing the translated text.

Import the Connector script#

Import the Rosey CloudCannon Connector script in your layout file so it loads when you open a page in the Visual Editor. Wrap the import in window?.inEditorMode so the script only loads in the Visual Editor:

<script>
  if (window?.inEditorMode) {
    import("rosey-cloudcannon-connector");
  }
</script>

<script type="module">
  if (window?.inEditorMode) {
    import("/node_modules/rosey-cloudcannon-connector/dist/index.mjs");
  }
</script>

Update the postbuild script#

Add the write-locales step to your .cloudcannon/postbuild script so translation changes you save in the Visual Editor are written back to your locale JSON files before Rosey runs. Your postbuild script should include these steps in order:

echo "Installing dependencies"
npm install

echo "Generating Rosey base"
npx rosey generate

echo "Writing locales"
npx rosey-cloudcannon-connector write-locales --source rosey --dest _site

echo "Translating site with Rosey"
mv ./_site ./_untranslated_site
npx rosey build --source _untranslated_site --dest _site --default-language en --default-language-at-root --exclusions "\.(html?)$"

Attributes reference#

The Connector uses the following data-rcc-* attributes to control behaviour in the Visual Editor:

<div data-rcc> 
  <nav>...</nav>
  <main>...</main>
  <footer>...</footer>
</div>

<p data-rosey="promo.code" data-rcc-ignore>SUMMER2026</p> 

<main data-rcc-exclude="de,es"> 
  ...
</main>

In the next step of this guide, we'll look at how to edit translations in the Visual Editor using the Connector.