CloudCannon Documentation logo Documentation

Available with CloudCannon hosting on the Pro plan.

CloudCannon Internationalisation allows you to serve your site in different languages based on the viewers browser settings.

Tagging content for translation

First we must add a key to each element we want internationalised. To do this add a data-i18n attribute with a unique key. For example:

<h2 class="editable" data-i18n="welcome_message">Hello, welcome to my website</h2>

Obtaining the current locale

Once you have tagged the elements that need translation, CloudCannon can generate a lookup of the content. CloudCannon supports three file extensions: .json, .yml and .properties. These files are called locales.

To obtain the current locale you can visit any of these URLs on your site:

  • /cms-current-locale.properties
    welcome_message = Hello, welcome to my website
  • /cms-current-locale.json
    {"welcome_message": "Hello, welcome to my website"}
  • /cms-current-locale.yml
    welcome_message: "Hello, welcome to my website"

Providing alternative locales

Once you have the current locale you can start creating new ones. For each new locale:

  1. Create the file with your chosen format (either .yml, .json or .properties).
  2. Name that file the locale that matches it. This locale should be a in the format language[_territory]. For example, general English is en and English specific to New Zealand should be en_NZ.
  3. Use the current locale as a template and update the values for the new locale.
  4. Add each file to the _locales directory in the root of your site.

Here are some example locales:

  • /_locales/de.properties
    welcome_message = Hallo, herzlich willkommen auf meiner Website
  • /_locales/es.properties
    welcome_message = Hola, bienvenido a mi página web

CloudCannon generates a new version of the HTML per locale and route visitors based on their accept-language header and country.

Detecting the current locale

CloudCannon automatically injects the viewers locale into the HTML elements class as it is served. If a site has en_NZ support and the viewer accepts that language it looks like:

<html class="language-en_nz">

Using CSS you can alter anything from font-size to text direction:

/* Arabic */
.language-ar .content {
  direction: rtl;
}

Run some custom JavaScript based on language:

var htmlElement = document.documentElement,
  languageClass = htmlElement.className.match(/language-([^\s]+)\b/);

if (languageClass) {
  console.log(languageClass[1]); // logs your locale - check your console
} else {
  console.log("Using default locale");
}