Core-Gadget - i18n

Owned by JamesS
Last updated: Mar 09, 2012Version comment
3 min read
The "JavaScript i18n" feature provides a JavaScript API for localized
parsing and formatting of dates, times, numbers and currency according
to the rules for the gadget's locale as set by the container. The
feature is specified by including either an "Optional" or "Required"
element within the "ModulePrefs" of the Gadget specification. The
feature identifier is "opensocial-i18n".

A container MUST emit the OpenSocial JavaScript i18n libraries and
data files required by the libraries if an application requires the
feature <Require feature="opensocial-i18n"/>. The container
SHOULD emit the OpenSocial JavaScript i18n libraries and data files
required by the libraries if an application optionallly requests the
feature <Optional feature="opensocial-i18n"/>.

Once available, gadget developer's can use the feature via the
"gadgets.i18n" JavaScript class.

The locale used by a gadget is established by the container when the
gadget is rendered. The i18n feature will use the country and language
specified in the locale to load the appropriate formatter and parser
for any given date, time, number or currency.

The i18n feature provides four distinct methods, defined <xref
target="i18n.methods">here</xref>. These are formatDateTime,
formatNumber, parseDateTime and parseNumber. At a minimum, each method
takes as input a format pattern that defines the structure of the data
being parsed or formatted and the value to which the pattern is to be
applied.

For instance, to format an integer using a localized grouping
separator (e.g. the number 1234567 formatted as "1,234,567" when the
locale is "en-US"), the following can be used:</t>

 var str = gadgets.i18n.formatNumber("#,###", 1234567);

The i18n feature includes a number of common, predefined format
patterns that can be used. The specific definition of these formats
are specific to the locale established by the container. For instance,
using the predefined "gadgets.i18n.MEDIUM_DATE_FORMAT" pattern to
format the date for August, 4th 2006 using the "de" (German) locale
using the formatDateTime method would output "04.08.2006". Using the
same predefined pattern using the "en-US" (United States) locale,
however, would output "08-04-2006".

 var date = new Date(2006,7,4);
 var str = gadgets.i18n.formatDateTime(gadgets.i18n.MEDIUM_DATE_FORMAT, date);

When parsing and formatting currencies using the predefined patterns,
There are several considerations that need to be taken into account.
For example, when the default locale is set to "fr-FR" (France), and
the gadgets.i18n.CURRENCY_PATTERN is used to parse a string, the
parser will assume that the input string is formatted according to the
localized rules for the "fr-FR" locale:

 var num = gadgets.i18n.parseNumber(gadgets.i18n.CURRENCY_PATTERN,
"20 000 \u20AC");

Here, "num" will equal 20000. </t>

If a foreign currency is used, U.S. Dollars for instance, the input
string MUST still be formatted in accordance to the rules specified
for the established locale and an optional currency code can be
specified:

 var num = gadgets.i18n.parseNumber(gadgets.i18n.CURRENCY_PATTERN,
"20 000 $", 0, "USD");

If, however, the input string is not formatted in accordance to the
localized rules for the established locale, the predefined pattern
will not work and a custom pattern needs to be used:

 var num = gadgets.i18n.parseNumber("#,###", "$20,000", 0, "USD");

#.#. Specifying Format and Parsing Patterns

#.#.#. Date/Time Pattern Specification

When formatting and parsing dates and times, the i18n feature utilizes
the patten specification defined in Appendix F of the <eref
target="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">
Unicode Locale Data Markup Language</eref> with the exception that
support for the following symbols is not required:

 - w: Week of year
 - W: Week of Month
 - D: Day of year
 - F: Day of Week in Month
 - g: Modified Julian day

#.#.#. Number Pattern Specification

Patterns for formatting and parsing numbers are expressed using the
same grammar used by the Java Standard Edition's as described <eref
target="http://docs.oracle.com/javase/7/docs/api/java/text/NumberFormat.html">NumberFormat</eref>
class.</t>

For example, assuming a locale of "en-US", using the pattern
"#,##0.00" to format the number 1234567.1234 using the formatNumber
method would output "1,234,567.12".

#.#. JavaScript Definitions

#.#.#. Predefined Format Constants

The Predefined Format Constants that MUST be supported are listed in
the table below. The specific pattern associated with each constant
will vary by locale.

     <texttable>
       <ttcol align="left" width="15%">Property</ttcol>
       <ttcol align="left">Description</ttcol>
       <c><spanx style="verb">gadgets.i18n.CURRENCY_PATTERN</spanx></c>
       <c>The default currency format, e.g. for the locale "en-US",
       the number 1234.235 would format as "$1,234.34".</c>
       <c><spanx style="verb">gadgets.i18n.DECIMAL_PATTERN</spanx></c>
       <c>The default decimal number format, e.g. for the locale
       "de-DE", the number 1234 with a fractional decimal of 13
       would format as "1.234,13".</c>
       <c><spanx style="verb">gadgets.i18n.PERCENT_PATTERN</spanx></c>
       <c>The default percentage number format, e.g. for the locale
       "en-US", the number 123 would format as "12,300%"</c>
       <c><spanx style="verb">gadgets.i18n.SCIENTIFIC_PATTERN</spanx></c>
       <c>The default scientific-notation format, e.g. the number
       12345.0 would format as "1E4"</c>
       <c><spanx style="verb">gadgets.i18n.FULL_DATE_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.FULL_DATETIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.FULL_TIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.LONG_DATE_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.LONG_DATETIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.LONG_TIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.MEDIUM_DATE_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.MEDIUM_DATETIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.MEDIUM_TIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.SHORT_DATE_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.SHORT_DATETIME_FORMAT</spanx></c>
       <c></c>
       <c><spanx style="verb">gadgets.i18n.SHORT_TIME_FORMAT</spanx></c>
       <c></c>
     </texttable>
   </section>

(after here is the current javascript reference.. largely unmodified)