Labels"

From Documentation
Line 18: Line 18:
 
</blockquote>
 
</blockquote>
 
== In ZUML ==
 
== In ZUML ==
To get a Locale-dependent property, you could use <tt>${c:l('key')}</tt> in EL expression. For example,
+
=== Use <tt>labels</tt> ===
 +
 
 +
Since 5.0.7 and later, an implicit object called <tt>labels</tt> are introduced, such that you could access the Locale-dependent labels (so-called internationalization labels) directly. For example
 +
 
 +
<source lang="xml">
 +
<window title="${labels.app.title}">
 +
...
 +
</window>
 +
</source>
 +
 
 +
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 <tt>de_DE</tt>, then <tt>WEB-INF/i3-label_de_DE.properties</tt> will be loaded. If no such file, ZK will try to load <tt>WEB-INF/i3-label_de.properties</tt> and <tt>WEB-INF/i3-label.properties</tt> in turn.
 +
 
 +
=== Use <tt>c:l('key')</tt> ===
 +
With 5.0.6 or prior, you could, to get an internationalization label, use <tt>${c:l('key')}</tt> in EL expression. For example,
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 30: Line 43:
 
Notice that [[ZUML Reference/EL Expressions/Core Methods/l|the l function]] belongs to the TLD file called [[ZUML Reference/EL Expressions/Core Methods|http://www.zkoss.org/dsp/web/core]], so we have to specify it with the [[ZUML Reference/ZUML/Processing Instructions/taglib|taglib]] directive as shown above.
 
Notice that [[ZUML Reference/EL Expressions/Core Methods/l|the l function]] belongs to the TLD file called [[ZUML Reference/EL Expressions/Core Methods|http://www.zkoss.org/dsp/web/core]], so we have to specify it with the [[ZUML Reference/ZUML/Processing Instructions/taglib|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 <tt>de_DE</tt>, then <tt>WEB-INF/i3-label_de_DE.properties</tt> will be loaded. If no such file, ZK will try to load <tt>WEB-INF/i3-label_de.properties</tt> and <tt>WEB-INF/i3-label.properties</tt> in turn.
+
=== Use <tt>c:l2('key')</tt> to format the message ===
 +
 
 +
If you'd like to use the label as a pattern to generate concatenated message with additional arguments (like <code>[http://download.oracle.com/javase/6/docs/api/java/text/MessageFormat.html java.text.MessageFormat]</code> does), you could use [[ZUML Reference/EL Expressions/Core Methods/l2|the l2 function]]
  
Here is a more complex example. Let us assume we want to generate a full name based on the Locale, then we could use <tt>${c:l2('key',args)}</tt> to generate concatenated messages as follows.
+
For example, let us assume we want to generate a full name based on the current Locale, then we could use <tt>${c:l2('key',args)}</tt> to generate concatenated messages as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >

Revision as of 19:08, 26 March 2011

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[1], 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.


  1. Notice the directory and filename is configurable. For more information, please refer ZK Configuration Reference: org.zkoss.util.label.web.location

In ZUML

Use labels

Since 5.0.7 and later, an implicit object called labels are introduced, such that you could access the Locale-dependent labels (so-called internationalization labels) directly. For example

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

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

Last Update : 2011/03/26


Version Date Content
5.0.5 October 2010 LabelLocator2 was introduced.



Last Update : 2011/03/26

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.