Localization

Introduction

Elementi supports locale-dependent display of date, time, numbers, and currencies for an extensive list of locales. A locale is a set of parameters that defines the user's language, region and any special variant preferences that the user wants to see in their user interface. Usually a locale identifier consists of at least a language identifier and a region identifier.

Many widgets included into Elementi Library feature a "Locale" property for selecting the desired locale, and different ways to specify the desired formatting - for instance, the date time widget has a "Format" property for selecting the date / time format, while most of the data-driven widgets and sun and moon widgets allow specifying date, time, and number formats inside data placeholders.

The support for localization has been further improved starting with Elementi 2016, by allowing to change the default calendar and the numeral system associated with a certain locale.

Locale selection

Locale dialog

For the widgets featuring a "Locale" property (under the "Properties" tab in Edit panel), selecting the desired locale is done by clicking the locale drop-down selection box, which offers a short list (up to ten options) of lastly-utilized locales, plus a "More..." option, which opens the "Locale" dialog (featured on the right) containing all the available locales.

Starting with Elementi 2016, two new options are available within the "Locale" dialog: "Calendar" and "Numbers"; these allow changing the default calendar and numeral system for the selected locale. For instance, the user could choose between Latin or Thai numerals for Thai language.

• Only relevant choices are proposed for the chosen language - for instance, if you chose the Thai language, then you can choose between Latin or Thai numerals.
• Others, like Roman numerals and Greek lower case numerals, might not be considered as relevant for any language so they have to be asked for manually in the data placeholder string.

How to add localization

This section is for advanced users.

Localization can be added to a widget using the <spx:json-choice> customization tag, with the "choice" attribute set to "locales". This will add a property within the Edit panel, under the "Properties" tab, listing all the available locales as described above.

Another way is through jSignage localization functions.

Date and time formats

 

The date and time formats detailed below can be used within Date Time widget, date widgets, and all the data-driven widgets containing data placeholders.

Generic date formats

The date / time format is commonly specified using the user-friendly date/time patterns detailed below:

• FULL_DATE

  Displays the date as "Tuesday, April 14, 2015" for "en_US" locale.

• LONG_DATE

  Displays the date as "April 14, 2015" for "en_US" locale or "14 de abril de 2015" for "es_ES" locale.

• MEDIUM_DATE

  Displays the date as "Apr 14, 2015" for "en_US" locale.

• SHORT_DATE

  Displays the date as "4/14/15" for "en_US" locale.

• FULL_TIME, LONG_TIME

  Displays the time as "10:10:34 PM GMT-05:00" for "en_US" locale.

• MEDIUM_TIME

  Displays the time as "10:10:34 PM" for "en_US" locale.

• SHORT_TIME

  Displays the time as "10:10 PM" for "en_US" locale.

• FULL_DATETIME

  Displays the date and time as "Tuesday, April 14, 2015 10:10:34 PM GMT-05:00" for "en_US" locale. It is a shortcut for "FULL_DATE FULL_TIME".

• LONG_DATETIME

  Displays the date and time as "April 14, 2015 10:10:34 PM GMT-05:00" for "en_US" locale. It is a shortcut for "LONG_DATE LONG_TIME";

• MEDIUM_DATETIME

  Displays the date and time as "Apr 14, 2015 10:10:34 PM" for "en_US" locale. It is a shortcut for "MEDIUM_DATE MEDIUM_TIME";

• SHORT_DATETIME

  Displays the date and time as "4/14/15 10:10 PM" for "en_US" locale. It is a shortcut for "SHORT_DATE SHORT_TIME".

Note:

The date and time formats can be freely combined beyond the *_DATETIME combinations above, separated by a space - for instance "LONG_DATE SHORT_TIME".

Date format patterns

Alternatively, you can use the Unicode CLDR date-time patterns, where each time unit, like the month or the hour, is represented by a sequence of letters from A to Z, that get automatically substituted upon parsing - for instance, you can use "EEEE, MMMM d, y hh:mm a" for a full date with 12-hour time (or "HH:mm" at the end for 24-hour time).

The following fields are fully or partially supported:

• G (era), y (year), u (extended year), U (cycle year name), r (related Gregorian year), Q (quarter), q (stand-alone quarter), M (month), L (stand-alone month), d (day of month), g (modified Julian day), E (day of week), e (local day of week), c (stand-alone local day of week),
• a (am/pm), h (hour 1-12), H (hour 0-23), K (hour 0-11), k (hour 1-24), m (minute), s (second), S (fractional second), A (milliseconds in day),
• z (time zone), Z (time zone), v (short time zone)

The following fields are NOT supported: w (week of year), W (week of month), Y (year in in "Week of Year" based calendars), D (day of year), F (day of week in month), b (period), B (flexible period), O (localized time zone), V (time zone id), X (ISO8601 time zone), x (X ISO8601 time zone without Z).

Notes:

• To prevent the characters replacement, the "real" characters need to be surrounded by apostrophes within the format string; for instance use "d 'of' MMMM" to get "14 of April". To use the apostrophe within that quoted string, use '' (that is, two adjacent ' characters); for instance use "h 'o''clock'" to get "10 o'clock".
• The numerals used are the default ones for the locale, except for the r, g and A fields which always use latin digits. Numerals can be overridden for all date fields at a time by prepending a BCP47 numbering system id to the formatting string between two hash signs, e.g. #hanidec# to use Chinese digits. The numerals can also be specified on a field based basis, e.g., #d=hanidays# displays the date with Han day-of-the-month characters for the day field only. The numerals for the time-related fields cannot be overridden.

Number formats

 

The number formats detailed below can be used within chart widgets, gauge widgets, and all the data-driven widgets containing data placeholders.

Generic number formats

The format for numbers is commonly specified using the user-friendly number patterns detailed below:

• DECIMAL

  Formats numbers as generic decimals. This is the lacuna value.

• SCIENTIFIC or E

  Formats numbers using the scientific E notation.

• PERCENT or %

  Formats numbers using percent values, such as 12%.

• CURRENCY or $

  Formats numbers as currency values, such as $12.00 for US locale.

Number format patterns

Alternatively, you can use the Unicode CLDR number patterns - for instance "#,###.00" means that the number is formatted so that only two decimals are kept and a "grouping" separator is used for thousands.

The following pattern characters are supported:

• 0 (zero padding), @ (significant digit), # (digit),
• . (decimal separator), , (grouping separator),
• - (minus sign), + (explicit plus),
• E (exponential), % (percent), ‰ (per mille),
• ¤ (currency symbol),
• ; (sub-pattern boundary).

The following pattern characters are NOT supported: 1-9 (rounding), * (padding).

Notes:

• The pattern must be either of a fixed digit positions (with #) or a significant digits (with @) one. If the patterns contains a @ it is a significant digits pattern. # and @ can be used in the same pattern to specify a minimum and maximum number of significant digits. The minimum number of significant digits is the number of @ signs, the maximum is the total number of @ and # signs.
• Remember that a significant digit format does not always mean the number of digits will be the one specified because additional zeros before or after the significant digits may be required. For instance, the number 12345 formatted as @@ will yield 12000 because 3 zeros are required after the two significant digits.
• Number patterns are only used when the numbering system for the locale is a decimal one. Both the default and native numbering systems are guaranteed to be decimal systems for all locales. However, the Chinese and Japanese traditional and financial numbering systems are not decimal, neither are Roman, Greek and Hebrew numerals, in which case the pattern is ignored.