Migrate and configure Rosey

Migrating to Rosey requires you to:

• install Rosey via npm,
• rename your _locales directory,
• convert your files to .json,
• add a Rosey configuration file,
• retag all your translatable elements with data-rosey.

Once your Site builds correctly locally, you can use CloudCannon's CI/CD workflow to build your Site.

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

Open your project in your local development environment.

CloudCannon's deprecated i18n feature stores your locale files in the _locales directory. Rename this directory to rosey/locales and convert each file from the CloudCannon i18n format to JSON.

Next, you need to add the YAML configuration file rosey.yml at the root of your project. This file contains the source and tag keys.

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. CloudCannon's built-in i18n used data-i18n, and Rosey uses data-rosey.

Go through your files and retag your HTML elements, replacing data-i18n with data-rosey throughout your templates.

<h1 data-i18n="hero.heading">Welcome</h1>

<h1 data-rosey="hero.heading">Welcome</h1>

Verify your translations migrated#

After retagging, confirm your migrated locale files line up with your tagged source. Generate a fresh base locale file, then run Rosey's check command:

npx rosey generate
npx rosey check

generate writes rosey/base.json from every data-rosey tagged element in your built Site. check compares it against your rosey/locales/* files and writes a checks.json report — entries marked "missing" are tagged strings your migrated locale files don't yet cover, which usually means a key didn't line up during conversion. Resolve anything it flags before you cut over. For the full checks.json format, please read our documentation on checking for stale translations.

You can also preview your translated website locally before pushing:

npx rosey build --serve

Push your changes to your Git Repository. CloudCannon will automatically sync these changes to your connected Site.

Set up the postbuild script#

Rosey runs as a postbuild step on CloudCannon. Create a .cloudcannon/postbuild script at the root of your project 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 — this should match the source value in your rosey.yml.

Disable CloudCannon's built-in i18n#

Before disabling built-in i18n, confirm your migration is complete — rosey check reports no missing translations and your translated pages preview correctly. Until you disable it, your migration is reversible: revert your Rosey changes and your Site returns to its previous setup.

Once Rosey is running correctly, disable CloudCannon's built-in i18n on the I18n page in your Site Settings. Your Site is now configured to use Rosey for translations.

In the next step of this guide, we'll update your Collection URLs so the Visual Editor can find your pages after a Rosey build.