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 , or you would know "I18n".

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[]) 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[]) to generate concatenated messages as follows.

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

Labels.getLabel(String, Object[]) 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.

Loading Labels from Other Resources

It is typical to partition the properties file into several modules for easy maintenance. In additions, you could extend the label loader to load labels from other locations, say database. It can be done by registering a locator, which must implement either LabelLocator or LabelLocator2. Then, invoke Labels.register(LabelLocator) or Labels.register(LabelLocator2) to register it.

If you can represent your resource in URL, you could use LabelLocator (as show below). If you have to load it by yourself, you could use LabelLocator2 and return an input stream (java.io.InputStream).

For example,

public class FooLocator extends org.zkoss.zk.ui.util.LabelLocator {
    private ServletContext _svlctx;
    private String _name;
    public FootLocator(SevletContext svlctx, String name) {
        _svlctx = svlctx;
        _name = name;
    }
    public URL locate(Locale locale) {
        return _svlctx.getResource("/WEB-INF/labels/" + name + "_" + locale + ".properties");
    }
}

Then, we could register label locators when the application starts by use of WebAppInit as follows.

public class MyAppInit implements org.zkoss.zk.ui.util.WebAppInit {
    public void init(WebApp wapp) throws Exception {
        Labels.register(new FooLocator((ServletContext)wapp.getNativeContext(), "module-1");
        Labels.register(new FooLocator((ServletContext)wapp.getNativeContext(), "module-2");
    }
}

where we assume module-1 and module-2 are two modules of messages you provide. Then, you configure it in WEB-INF/zk.xml as described in ZK Configuration Reference.

Version History

Version	Date	Content
5.0.5	October 2010	LabelLocator2 was introduced.