UI Localization

ACE UI Localization

UI localization is the ability to display a UI in a way that is adapted to a specific locale or region. In ACE, this means that applications such as the Content Developer support translating labels, messages etc. into any language as well as adapting properties like date formats.

Localizations can be provided by a project by importing new localization definitions and configuring the ACE UI applications to use them (see below). This can be used to create completely new localizations as well as to override existing language keys used by ACE UI or the Content Developer.

The ACE UI applications and widget libraries come with built in support for English.

Locale selection and fallbacks

ACE UI applications will always try to display themselves using the selected locale of the current user. This is automatically determined by the application using settings from the browser. This might be something like American English (en_US) or Canadian French (fr_CA).

UI localization in ACE work using a fallback mechanism which makes sure the end user always ends up with an effective localization using as much as possible from the selected language or locale. For example, if the ACE UI application has determined that Canadian French (fr_CA) is the most fitting locale, the effective localization used will be Canadian French whenever possible. In the cases where there are no Canadian French translations, generic French (fr) will be used instead. As a final fallback, ACE UI applications then also tries to use English (en).

The Localization Service

Localized bundles are retrieved using the Localization Service. This service can be queried for multiple bundles (for different contexts) in one request, in which case the service will aggregate the bundles.

The service expects URLs on the following format:

http://ace-content-service:8081/localization/<CONTEXTS>/<LANGUAGE>

<CONTEXTS> is a '|'-separated list of contexts for which to build the total language bundle.

<LANGUAGE> is a string describing the language or locale for which to build the total language bundle. Should be on Java Locale string format.

The constructed total language bundle will be delivered by the Localization Service as a JSON object.

Retrieve the effective language bundle for X in locale Y:

$ curl -i -s "http://ace-content-service:8081/localization/X/Y"

HTTP/1.1 200 OK
Date: Wed, 30 Jan 2019 13:58:46 GMT
Ace-Api-Version: 1.7.1
Cache-Control: no-transform, max-age=60, s-maxage=60, public
Content-Type: application/json
Content-Length: 2239

{
  ...
}

Examples

Retrieve the effective language bundle for ace-ui in English:

$ curl -i -s "http://ace-content-service:8081/localization/ace-ui/en"

Retrieve the effective language bundle for ace-ui and code in English:

$ curl -i -s "http://ace-content-service:8081/localization/ace-ui|code/en"

Retrieve the effective language bundle for ace-ui, code as well as myProject in English:

$ curl -i -s "http://ace-content-service:8081/localization/ace-ui|code|myProject/en"

Retrieve the effective language bundle for ace-ui, code as well as myProject in American English:

$ curl -i -s "http://ace-content-service:8081/localization/ace-ui|code|myProject/en_US"

Automatic fallback for region specific locales to non-region will be performed. For example, when requesting a language bundle for en_US, you will automatically also get the standard english language bundle included. The en_US localization will of course take precedence.

Storage format

Localizations are stored in content using the aceLocalizationContent content type and the aceLocalization aspect type. When using the .properties file format though (described below), the correct types are automatically assigned.

Importing a translation

Localized strings can be imported into ACE directly from .properties files using the content import. Using a special file name format, the localized strings will automatically be imported to a content of the correct type, for the correct context and correct locale. The file format is

<LOCALE>.<CONTEXT>.localization.properties

where the first part could be e.g. en or en_US and the second could be myProject.

Examples

Properties file representing the localization for the English bundle of myProject

en.myProject.localization.properties

##
# MyProject english localization
##

# Custom project keys

myProject.template.article=MyProject Standard Article
myProject.customWidget.save=Save
myProject.customWidget.close=Close

# Override of ACE standard UI keys

code.welcome=MyProject-specific Content Developer greeting

NOTE: localization for a single bundle (read: "project") cannot be spread across multiple JSON or localization properties files. If the localization NEEDS to be spread across multiple files, the recommended way is to instead use multiple bundles.

Configuring the ACE UI applications

The ACE Content Developer is pre-configured to use the default localization supplied by both ACE UI and the Content Developer itself, which is available for standard english (en).

Any custom localization, be it for a new module or overrides of existing ACE UI / Content Developer language keys, must be added to the configuration of the application where it should be included.

Example for the Content Developer

code.json

{
  "i18n": {
    "translationSchema": ["ace-ui", "code", "myProject"]
  }
}

The language used by the Content Developer is automatically detected using browser settings with a fallback to standard english (en).

Examples

Browser using en_GB will get localization in en > en_GB, with en_GB being the most significant locale.
Browser using fr will get localization in en > fr, with fr being the most significant locale.
Browser using fr_CA will get localization in en > fr > fr_CA, with fr_CA being the most significant locale.

If the most significant locale doesn't contain all language keys, the next most significant locale in the locale significance order will be used for those keys, and so on.

Guides

Creating a localization for a new language

fr.myProject.localization.properties

##
# MyProject-specific language keys
##

myProject.customWidget.save=Enregistrer
myProject.customWidget.close=Fermer
...

##
# Existing ACE UI / Content Developer keys
##

code.welcome=Bienvenu au Content Developer
...

When creating a new translation, you will need to know which language keys to translate. This information can be retrieved from the Localization Service by requesting the total language bundle in English. The following will return a total language bundle for the contexts ace-ui, code as well as myProject in standard English:

$ curl -i -s "http://ace-content-service:8081/localization/ace-ui|code|myProject/en"

Make sure that relevant ACE UI applications are also configured to include the new bundle (see above).

Overriding keys in an existing localization

en.myProject.localization.properties

##
# Existing ACE UI / Content Developer keys
##

code.welcome=MyProject-specific Content Developer greeting
...

Make sure that relevant ACE UI applications are also configured to include the new bundle (see above).

Localizing a template

The following parts of a template are always localizable, and handled by the ACE UI framework:

label - the template label displayed in ACE UI template selectors, such as the Content Developer quick-creator
field help text - the text displayed as the help text of a template field
field expandable help text - the text displayed as the verbose help text of a template field

Example:

{
  "label": "template.article.label",

  "dataBindings": [
    {
      "name": "title",
      "label": "template.article.title.label",

      "widget": "aceUITextInput",

      "helpText": "template.article.title.helpText",
      "expandableHelpText": "template.article.title.expandableHelpText"
    }
  ]
}

Widget-specific configuration such as placeholder texts may or may not be localizable, depending on the widget. All standard ACE UI widgets are localizable. Please see the ACE UI widget documentation for more information.

Localization in ACE UI is done through the use of the angular-translate library, which is automatically supplied to all ACE UI applications. A widget simply needs to inject and leverage the $translate service. All bootstrapping related to determining what language / locale to use as well as the loading of the localization keys will have already been taken care of.

Example: the MyWidget widget

MyWidget-widget.js

atex.aceui.register('ng-directive', 'MyWidget', [], function() {
  return ['$translate', function($translate) {
    return {
      controller: function($scope) {
        $scope.placeholder = $scope.config.placeholder || '';

        // Will return the determined language / locale
        // value (like en_US), should you ever need it
        $translate.use();
      },

      link: function(scope, element, attrs) {
        // Translate a property programatically
        scope.translatedPlaceholder = $translate.instant(scope.placeholder);
      }
    };
  }];
});

MyWidget-template.html

<!-- Translate the 'placeholder' attribute -->
<input translate-attr="{ 'placeholder': placeholder }" />

<!-- Translate the element value -->
<span translate>my-widget.label</span>

Please see the angular-translate documentation for usage details.

ACE UI Localization

Locale selection and fallbacks

The Localization Service

Examples

Storage format

Importing a translation

Examples

Configuring the ACE UI applications

Example for the Content Developer

Examples

Guides

Creating a localization for a new language

Overriding keys in an existing localization

Localizing a template

Localizing a widget