ZK Developer's Reference/Internationalization/Labels

Overview

For a multilingual application, it is common to display the content in the language that the end user prefers. With EL, it is easy to display the right language by use of any static method an application provides.

To simplify the task, ZK provides a utility to retrieve Locale-dependent strings easily. For historical reason, it is called i3-label.

i3-label

ZK provides a utility to retrieve Locale-dependent strings easily.

First, you shall put Locale-dependent content into files under the WEB-INF directory, and one file per locale. The file shall be named as i3-label_lang_CNTY.properties, where lang is the language such as en and fr, and CNTY is the country, such as US and FR. If you want to use one file to represent a language regardless the country, you could name it i3-label_lang.properties, such as i3-label_ja.properties. Furthermore, i3-label.properties is the default file if the user's preferred locale doesn't match any other file.

---

In ZUML

To get a Locale-dependent property, you could use ${c:l('key')} in EL expression. For example,

<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>

<window title="${c:l('app.title')}">
 ...
</window>

Notice that the l function belongs to the TLD file called http://www.zkoss.org/dsp/web/core, so we have to specify it with the taglib directive as shown above.

When a Locale-dependent label is about to retrieved, one of i3-label_lang_CNTY.properties will be loaded. For example, if the Locale is de_DE, then WEB-INF/i3-label_de_DE.properties will be loaded. If no such file, ZK will try to load WEB-INF/i3-label_de.properties and WEB-INF/i3-label.properties in turn.

In Java

To access labels in Java code (including zscript), you could use Labels.getLabel(String), Labels.getLabel(String, Object[] args) and others.

String username = Labels.getLabel("username");

Here is a more complex example. Let us assume we want to generate a full name based on the Locale, then we could use Labels.getLabel(String, Object[] args) to generate concatenated messages as follows.

public String getFullName(String firstName, String lastName) {
   return Labels.getLabel("fullname.format", new Object[] {firstName, lastName});
}

Labels.getLabel(String, Object[] args) assumes the content is a valid pattern accepted by MessageFormat, such as "{1}, {0}".

Encoding character set

By default, the encoding of Locale-depedent files are assumed to be UTF-8. If you prefer another encoding, please specify it in a library property called org.zkoss.util.label.web.charset. For more information, please refer to ZK Configuration Reference/zk.xml/The library-property Element/Library Properties#org.zkoss.util.label.web.charset ZK Configuration Reference.

Loading Locale-dependent labels from database

You could extend the label loader to load labels from other locations, say database, by registering a locator, which must implement either LabelLocator2 or LabelLocator. Then, invoke Labels.register(LabelLocator2) or Labels.register(LabelLocator) to register it.

Version History

Last Update : 2010/10/12

Version	Date	Content