What is Rosey?

Rosey is an open-source internationalization (i18n) tool for static sites, developed and maintained by CloudCannon. Rosey works with any Static Site Generator (SSG) — you tag the HTML elements you want to localize with data-rosey attributes, and Rosey generates complete locale-specific versions of your Site from JSON translation files during the build process.

Rosey supports translation of:

• Text content — the inner text of any tagged HTML element
• Images — swap out images per locale using data-rosey on <img> elements
• HTML attributes — translate alt text, meta descriptions, and other attributes
• CJK languages — use the --wrap flag for correct word-wrapping in Chinese, Japanese, and Korean

For comprehensive Rosey documentation, including advanced configuration options, see rosey.app.

How Rosey works#

When you build your Site, Rosey reads your files and looks for elements tagged with the data-rosey attribute. For each tagged element, it consults locale files stored in your project (e.g., rosey/locales/ja.json⁠) for the corresponding translation and replaces that content. It then outputs a separate directory for each locale, producing complete localized versions of your Site (e.g., example.com/en/about/ and example.com/ja/about/⁠).

You start by tagging translatable elements in your site templates with data-rosey attributes. Running npx rosey generate produces a base locale JSON file listing all tagged strings. Translators then create locale files (⁠fr.json, de.json, etc.) with translated values in rosey/locales/. Finally, Rosey runs as a postbuild step on CloudCannon, generating a localized version of your Site for each locale.

Stale translation detection#

Rosey tracks when source content changes. If a tagged string changes after a locale file has been created, Rosey marks that translation as stale so translators know it needs updating. This keeps your translations in sync with your source content without manual tracking.

Testing locally#

You can test your translated Site locally before pushing to CloudCannon using npx rosey build --serve. Rosey builds your Site and starts a local server, letting you preview each locale without deploying.

How Rosey fits into CloudCannon#

After you set up Rosey, you can edit your locale files in the Data Editor, save, and see the changes on your live webpage for each localized version.

If you want to see your changes in context without saving and building your Site, you can edit each localized version of a page inline in the Visual Editor with the optional Rosey CloudCannon Connector, covered in the second section of this guide.

In the next step of this guide, we'll install Rosey and set it up on your Site from scratch.