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

Use labels

Since 5.0.7 and later, an implicit object called labels was introduced, such that you could access the Locale-dependent labels (so-called internationalization labels) directly. For example, assume you have a label called app.title, and then you could:

<window title="${labels.app.title}">
...
</window>

The labels object is a map (java.util.Map), so you could access the label directly by use of labels.whatever in an EL expression. Moreover, as shown above, you could access the label even if a key is named as aa.bb.cc (a string containing dot), such as app.title in the above example.

If the key is not a legal name, you could use labels['key'] to access, such as labels['foo-yet'].

When an internationalization label is about to be 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.

Use c:l('key')

With 5.0.6 or prior, you could, to get an internationalization label, 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.

Use c:l2('key') to format the message

If you'd like to use the label as a pattern to generate concatenated message with additional arguments (like java.text.MessageFormat does), you could use the l2 function

For example, let us assume we want to generate a full name based on the current Locale, then we could use ${c:l2('key',args)} to generate concatenated messages as follows.

<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>
<label value="${c:l2('fullname.format', fullname)}">

where we assume fullname is a string array (such as new String[] {"Jimmy", "Shiau"}).

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

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 Multiple 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.