Adding i18n to your site for global audiences

Last modified: March 13th, 2023

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

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:

index.html
copied
<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 Webseite
    
  • /_locales/es.properties

    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:

index.html
copied
<html class="language-en_nz">

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

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

Run some custom JavaScript based on language

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

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

Related Articles

Open in a new tab