Multi-Language Content

The world is becoming more and more globalised and for many projects supporting just a single language is no longer viable. Despite that, managing multi-language content effectively remains a challenge to this day. Mattrbld comes with some built-in features to hopefully make this experience more enjoyable and less error prone for you and your collaborators.

In this article, you’ll learn how to set up Mattrbld to deal with multi-language content and what features are at your disposal to reduce complexity.

Internationalisation Concepts

Tackling multi-language content is usually done in one of two ways: either by creating individual files for each language, or by consolidating all the language variations of a piece of content within a single file. Both approaches are viable options and both can be achieved in Mattrbld, although Mattrbld is optimised for the latter for a couple of reasons:

• Keeping all languages in one file reduces redundancies for non-translated properties and ensures that nothing can be missed, reducing the risk of errors

• Having a single source of truth is beneficial when implementing internationalisation on the frontend, as switching between languages becomes as easy as changing one look-up variable

• Content Editors and translators are able to see the other languages right in the editing interface to have a better foundation for their translations

Implementation Details

When a field in a Schema is marked as “localised”, it stores an object instead of a simple value. This object contains properties where the key corresponds to a language code and the value is the actual value of the field for that language.

Most, but not all fields can be localised. Notable exceptions are fields that have no content, such as visual-only fields, as well as Field Group, Rows and Columns fields, since they represent data structures, not actual content. If you would like to localise these fields, simply enable localisation for the fields they contain.

Example

An Unformatted Text field with the key title would output the following if not localised:

{
  "title": "value"
}

If localisation was enabled, however, the output would change to the following, supposing de-DE and en-GB were enabled as languages for this piece of content:

{
  "title": {
    "de-DE": "wert",
    "en-GB": "value"
  }
}

This way your frontend code could simply look up the English value using title['en-GB'], and the German value using title['de-DE']. This can be made even more dynamic by using the current locale as a variable:

// Simple example for brevity
function getLocalisedValue(content, key, locale) {
  if (content[key]) return content[key][locale];
  else throw new Error(`${key} could not be found in content`);
}

const content = {
  title: {
    'de-DE': 'wert',
    'en-GB': 'value',
  },
};

getLocalisedValule(content, 'title', 'en-GB'); // → 'value'
getLocalisedValule(content, 'title', 'de-DE'); // → 'wert'

For advanced use cases with nested data structures, it might be advisable to write a recursive function that transforms a piece of localised content into a plain content structure based on a locale, i.e. turning title back into a simple value instead of an object.

Effects for Content Editors

When editing multi-language content, localised fields in the editing UI will be displayed similar to Field Group fields if more than one language is enabled for the content item being edited. Clicking on them will show one field for each available locale. For example, the localised Unformatted Text field from the example above would display one text input for the “de-DE” locale and a different one for the “en-GB” locale, allowing Content Editors to see both the German and the English content at the same time, making it easy to determine and validate what content is still missing, as well as providing a context for translators.

Enabling Internationalisation

You can enable internationalisation from the General Settings tab in the project settings. This will then add your current locale to the input below, where you can proceed to add more locales as you see fit. These will be used as the keys in localised properties, so you are not restricted to actual locale codes. de, en-GB, and klingon are all valid options.

For every locale you define you are also able to set a set of typographic quotation marks, which will be used in Rich Text fields for that locale when the “smartquotes” option is active. If none is defined, it will fall back to English style quotes, if one is defined it will be used as a default.

Once enabled, fields that support being localised will have an additional toggle to activate that feature in Schemas. It is done on a per-field basis so you can keep fields that are the same in every locale simple.

By default, all localised fields display input options for all the locales defined in the Internationalisation Options. You can overwrite this on a per-content-item basis by including a Content Languages field, where Content Editors will be able to select for which locales the content item should be available for.

Dealing with Pre-Existing Content

You can en- and disable internationalisation at any point in your project, however be aware that Mattrbld will not touch existing content items when the option is enabled or disabled. Only once you open a content item and make some changes will the properties be converted to and from simple values to objects.

Non-Localised to Localised

When converting a non-localised property into a localised property, the current value will be set as the value of the first locale in the order defined in the project settings.

For example turning this:

{
  "title": "value"
}

into this:

{
  "title": {
    "de-DE": "value",
    "en-GB": null
  }
}

Localised to Non-Localised

When converting a localised property back into a non-localised property, the current value will be set to the value of the first locale in the order defined in the project settings. The other values will be discarded.

For example turning this:

{
  "title": {
    "de-DE": "wert",
    "en-GB": "value"
  }
}

into this:

{
  "title": "wert"
}

Translating the Mattrbld UI

At the moment, the Mattrbld UI is available only in English and no groundwork has been laid so far to make it easily translatable. Currently the focus is on missing features and polishing the existing ones. Multi-language support for the Mattrbld UI may be considered at a future point in time.

Closing Words

Multi-language content is a reality and Mattrbld wants to acknowledge that by making creating and editing such content as intuitive as possible. Despite that, Mattrbld’s approach is very opinionated in this regard, so keep in mind that there should be enough flexibility for you to implement your own approach to internationalised content in case the available concept is not the right one for you.

This article concludes the section on Data Modelling. The next series of articles will focus on the content editing experience and give a more detailed overview and insight for less technologically adept users, as well as discuss how to actually create and manage content with Mattrbld.