Locale

This documentation is for an older version of ZK. For the latest one, please click here.

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 Application Attribute: px_preferred_locale

[Since 3.6.3]

If you want to use the same locale for all users, you can specify the locale in the application attribute (WebApp, aka., ServletContext) called px_preferred_locale.

Tip: To avoid typo, you can use the constant: Attributes.PREFERRED_LOCALE.

For example, you can implement a WebAppInit listener as follows.

package foo;
public class MyAppInit implements org.zkoss.zk.ui.util.WebAppInit {
  public void init(WebApp wapp) {
    wapp.setAttribute(org.zkoss.web.Attributes.PREFERRED_LOCALE, Locale.DE);
  }
}

And, specify it in WEB-INF/zk.xml:

<listener>
	<listener-class>foo.MyAppInit</listener-class>
</listener>

The Session Attribute: px_preferred_locale

Before checking the browser's preferences, ZK will check if a session attribute called px_preferred_locale is defined. If defined, ZK uses it as the default locale for the session instead of the browser's preferences. Thus, you can control the locale of a session by storing the preferred locale in this attribute.

Tip: To avoid typo, you can use the constant: Attributes.PREFERRED_LOCALE

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(org.zkoss.web.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 use of cookies. With ZK, you can register a request interceptor and manipulates the cookies when the interceptor is called.

A request interceptor is used to intercept each request processed by ZK Loader and ZK Update Engine. It must implements 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 follows. Once registered, the request method is called each time ZK Loader or ZK Update Engine receives a request. Refer to Appendix B in the Developer's Reference for more information about configuration.

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