ZK Developer's Reference/Internationalization/Locale

Overview

The locale used to process requests and events is, by default, determined by the browser's preferences (by use of the getLocale method of javax.servlet.ServletRequest). For example, DE is assumed if an user is using a DE-version browser (unless he changed the setting).

In this section, we'd like to discuss how to configure ZK to handle the locale differently. For example, you might want to use the same Locale for all users no matter how the browser is configured. Another example is that you might want to use the preferred locale that a user specified in his or her profile, if you maintain the user profiles in the server.

The decision sequence of locale

The locale is decided in the following sequence.

1. It checks if an attribute called org.zkoss.web.preferred.locale defined in the HTTP session (or Session). If so, use it.
2. It checks if an attribute called org.zkoss.web.preferred.locale defined in the Servlet context (or Application). If so, use it.
3. It checks if a property called org.zkoss.web.preferred.locale defined in the library property (i.e., Library). If so, use it.
4. If none of them is found, it uses the locale defined in the Servlet request (i.e., ServletRequest.getLocale()).

With this sequence in mind, you could configure ZK to use the correct locale based on the application requirements.

Application-level Locale

If you want to use the same locale for all users, you can specify the locale in the library property. For example, you could specify the following in WEB-INF/zk.xml:

<library-property>
    <name>org.zkoss.web.preferred.locale</name>
    <value>de</value>
</library-property>

Alternatively, if you prefer to specify it in Java, you could invoke Library.setProperty(String, String). Furthermore, to avoid typo, you could use Attributes.PREFERRED_LOCALE as follows.

Library.setProperty(Attributes.PREFERRED_LOCALE, "de");

Per-user Locale

Because ZK will check if a session attribute for the default locale, you could configure ZK to have per-user locale by specifying the attribute in a session.

For example, you can do this when a user logins.

 void login(String username, String password) {
     //check password
     ...
     Locale preferredLocale = ...; //decide the locale (from, say, database)
     session.setAttribute(Attributes.PREFERRED_LOCALE, preferredLocale);
     ...
 }

The Request Interceptor

Deciding the locale after the user logins may be a bit late for some applications. For example, you might want to use the same Locale that was used in the previous session, before the user logins. For a Web application, it is usually done by storing the information in a cookie. It can be done by registering a request interceptor, and then manipulating the cookies when the interceptor is called.

A request interceptor is used to intercept each request being processed. It must implement the RequestInterceptor interface. For example,

import java.util.Locale;

import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;

import org.zkoss.web.Attributes;

public class MyLocaleProvider implements org.zkoss.zk.ui.util.RequestInterceptor {
     public void request(org.zkoss.zk.ui.Session sess,
     Object request, Object response) {
        final Cookie[] cookies = ((HttpServletRequest)request).getCookies();
         if (cookies != null) {
             for (int j = cookies.length; --j >= 0;) {
                if (cookies[j].getName().equals("my.locale")) {
                     //determine the locale
                     String val = cookies[j].getValue();
                     Locale locale = org.zkoss.util.Locales.getLocale(val);
                     sess.setAttribute(Attributes.PREFERRED_LOCALE, locale);
                     return;
                 }
             }
         }
     }
}

To make it effective, you have to register it in WEB-INF/zk.xml as a listener. Once registered, the request method is called each time ZK receives a request.

<listener>
    <listener-class>MyLocaleProvider</listener-class>
</listener>

Note: An instance of the interceptor is instantiated when it is registered. It is then shared among all requests in the same application. Thus, you have to make sure it can be accessed concurrently (i.e., thread-safe).

Note: The request method is called at very early stage, before the request parameters are parsed. Thus, it is recommended to access them in this method, unless you configured the locale and character encoding properly for the request.

Version History

Version	Date	Content