i18n
Product: xTier™/LWC 2.3 Whitepaper:  Technical Whitepaper	support@fitechlabs.com  Download  Buy
Depends: log  Related: n/a
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
The 'i18n' service provides a general purpose internationalization facility. Basically, xTier™ 'i18n' allows internationalization for two types of information: textual (i.e., strings, labels text, messages, etc.), and object. Both classes of properties can have a set of values. Concrete value is retrievied based on locale settings. Non textual, object properties have java.lang.Object as a value, which is instantiated and internally retrived using Inversion of Control (IoC) mechanism used througout xTier. 'i18n' service uses IoC mechanism to instantiate objects, that can be local-dependent, such as images, audoclips, UI settings, etc. See IocService for more details on IoC-based configuration.

The main features of the 'i18n' service include (but are not limited to):

• The ability to have different property values for different locales.
• The ability to reload the configuration automatically.
• Skins allow to have different values for the same property and locale.
• The ability to pass parameters to property value.
• The ability to retrieve object property values using IoC (Inversion of Control) mechanism.
• A unified XML-based configuration.

 Top

Configuration
The 'i18n' service is configured via the pre-defined xtier_i18n.xml configuration file. Formal specification for this file can be found at ${XTIER_ROOT}/config/dtd/xtier_i18n.dtd. This file follows standard xTier™ service configuration pattern demonstrated by the following complete example of the i18n configuration:

1		<xtier-i18n>
2		<region name="examples">
3		<reload>true</reload>
4
5		<group name="another.group">
6		<!-- Locale-less property. -->
7		<i18n name="file.path">
8		<forall>somepath</forall>
9		</i18n>
10		</group>
11
12		<group name="i18n.group">
13		<!-- Localized property. -->
14		<i18n name="locale.prop">
15		<!-- Skinless values. -->
16		<locale lang="en" country="US">
17		Skinless short form - ${another.group:file.path}
18		</locale>
19		<locale lang="en">
20		Skinless lo...ong form - ${another.group:file.path}
21		</locale>
22		<skin name="short">
23		<locale lang="en" country="US">Short form. </locale>
24		</skin>
25		<skin name="long">
26		<locale lang="en">Lo...ong form.</locale>
27		</skin>
28		</i18n>
29		</group>
30
31		<group name="example">
32		<i18n name="prop0">
33		<locale lang="en">Template#0</locale>
34		<skin name="example.skin">
35		<locale lang="en">
36		No parameter skinned template
37		</locale>
38		</skin>
39		</i18n>
40
41		<i18n name="prop1">
42		<locale lang="en">Template#1 {0}</locale>
43		<skin name="example.skin">
44		<locale lang="en">
45		1 parameter skinned template {0}
46		</locale>
47		</skin>
48		</i18n>
49
50		<i18n name="prop4">
51		<locale lang="en">
52		Template#4 {0} {1} {2} {3}
53		</locale>
54		<skin name="example.skin">
55		<locale lang="en">
56		4 parameters skinned template {0} {1} {2} {3}
57		</locale>
58		</skin>
59		</i18n>
60
61		<i18n name="obj">
62		<ioc-locale lang="en">
63		<!-- IoC object definition -->
64		<ioc policy="new">
65		<java class="java.lang.StringBuffer">
66		<!--
67		Creating this object by calling a constructor
68		with the following arguments.
69		-->
70		<ctor>
71		<arg type="string" >Skinless IoC object</arg>
72		</ctor>
73		</java>
74		</ioc>
75		</ioc-locale>
76		</group>
77
78		<group name="example.locale">
79		<i18n name="prop.en">
80		<locale lang="en">Values: {0}, {1}</locale>
81		</i18n>
82		<i18n name="prop.de">
83		<locale lang="de">Bedeutungen: {0}, {1}</locale>
84		</i18n>
85		</group>
86		</region>
87		</xtier-i18n>

The 'i18n' configuration region consists of zero or more <group> tags each defining an i18n group. <group> XML tag has the following required attributes:

name	Unique name of the i18n group. This name can be used later at runtime to access this group's properties.

The 'i18n' group consists of zero or more <i18n> tags each defining an i18n property. <i18n> XML tag has the following required attributes:

name	Name of the i18n property. Should be unique within the i18n group. This name can be used later at runtime to access this property's value.

<i18n> tag may include <forall>, <skin>, <locale>, <ioc-forall> and <ioc-locale> tags. The <forall> XML tag defines textual property value that is the same for any locale. <locale> tag define textual property value for a given locale. <locale> XML tag has the following attributes:

lang	Required ISO-639 language code.
lang	Optional ISO-3166(A2) country code.

<locale> value is used as property for given locale.

<ioc-forall> and <ioc-locale> tags provide ability to use Inversion of Control (IoC) mechanism for internationalization/localization purposes. Adding IoC support to 'i18n' service allows to internationalize/localize non-textual information, such as images, audioclips, etc. <ioc-forall> and <ioc-locale> tags acts the same as <forall> and <locale> tags, respectively, except these tags contain nested <ioc> element, which describes IoC based value for property.

Object, defined by this tag, can be instantiated and retrieved using one of getObject(...) i18n service methods. These methods return java.lang.Object that can be cast to its actual type. Note that i18n property cannot mix string and IoC-based values, thus <i18n> tag cannot have both <locale> and <ioc-locale> nested tags together.

You can consider 'example:obj' property from XML fragment above as example of IoC-based configuration. Here java.lang.StringBuffer object is defined, which can be instantiated later at runtime using one-arg constructor, which will take string argument with value "Skinless IoC object". Note that any other objects can be configured in similar way as values for this property for other locales or skins. See IocService for more details on xTier™ IoC configuration.

Skins allow to have different values for the same property name and the same locale depending on the skin. Currently used skin can be set via setSkin(String) method. <skin> XML tag has the following required attributes:

name	Name of the skin. This name can be used later at runtime to find property value which skin matches 'i18n' service current skin.

<skin> XML tag consists of one <forall>, or one <ioc-forall>, or one or more <locale> tags, or one or more <ioc-locale> tags (note that ioc and non-ioc tags cannot be used together in the same <skin> element). <forall> tag provides the same skinned value for any locale. <locale> tag provides property value for corresponding locale.

Note that <forall> and <locale> tags cannot be used together in the same <skin> tag. <ioc-forall> and <ioc-locale> tags act similary, except they define IoC-based property value instead of string pattern.

'i18n' configuration region also provides possibilty to enable/disable its configuration reloading and to specify time period of automated reloading. This ability is provided by <reload> XML tag which can be included into <region> tag. <reload> XML tag has the following attributes:

msec	This optional attribute specifies i18n configuration region reloading period in millisecinds. If ommited, default value '600000' (10 min.) is used. If <reload> tag has false value, this attribute is ignored.

<reload> tag can take the following values: true or false. if value is true, i18n configuration region automatically reloads with period, specified by msec attribute (10 min by default). if value is true, i18n configuration region does not reload automatically. However in this case it still can be reloaded via reload() method call.

 Top

Properties
Each property in <locale> and/or <forall> elements should contain textual pattern that is a functional subset of formatting pattern supported by java.text.MessageFormat class. Following table shows supported pattern elements.

Java {index[,formatType][,formatStyle]}

{N}

{N, number}

{N, number, integer}

{N, number, percent}

{N, number, currency}

{N, number, other}

{N, date}

{N, date, short}

{N, date, medium}

{N, date, long}

{N, date, full}

{N, date, other}

{N, time}

{N, time, short}

{N, time, medium}

{N, time, long}

{N, time, full}

{N, time, other}

N - index of the argument.

Note again that although 'i18n' service supports only a subset (see above) of formatting supported by java.text.MessageFormat class, the property values should follow the single quote escaping rules defined in java.text.MessageFormat class. In particular, "''" should be used to represent one single quote within the string (unescaped single quotes have special meaning in java.text.MessageFormat's supported grammar).

 Top

Property Substitution
Any property in <locale> and/or <forall> elements can include ${[group:]prop} construct (more specifically, matching \$\{([^:}]+:)?[^:}]+\} regular expression) where group is an optional i18n group name and prop is the name of property in that group. If group is not specified the current group is assumed by default. The value of referenced property will be substituted in place of ${[group:]prop}. ${[group:]prop} construct can use forward declarations.

 Top

I18n JSP Support
'i18n' service comes with JSP tag that can be used to access service's functionality directly via JSP tag. In ${XTIER_ROOT}/lib/xtier/taglib directory there is JAR xtier-taglib.jar that contains code for custom JSP tag. The same directory also contains JSP taglib file xtier-taglib.tld. Consult this file for detailed usage information. Following JSP example demonstrates some basic usage of JSP i18n tag. Assuming the following taglib declaration was used:

<%@ taglib uri="/xtier" prefix="xtier" %>

the JSP fragment may look like:

1		<html>
2		<head>
3		<title>Sample JSP page</title>
4		</head>
5
6		<body>
7		Property 1: <br>
8		<xtier:i18n locale="en" group="test" prop="prop1"
9		skin="test.skin" p1="param1"/>
10		<br>
11		<br>
12		Property 2: <br>
13		<xtier:i18n group="test" prop="prop2"/>
14		</body>
15		</html>

 Top

I18n Lint Utility
xTier ships with special utility xtier-i18n-lint.{sh|exe} that can be found in ${XTIER_ROOT}/bin directory. This command lint utility allows to check consistency between I18n XML configuration files and the usage of I18n service in source code (Java). This utility checks the following error conditions:

• Properties unused in source code.
• Missing properties.
• Duplicate properties.
• Invalid property names.
• Arguments number mismatch.
• Invalid formatting.
• Arguments are incorrectly numbered.
• Different number of arguments for localizations.
• Undetermined usage of I18n service. Variable is used for property name.
• Undetermined usage of I18n service. Variable is used for group name.
• Unused groups in source code.
• Regions containing different sets of groups/properties.

-root <path>

Sets xTier™ installation root.

-i18nxml <file-path>

File containing I18n configuration information.

-path <path>

Source code location.

-exclude <path;path;...>

Folders to be excluded from source code.

-lang <java|vb|cs|js|cpp|all>

Source code programming language.

-help or -?

Shows help message.

 Top

Examples
Usage of 'i18n' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the 'i18n' service. Once the service instance is obtained the service API can be used. 'i18n' provides a set of format methods to retrieve textual values and set of getObject methods to retieve IoC-based values.

'i18n' service provides two types of formatting methods: one that uses the current locale and another that takes locale as a parameter, the same for getObject methods. All formatting methods accept from 0 to 5 parameters for convenience. If more parameters is required, user can use the methods that accept object array.

Following example illustrates these basic steps:

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'i18n' service.
5		I18nService i18n = xtier.i18n();
6
7		// Print value of property 'prop0' from 'example'
8		// group.
9		System.out.println(i18n.format("example", "prop0"));
10
11		// Set skin 'example.skin'.
12		i18n.setSkin("example.skin");
13
14		// Print skinned value of property 'prop4' from
15		// 'example' group with 4 parameters.
16		System.out.println(i18n.format("example", "prop4",
17		"p1", "p2", "p3", "p4"));
18
19		// Print default locale.
20		System.out.println("Default locale: " +
21		i18n.getLocale());
22
23		// Print 'example.locale:prop.en' property value
24		// with array of paramters.
25		Object[] params = new Object[] { new Date(),
26		new Double(7.777) };
27		System.out.println("prop.en with default locale: " +
28		i18n.format("example.locale", "prop.en", params));
29
30		// Print 'example.locale:prop.de' property value with
31		// Locale.GERMANY local and array of parameters.
32		System.out.println("prop.de with GERMANY locale: " +
33		i18n.format(Locale.GERMANY, "example.locale",
34		"prop.de", params));
35
36		// Set locale.
37		i18n.setLocale(java.util.Locale.GERMANY);
38
39		// Print 'example.locale:prop.de' property value,
40		// 'i18n' service locale is now Locale.GERMANY.
41		System.out.println("prop.de with default locale: " +
42		i18n.format("example.locale", "prop.de", params));
43
44		// Get 'example:obj' IoC property value for Locale.US locale.
45		StringBuffer buff = (StringBuffer)i18n.getObject(Locale.US,
46		"example", "obj");
47		System.out.println("obj property for Locale.US: " + buff);
48
49		// Reloading.
50		i18n.addListener(new I18nChangeListener() {
51		public void i18nChanged() {
52		System.out.println("i18n configuration changed.");
53		}
54		});
55
56		i18n.reload();

 Top