Multi-Locales and I18N

Internationalization (I18N) is an essential requirement for many projects. Adding support for multiple regions/locales/languages to a FrontAid CMS project is thus very simple. Essentially, you will just have to add a list of locales that you want to support.

Without Localization

A basic Model without any specified locales and a single input field could look like the following example.

{
  ":name": "Example",
  "exampleText": {":type": "text"}
}

So when an editor fills out the content fields, the JSON that will be generated will look similar to the one below. It is an object containing the property exampleInput that was defined in the Model.

{
  "exampleText": "Hello World"
}

Adding Localization

In order to add localization to a project, use the :locales property and specify a list of locales. While you can use arbitrary locale names, we suggest using the format as specified in ISO/IEC 15897. Essentially, it is defined as language[_TERRITORY] and valid examples are en (general English) or en_GB (British English).

The following example shows a Model with the two locales English and German. You can add just one or as many locales as you need to support.

{
  ":name": "Example",
  ":locales": [
    "en",
    "de"
  ],
  "exampleText": {":type": "text"}
}

When filled out using FrontAid CMS, the generated JSON will look similar to the following example. As you can see, the locales are used as root properties and all their corresponding content is nested within them.

{
  "en": {
    "exampleText": "Hello World"
  },
  "de": {
    "exampleText": "Hallo Welt"
  }
}

Note that the first locale in the :locales list is considered the default locale. For example, when you open a multi-locale project in FrontAid CMS, it will use the default locale first. But then you can show and hide arbitrary locales as you wish.

Content Migration

Localization can be added to new or existing projects easily. For existing projects you should ensure to migrate the content, though. You can do that manually directly in the JSON file.

{
  "exampleText": "Hello World"
}

Given the example content structure from above, we will now migrate it. It should support the two locales en and de. As the existing content is in English, we will nest it within the en property that we specified in the Model. The German content (i.e. locale de) does not have to be prepared, it will automatically be created when the content is translated by the editor.

{
  "en": {
    "exampleText": "Hello World"
  }
}

Now save the file and commit/push it to Git. FrontAid CMS will then pick it up and use the migrated content structure for any future content changes.

If you don’t migrate the existing content when adding localization, the editor cannot use the already existing content and has to start from scratch. And the content which is stored in the JSON file will also contain dead content as can be seen in the example below. The property exampleText will not be used anymore as given the localization configuration, only en.exampleInput and de.exampleInput are relevant.

{
  "exampleText": "Hello World",
  "en": {
    "exampleText": "Hello World"
  },
  "de": {
    "exampleText": "Hallo Welt"
  }
}