Labels"

From Documentation
Line 13: Line 13:
 
First, you shall put Locale-dependent content into files under the <tt>WEB-INF</tt> directory, and one file per locale. The file shall be named as <code>i3-label_''lang''_''CNTY''.properties</code>, 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 <code>i3-label_''lang''.properties</code>, such as <code>i3-label_ja.properties</code>. Furthermore, <code>i3-label.properties</code> is the default file if the user's preferred locale doesn't match any other file.
 
First, you shall put Locale-dependent content into files under the <tt>WEB-INF</tt> directory, and one file per locale. The file shall be named as <code>i3-label_''lang''_''CNTY''.properties</code>, 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 <code>i3-label_''lang''.properties</code>, such as <code>i3-label_ja.properties</code>. Furthermore, <code>i3-label.properties</code> is the default file if the user's preferred locale doesn't match any other file.
  
To get a Locale-dependent property, you could use <javadoc>org.zkoss.util.resource.Labels</javadoc> in Java, or <tt>${c:l('key')}</tt> in EL expression. To use it in EL, you have to specify the TLD file with the <tt>taglib</tt> directive in your page as follows.
+
=== In ZUML ===
 +
To get a Locale-dependent property, you could use <tt>${c:l('key')}</tt> in EL expression. For example,
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 23: Line 24:
 
</source>
 
</source>
  
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.<ref>For performance issue, the look up sequence for English is different: First:i3-label_en_US.properties, Second:i3-label.properties, Third:i3-label_en.properties</ref>
+
Notice that the <code>l</code> function belongs to the TLD file called <code>http://www.zkoss.org/dsp/web/core</code>, so we have to specify it with the <tt>taglib</tt> directive as shown above.
  
To access labels in Java codes (including zscript), use the <tt>getLabel</tt> method of the <javadoc>org.zkoss.util.resource.Labels</javadoc> class.
+
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.
  
 +
=== In Java ===
 +
To access labels in Java code (including zscript), you could use <javadoc method="getLabel(java.lang.String)">org.zkoss.util.resource.Labels</javadoc>, <javadoc method="getLabel(java.lang.String, Object[] args)">org.zkoss.util.resource.Labels</javadoc> and others.
 +
 +
<source lang="java">
 +
String username = Labels.getLabel("username");
 +
</source>
 +
 +
Here is a more complex example. Let us assume we want to generate a full name based on the Locale, then we could use <javadoc method="getLabel(java.lang.String, Object[] args)">org.zkoss.util.resource.Labels</javadoc> to generate concatenated messages as follows.
 +
 +
<source lang="java">
 +
public String getFullName(String firstName, String lastName) {
 +
  return Labels.getLabel("fullname.format", new Object[] {firstName, lastName});
 +
}
 +
</source>
 +
 +
<javadoc method="getLabel(java.lang.String, Object[] args)">org.zkoss.util.resource.Labels</javadoc> assumes the content is a valid pattern accepted by [http://download.oracle.com/javase/6/docs/api/java/text/MessageFormat.html MessageFormat], such as <code>"{1}, {0}"</code>.
 +
 +
=== Loading Locale-dependent labels from database ===
 
In addition, you could extend the label loader to load labels from other locations, say database, by registering a locator, which must implement the <javadoc type="interface">org.zkoss.util.resource.LabelLocator</javadoc> interface. Then, invoke the <tt>register</tt> method of the <javadoc>org.zkoss.util.resource.Labels</javadoc> class.
 
In addition, you could extend the label loader to load labels from other locations, say database, by registering a locator, which must implement the <javadoc type="interface">org.zkoss.util.resource.LabelLocator</javadoc> interface. Then, invoke the <tt>register</tt> method of the <javadoc>org.zkoss.util.resource.Labels</javadoc> class.
 
'''Notes'''
 
<references/>
 
  
 
=Version History=
 
=Version History=

Revision as of 02:24, 12 October 2010

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}".

Loading Locale-dependent labels from database

In addition, you could extend the label loader to load labels from other locations, say database, by registering a locator, which must implement the LabelLocator interface. Then, invoke the register method of the Labels class.

Version History

Last Update : 2010/10/12

Version Date Content
     



Last Update : 2010/10/12

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