The InternationalTokens Object

An InternationalTokens have the same functionality as the Properties object with the addition of the format function. The main difference is in the loading of the file.

Refer to the Properties object for details of that functionality.

InternationalTokens objects are of class I18nTokens.

The InternationalTokens Constructor

Using the new Operator with the InternationalTokens Constructor

The InternationalTokens constructor is used to create new InternationalTokens objects.

var myInternationalTokens = new InternationalTokens(name[, language[, country]]);

A new InternationalTokens object for the file identified by the name is created. The name uses the script file reference to identify the file. The file can be anywhere on the host filing system. If the name argument is not present then a runtime error will be generated and the script page execution halted.

The language and country are optional and represent the locale for the international tokens. If the language and country arguments are present then the constructor will automatically call the read function to load the properties into the InternationalTokens object.

After the InternationalTokens object has been created, calling the read function causes it to load all the tokens in the properties file that most closely matches the language and country specified. If no language and country are specified in the read function then the script locale is used for the language and country. These tokens are then available as variables held by the InternationalTokens object. The values of these variables are always strings.

The difference between a Properties object and an InternationalTokens object is that there is a set of properties files all using the same names for the properties (which are called tokens) but with different language versions of the values. Each properties file in the set holds all the tokens for a language and a script writer using the token names will automatically get the correct language version of the token.

Each properties file in the set has a file name with a particular structure. The first part of the name is the base name for the properties (the name specified when creating a InternationalTokens object) and is the same for all properties files in the set. The second part is the language and country in the form "_ll_cc" where ll is a two digit language code and cc is a two digit country code. The third part is ".properties" and is the same for all properties files in the set.

e.g.

mytokens_en_us.properties	American English properties file
mytokens_fr_ca.properties	French Canadian properties file
mytokens_ja.properties	Japanese properties file
mytokens_zh.properties	Chinese properties file

The example above shows a set of properties files for English, French, Japanese and Chinese. What this set also shows is that the country is optional and if not present then the language properties file will be used ignoring the country.

In fact there is a hierarchy of loading a properties file. First an exact match of language and country is looked for, then just the country and finally just the base name on its own with no language or country. This hierarchy applies to individual tokens as well as to whole properties files. This means that if you have a properties file for French and another for French Canadian, the French Canadian properties file only needs to contain those tokens whose words or spelling differ from the standard French tokens.

The language and country codes are normally taken from the script locale which is derived from the request object which holds the codes sent by the browser. The example below shows an InternationalTokens object being used to display the 'hello' phrase in the browser users language.

var tokens = new InternationalTokens(“mytokens");
tokens.read();
write(tokens.helloPhrase);

Note that by using the read function without specifying the language and country the script locale is used.

Shown below is the InternationalTokens object prototype chain.

Calling the InternationalTokens Constructor as a Function

When the constructor is run as a function without the new operator it has exactly the same behaviour as using the new operator.

InternationalTokens Constructor Properties

Constructor properties are read only (they cannot be changed or deleted) and it is not possible to add new properties to the Constructor.

Property	Description
prototype	A reference to the I18nTokens Prototype. This property does not enumerate and can not be changed or deleted.

InternationalTokens Constructor Functions

The InternationalTokens constructor has no predefined functions.

The I18nTokens Prototype

This prototype can be used by any object. It requires the properties file name to be a property in the object called fileName. If this is not present then the read and write functions will cause the error property to be set in the object. The language and country (if required) must also be properties of the object.

I18nTokens Prototype Properties

Property	Description
prototype	A reference to the Properties Prototype. This property does not enumerate and can not be deleted, but it can be changed.

I18nTokens Prototype Functions

The this reference used here always refers to the object that was used to run the function.

Function

Description

format(name, format)

Returns the name property formatted in the appropriate manner based on the locale. The format argument is an array of objects to be used in formatting the property. See below for an explanation of how to use the format function.

read([language[, country]])

Reads the properties from the international set of properties file and adds them to this object as properties. The language and country arguments define the locale for the tokens and if these arguments are not present then the script locale is used. If an error is detected this function will return false and the error property will be set. If the properties were read successfully then this function will return true.

Note: All properties created are primitive strings.

Formatting Properties

Properties can be formatted using a format pattern as shown below. This pattern is embedded in the string that is the value of the property. Any number of patterns can be embedded in the string.

messageFormatPattern := string ( "{" messageFormatElement "}" string )*
messageFormatElement := argument { "," elementFormat }
   elementFormat := "time" { "," datetimeStyle } or "date" { "," datetimeStyle } or "number" { "," numberStyle }
   datetimeStyle := "short" or "medium" or "long" or "full" or dateFormatPattern
   numberStyle := "currency" or "percent" or "integer" or numberFormatPattern

The format element is enclosed in braces and must contain an argument. This argument is the index in the arguments array. Formatting with no elementFormat defined will replace the format element by the String representation of the relevant object in the arguments array. If there is no element in the arguments array then the format element in the message will be replaced by null. See dateTimeStyle and the numberStyle formats.

To use formatted messages the script writer calls the format function supplying the property name and an array of arguments. The format function returns the string formatted using the data from the arguments array.

e.g.

The file myTokens.properties contains the following line. Note that the data for the token called myMessage contains four format elements, but as two of them reference the same index in the arguments array we only need three elements in the array.

myMessage = At {1,time,short} on {1,date,medium}, there was {2} on planet {0,number,integer}.

This piece of script code is run on Jul 3, 2053:

var tokens = new InternationalTokens("myTokens");
tokens.read();
var arguments = new Array(7.5696, new Date(), "a disturbance in the Force");
writeln(tokens.format("myMessage", arguments));

The resulting output is:

At 12:30 p.m. on Jul 3, 2053, there was a disturbance in the Force on planet 7.

Comment on this topic

Topic ID: 150063