Localize your sites

Print articleFacebookTwitter

Translating common words and phrase throughout your sites can now easily be done by using the "Localization" feature of Enonic CMS 4.4.0

Based on a resolved locale the localization feature enables you to translate phrases or words. Typically, elements like menus, buttons, footers etc could be labeled in different languages based on e.g the users preferences. The translations should be written in files, one for each supported locale, with a key representing the phrase name, and a value representing the locale representation of the phrase.

There are three steps necessary to enable localization:

1. Locale resolver setup
2. Create localization resource-files for selected locales
3. Use the localization function in your templates

Locale resolver

To be able to localize a word or phrase, we have to decide which locale to use.

A locale in this context is a string representing language, country and variants. Country and variant are optional. The three parts are separated by underscores, like: "languagecode_countrycode_variantcode"

The language argument should be a valid ISO Language Code, and the country argument should be a valid ISO Country Code.

Samples of valid locale strings:

To resolve the locale, you have a number of different choices:

1. Forced
2. Script-resolved
3. Menu-item or site-language

These are evaluated in the given order. If no forced value found and no script applied, the menu-item or site-language will automatically be used.

Forced

There are two portal HTTP-Service functions at your disposal to manipulate Locale; "forceLocale" and "resetLocale".
The "forceLocale" - function can be used to offer the user a selection of supported languages:

<a href="{portal:createServicesUrl('portal','forceLocale', ('locale', 'en', 'lifetime', 'permanent'))}">
 English
</a>

<a href="{portal:createServicesUrl('portal','forceLocale', ('locale', 'no', 'lifetime', 'permanent'))}">
 Norsk
</a>

<a href="{portal:createServicesUrl('portal','forceLocale', ('locale', 'no_NO_NY', 'lifetime', 'permanent'))}">
 Nynorsk
</a>

Script-resolved

Its also possible to apply a locale classification script on your sites. This script should evaluate a given input and return a string representing the resolved locale. The script will be provided with an XML containing fields from the HTTP-Request and the current user.

The script could for instance use the HTTP-Request path, the accept-language header or the user's locale-setting to resolve the locale.

Menuitem or site - language

This is the simplest approach. If the menu-item has a language-setting, this will be use. If not, the site language-setting will be used.

Localization resource files

The localization resource-files contain the names of the phrases or words to be localized with their responding locale translation. When discovering localize-functions in the templates, Enonic CMS will try to find the best matching translation of the phrase or word based on the resolved locale in these files.

There has to be one default resource file, and optinally a number of locale specific files.

E.g; If supporting "english - Great Britain"  and "english - United States" on your site, you will have two or three localization resource files on your site:

phrases.properties (default - all common or default phrases)
phrases_en_gb.properties (english (gb) specific phrases)
phrases_en_us.properties (english (us) specific phrases)

Since the default resource file should contain all phrases or words to enshure that everything will be localized no matter what locale is resolved, we could have managed with only two files; the default and the one that should differ from the default. 

Sample localization resource files

phrases.properties:

   label_menu=menu
   label_colour=colour
   label_centre=centre
   label_summary=You selected {0} of {1} elements

phrases_en_gb.properties

   label_colour=colour

phrases_en_us.properties

   label_colour=color
   label_centre=center

Finding the best match

When localizing phrases, Enonic CMS will search for the most accurate match first, and then broaden the search until reaching the default resource file.

E.g.: Locale is resolved to "en_GB_ch" and a localize request for "label_centre" occurs: 

phrases_en_gb_ch.properties -> file not found
phrases_en_gb.properties -> file found, but no phrase
phrases_en.properties -> file not found
phrases.properties -> match found, returns "centre"

Placeholders

If the "languageRepresentation" - string contains placeholders, these could be used to insert parameters when localizing elements.

Placeholders should appear in the localeRepresentation as a number that is enclosed in curly brackets, such as "{0}", "{1}", "{2}", etc, and these placeholders will then be replaced by parameters sent by the two-argument localize-function.

As an example, calling function:

<xsl:value-of select="portal:localize('summary', (4,10))"/>

with resolved locale "en" on the above files will result in the localized phrase:

You selected 4 of 10 elements

Deploying

The localization resource-files should be stored on your server as you would do with any resource file. On a site's property-page, there is a section named "Localization" with a picker for "Default localization resource". Select your default localization resource file, and localization will be enabled.

Localizing phrases in your templates

When the locale resolver is configured and the localization resource-files are created, the templates will be able to localize the phrases or words by calling the "localize" HTTP-Services portal-function. The localized phrase will be fetched from the best matching localization resource and inserted into the rendered result.

<xsl:value-of select="portal:localize('label_menu')"/>
<xsl:value-of select="portal:localize('label_summary', '4,10')"/>
<xsl:value-of select="portal:localize('label_color')"/>