Adding i18n to your site for global audiences

Last modified: June 1st, 2023

Make your website more accessible to an international audience. i18n is an abbreviation for the word internationalization. It can be broken down to the following:

  1. i (the first letter of the word)
  2. 18 characters
  3. n (the last letter of the word)

This is a form of abbreviation known as a Numeronym. Globalization (G11n) is sometimes used interchangeably with i18n.

Internationalization (i18n) on CloudCannon allows you to translate your site into different languages.

You can enable Internationalization in Site Settings / i18n.

I am an alt text

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:

  • /

    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/

    welcome_message = Hallo, herzlich willkommen auf meiner Webseite
  • /_locales/

    welcome_message = Hola, bienvenido a mi p&aacute;gina web

CloudCannon generates a new version of the HTML per locale and routes 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

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

if (languageClass) {
} else {
  console.log('Using default locale');

Related Articles

Open in a new tab