Internationalization

The Frontastic Catwalk inherently knows about internationalization. The locale of the consumer browsing the page is available, the configuration of the project (locales configured for the project and the default locale) as well as translatable data.

We support multi-language and multi-region setups which can be done in different ways depending on your requirements.

There are generally three things which can be translated or adapted to the target regions by other means:

Not only can each Frontastic Project can be multi-lingual and multi-region, but you can also have a dedicated Frontastic Project by region or language. 

We can identify languages and regions by their locale. For example, en_GB would stand for English - Great Britain. This is especially important for slight variations in languages, like the difference between English in Great Britain and the USA, but also for countries using multiple languages, like Switzerland (de_CH for German, fr_CH for French and it_CH for Italian).

Frontastic Page Structure and Data

The simplest way to set up Internationalization in Frontastic is just a single language per project. If you'd like to do this, just tell us to create multiple projects, with one language each. 

These projects can share data using the (optionally partial) inter-project synchronization mechanism Frontastic Supports. This synchronization mechanism allows Frontastic to specify which data sets are synchronized. A common case, for example, is to synchronize Nodes and Tastics, while not synchronizing Pages. Which means that the general navigation tree is the same for all languages, but you can create entirely different Pages. When not synchronizing Nodes even the structure can be vastly different between those projects, of course.

The other way to do this is to use a single Project with multiple languages. This way, the structure and Pages are shared across all languages. You can still overwrite Pages for a certain language or locale, for example to show different start pages to customers from Germany. You would also need to define a default language.

Both mechanisms can be combined:

  • English Website (en_GB)
  • Swiss Website (de_CHfr_CHit_CH) with the same node tree as the English website, but different Pages

If a single Project defines multiple locales all contents of fields configured as translatable can be translated in Backstage by Frontend Managers.

Data From External APIs

The Catwalk always determines the locale of the user based on the locale configured for the current project and the accept header sent by the users browser. For all subsequent requests this locale will be used, except if the user choose a different locale manually. This mechanism can be changed and extended. So, we always know which locale the current user uses.

The users current locale is passed to all API requests (ProductAPI, ContentAPI, …) and those APIs can modify queries based on that and should only return data in the current users locale.

Some APIs need even more information than language and region in the locale, which is supported by Frontastic. The system is also currency aware, which is especially important for commerce APIs, so you could use  en_GB@EUR to use Euro instead of Pounds when shopping even in Great Britain.

If there's some additional logic wanted like a fallback from  de_AT and de_DE to just de (because you don't want to maintain dedicated product descriptions in Austrian German and German) this logic has to be implemented either in the API itself or inside the mapping in the API abstraction in Frontastic.

User Interface Strings (aka Internationalization of Tastics)

Making Tastic Data Translatable

To set a Tastic field to be translatable, you just need to set the corresponding flag to true in your Tastic Schema specification.

For example:

{
     ...
     "schema": [
	{
	     "name": "Stream Selection",
	     "fields": [
		...
		{
		     "label": "Show strike price",
		     "field": "showStrikePrice",
		     "type": "boolean",
		     "translatable": true
		}
	     ]
	}
     ]
}
This will give your Frontend Manager the possibility to configure a setting showStrikePrice for each of the locales available in the project.

NOTE: Some field types are translatable by default so if you don't want these to be translatable you need to explicitly switch the setting off. Those types are:

  • string
  • text
  • markdown
Defining Translatable Data

Once you receive translatable data in your Tastic you'll see that the data format changes. Instead of retrieving a single instance of the value type, you receive a HashMap that uses locales as index and has a value type assigned to each of these keys. For example:

{
     data: {
	// ...
	     showStrikePrice: {
		'en_GB': true,
		'de_DE': false,
		'de_CH': true,
	     }
     }
}
For values such as boolean and others you'll then need to determine the correct one for your situation (see later section on advanced internationalization handling). But for textual values Catwalk provides a shortcut.
Translating Textual Data

If you defined a text field that's translatable as below:

{
     ...
     "schema": [
	{
	     "name": "Configuration",
	     "fields": [
		...
		{
		     "label": "Description",
		     "field": "description",
		     "type": "text"
		}
	     ]
	}
     ]
}

You can simply render the description in the user's language using:

import Translatable from 'frontastic-catwalk/src/js/component/translatable'

class TranslationExampleTastic extends Component {
     render () {
	return (<Translatable value={this.props.data.description} />
     }
}

export default TranslationExampleTastic

The Translatable component will retrieve the users preferred locale and the locales configured for the Project. It'll work out the best possible match from the given value and render it. It will also render a ´with the CSS class untranslated` around it if an exact match can't be found. Feel free to style this in your Development or Staging environment so that you can easily spot missing translations.

Automatic Translation of Tastic Fields

If you only have simple string fields that are translatable, you can try our new withTranslatedTasticData higher order component.

This will pass all string Tastic fields that are translatable as an already translated string. This means you don't need to use the <Translatable /> component anymore. Our <TranslationExampleTastic /> component from before would look like this:

import withTranslatedTasticData from "frontastic-catwalk/src/js/component/withTranslatedTasticData";

class TranslationExampleTastic extends Component {
     render() {
	return this.props.data.description;
     }
}

export default withTranslatedTasticData(TranslationExampleTastic);
Working Manually with Internationalized Data

If you need to work with more advanced data structures, numbers or you have advanced requirements than our Translatable component provided, you can handle Internationalization by yourself. To do this, you need to retrieve the involved locale from the Redux Store using a connector function:

export default connect(
     (globalState, props) => {
	return {
	     currentLocale: globalState.app.context.locale,
	     defaultLocale: globalState.app.context.project.defaultLanguage
	}
     }
)(AdvancedTranslationExample)

The currentLocale prop will contain the locale preferred by the current user and defaultLocale can be used as a fallback for missing translations.


‹ Back to Article List

Next Article ›

Image Usage

Still need help? Contact Us Contact Us