Top

Localization and Resources

Localization and Internationalization

Localization and internazionalization is a powerful feature to write applications that adapts to different languages and settings based on country and/or regional differences of target market.

Internationalization aka i18n

Internationalization, meant as a way to develop applications that can be easily adapted to different languages, is achieved by means of Resources files that specify a format to produce a common structure translated in as many languages as you wish to offer to users.

There are currently available two kind of resources that can be defined and/or used inside an Aria Templates application.

  • Static resources
  • Dynamic resources (through Resource Providers) - Currently under development. More documentation to be provided soon.

Static resources

Static resources can be defined inside plain JavaScript files using the Aria.resourcesDefinition facility. They are usually physically stored as files on the back-end Web Server delivering your AT application, thus accessible through the HTTP(S) protocol.

You can then localize a resource file creating different versions of the file and appending the locale to the end of each resource definition JavaScript file.

An example of a resource definition is the following:

Conventions to be used

Resources should be defined by following a standard scheme to be properly accessible from your code: classpath.panelId.resType.resId. Here's an explanation of each scheme component and accepted values:

  • classpath - the classpath of the resourcesDefinition entity
  • panelId - the id of the panel where the resource is used or common if it is used in several panels
  • resType - the type of the resource, which can be one of the following values:

    • label - static text resource without any HTML markup
    • alt - alternate text for DOM elements (mainly images)
    • content - text resource which may contain safe HTML markup (no CSS, no Scripts)
    • link - relative or absolute path to a resource
    • pattern - pattern resource (e.g. date format, number format ...)
  • resId - a free text which has to be descriptive

How to use Static Resources
Inside Templates

You must first declare the classpath of the resources to use with the $res parameter of the Template statement. Then, localized resources are made available through the res variable, which can be seen be seen as an alias to the automatically loaded resource classpath.

Of course, you can use an intermediate variable, like label here, to make the references to localized resources less verbose.

Inside Template Scripts

Here is the script associated to the previous template, which displays a message, using localized resources.

As the class generated from a template inherits from its script, localized resources are also available from the template script, through this.res.

Localization aka l10n

Localization, meant as the process of adapting an internationalized application to a specific region or language, is achieved with application wide settings that can be changed anytime during applications's life cycle.

All locale specific parameters can be configured through the aria.core.AppEnvironment.

The framework allows you to configure:

  • Language of static resources
  • Number and currency format settings
  • Date and Time format settings

Language

Language and region are used to load a particular version of #static-resources. The language identifier follows the IETF language tag standards but only allows to specify a primary language subtag and one extended language subtag, e.g en-US. aria.core.environment.Environment.setLanguage(locale, afterChangeCB) aria.core.environment.Environment.getLanguage()

More information are available on Environment Base Configuration Bean.

While changing the locale is quite easy, at least a full application templates refresh could be required to make the changes effective. For this pourpose the first method accept a callback parameter - i.e. a method/function - that should contain all the necessary code to achieve the aforementioned goal.

Resources organization

Definition and structure are better defined in the following section. Here we simply highlight how to organize your translated resource files. A potential structure, could be for instance the following, with translations in five languages:

$appRoot/res/SampleRes.js //default language, if no app wide locale is specified
$appRoot/res/SampleRes_en_US.js
$appRoot/res/SampleRes_sv_SE.js
$appRoot/res/SampleRes_fr_FR.js
$appRoot/res/SampleRes_sv_SE.js
$appRoot/res/SampleRes_pl_PL.js

The framework will automatically try to download the proper resource file based on the locale setting defined through the AppEnvinroment.setLanguage method call.

Please note how the first resource is indeed the base resource name to be referenced inside your classes, modules and/or templates. While keeping this name you should then append the proper locale code according to the language contained in each resource file.

Number and currency

Aria Templates provides a Number utility to interpret numbers and format them according to a user defined pattern and locale.

Application's parameters are defined in Number Configuration Bean and can be modified through the AppEnvironment.

Snippet on how to modify the appenvironment

By default numbers are interpreted with en_US conventions:

  • " . " a dot for decimal separator.
  • " , " a comma for group (thousand) separator.
Numberfield with different patterns and separators

The option strictGrouping allows to enforce or not the match between the number pattern and what the user typed.

When strictGrouping is enabled, the following rules apply:

Pattern : #,###
1,000 is valid
1,00 is invalid

Pattern : #,##
1,000 is invalid
1,00 is valid

disabling strictGrouping no check will be done on the input pattern, the grouping separator is simply ignored

Pattern : #,###
1,000 is valid : 1000 (one thousand)
1,00 is **valid** : 100 (one hundred)

Pattern : #,##
1,000 is **valid** : 1000 (one thousand)
1,00 is valid : 100 (one hundred)

strictGrouping might be useful for languages such as

  • Chinese/Japanese : the grouping separator might be used as a 10-thousands separator

    10,0000  (100 thousands)
  • Hindi : the first grouping separator (from the rightmost character) is used for thousands and then for hundreds

    10,00,000 (1 million)

The separator can be only a single character, non digit. Conventions such as the ones used in the following countries are not supported:

  • Croatia : thousands separator alternates dots and commas

    1.000,000 (1 million)
  • Mexico : comma for thousand, apostrophe for million

    1'000,000 (1 million)

The formatting patterns to specify how a number should be conventionally displayed or interpreted, even as a currency. It can be defined as a combination of the following:

Symbol Location Meaning
0 Number Digit
# Number Digit, zero shows as absent
. Number Decimal separator
, Integer Grouping separator
ยค (\u00A4) Prefix or suffix Currency sign, replaced by currency symbol.

The supported patterns are a subset of the java.text.DecimalFormat specs.

Date and Time

Date Configuration Bean defines the application's environment for date and time formatting.

  • Accepted date separators : / - . and space.
  • Accepted time separators : \;,.-/: and space.
  • Accepted formatters : d M y E for date and h m s for time.

Accepted formatters are a subset of the Java patterns.

Some date patterns are defined at application level :

shortFormat, longFormat, mediumFormat and fullFormat.

Default values for these patterns are:

  • shortFormat: d/M/y
  • mediumFormat: d MMM y
  • longFormat: d MMMM yyyy
  • fullFormat: EEEE d MMMM yyyy

These patterns can be accessed through aria.utils.environment.Date.getDateFormats()

Similarly some time patterns are also defined at application level. There are currently two :

shortFormat and fullFormat.

Default values for these patterns are:

  • shortFormat: HH:mm
  • fullFormat: HH:mm:ss

These patterns can be accessed through aria.utils.environment.Date.getTimeFormats()

Supported patterns are similar to Java patterns.

Example:
`dd MMM yyyy` will display **02 Feb 2010** for date 02/02/2010.

`hh:mm` will display **09:00** for 9.00

On top of Java-like patterns, it is possible to use the IATA format replacing the month format character with 'I'. For example:

`UddIyy`   will display **02 Feb 10** for date 02/02/2010.
or
`UddIyyyy`   will display **02 Feb 2010** for date 02/02/2010.

In this case, the English version of the month will be displayed in the format specified regardless of the localization settings (IATA format corresponds to 3 capital letter untranslated month name).

Snippet on how to modify the appenvironment

The format for date and time can be either a String or a Function. This

When setting formats at the application level it is possible to specify the format as a string or as a function. This will provide usecases where the format needs to be generated dynamically.

Anything, including something with a function in the format.