Configure URLs for Rosey

When Rosey runs as a postbuild step, it moves your output files to language-prefixed paths — for example, /en/about/ instead of /about/. This affects where the Visual Editor looks for your pages, and how your visitors reach your default language. You can address these issues by updating your Collection URLs so the Visual Editor can find your pages, and by configuring Rosey's URL options to control how your default language is served.

Fix the Visual Editor preview#

Rosey moves your output files to language-prefixed paths, but CloudCannon's default Collection URL configuration doesn't account for this prefix. CloudCannon uses the output URL to match each source file to its output file — if the output URL is wrong, the webpage preview in the Visual Editor and the webpage screenshot on each File Card in the Collection Browser will both be incorrect. You can fix this by updating your Collection URLs to match Rosey's output paths.

You can update your Collection URLs either through CloudCannon or by editing your Configuration File directly.

Update Collection URLs in CloudCannon

Navigate to the relevant Collection in the Collection Browser and enable Configuration Mode using the switch on the right of the Site Header — purple Edit Configuration buttons will appear. Click Edit Advanced in the top right to open the Edit Advanced data panel. Enter your language-prefixed URL template in the URL field — for example, /en/[slug]/ — then save your Site. Repeat this process for each Collection in your Site.

Update Collection URLs in your Configuration File

To update your Collection URLs without using CloudCannon, edit the url key for each Collection in your cloudcannon.config.yml.

collections_config:
  pages:
    url: /en/[slug]/

{
  "collections_config": {
    "pages": {
      "url": "/en/[slug]/"
    }
  }
}

Add a url entry for each Collection in your Site, replacing en with your default locale code. Once you've updated the url for each Collection, the Visual Editor will load your pages correctly after every build.

Use a staging workflow instead#

If you prefer to keep your Collection URLs un-prefixed, you can use a staging workflow as an alternative — running Rosey only on your production branch and using a separate branch for content editing. See the staging workflow guide for guidance on configuring this in CloudCannon.

To restrict Rosey to your production branch, replace the postbuild script from the previous step with this version, which wraps the build in an environment variable check:

if [[ $TRANSLATE == "true" ]];
then
  echo "Translating site with Rosey"
  mv ./_site ./_untranslated_site
  npx rosey build --source _untranslated_site --dest _site
fi

Then add a TRANSLATE environment variable with the value true on your production Site in CloudCannon. You can do this in the Environment variables section under Build in your Site Settings. Leave the variable unset on your staging Site — Rosey won't run on any build where TRANSLATE is not true, which keeps the Visual Editor working correctly on your editing branch.

Keep your default language at the root path#

Rosey also gives you control over how the default language's URLs are structured. Rosey uses en as the default language unless you set a different value using the default_language key in your rosey.yml.

source: _site
tag: data-rosey
default_language: fr

By default, Rosey places your default language under a language code prefix (for example, /en/index.html⁠) and generates a redirect page at /index.html that sends visitors to the correct locale. If you'd prefer your default language to live at the root path — for example, /index.html instead of /en/index.html — you can set the default_language_at_root option in your rosey.yml.

source: _site
tag: data-rosey
default_language: en
default_language_at_root: true

If your default language isn't en, set both keys together:

source: _site
tag: data-rosey
default_language: fr
default_language_at_root: true

With your Collection URLs configured, Rosey will build and serve a localized version of each page for every locale you've set up. This completes the Rosey section of the guide — your Site now has full multilingual support.

In the next step of this guide, we'll introduce the Rosey CloudCannon Connector — an optional add-on that lets you edit translations inline in the Visual Editor.