Regional settings

Most of the Spring architecture supports internationalization, as does the Spring MVC web framework. DispatcherServlet allows you to automatically recognize messages using the regional settings (locale) of the client. This is done using LocaleResolver objects.

When a request comes in, DispatcherServlet looks for a locale resolver and, if it finds one, tries to use it to set the locale. Using the RequestContext.getLocale() method, you can always get the locale that was recognized by the locale resolver.

In addition to automatic locale detection, you can also bind an interceptor to handler mappings to change the locale under certain circumstances (for example, based on a parameter in the request).

Locale resolvers and interceptors are defined in the org.springframework.web.servlet.i18n package and are configured in the context of your application as usual. Spring includes the following set of locale resolvers.

• Time zone

• Title recognizer

• Cookie recognizer

• Session recognizer

• Regional settings interceptor

Time zone

In addition to obtaining the client's regional settings, it is often useful to know its time zone. The LocaleContextResolver interface provides a LocaleResolver extension that allows resolvers to provide a more functional LocaleContext that can contain time zone information.

If available, the user's TimeZone can be obtained using the RequestContext.getTimeZone() method. Time zone information is automatically used by all Converter and Formatter date/time objects that are registered with the ConversionService from Spring.

Header Recognizer

This locale resolver checks the accept-language header in a request sent by a client (such as a web browser). Typically this header field contains the regional settings of the client's operating system. Please note that this resolver does not support time zone information.

Cookie recognizer

This locale resolver checks Cookies that may exist on the client side against the specified Locale or TimeZone. If there are any, then the specified information is used. Using the properties of this locale recognizer, you can set the name of the cookie as well as the maximum expiration date. The following example defines CookieLocaleResolver:

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">
    <property name="cookieName" value="clientlanguage"/>
    <!-- in seconds. If set to -1, the cookie is not saved (deleted when the browser is closed) -->
    <property name="cookieMaxAge" value="100000"/>
</bean>

The following table describes the properties of the CookieLocaleResolver:

Session recognizer

SessionLocaleResolver allows you to get Locale and TimeZone from a session that can be associated with a user request. Unlike CookieLocaleResolver, this strategy stores the locally selected locale in the HttpSession of the servlet container. As a consequence, these settings are temporary for each session and are therefore lost when each session ends.

Note that there is no direct connection to external session management mechanisms such as the Spring Session project. This SessionLocaleResolver evaluates and modifies the corresponding HttpSession attributes in the current HttpServletRequest.

Regional settings interceptor

You can enable locale changing by adding a LocaleChangeInterceptor to one of the HandlerMapping definitions. It detects the parameter in the request and changes the locale settings accordingly by calling the setLocale method on the LocaleResolver in the dispatcher application context. The following example shows that calls to all *.view resources containing a parameter named siteLanguage will now change the locale settings. So, for example, a request to the URL https://www.sf.net/home.view?siteLanguage=nl changes the site language to Dutch. The following example shows how to intercept the regional settings:

<bean id="localeChangeInterceptor"
        class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
    <property name="paramName" value="siteLanguage"/>
</bean>
<bean id="localeResolver"
        class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>
<bean id="urlMapping"
        class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    <property name="interceptors">
        <list>
            <ref bean="localeChangeInterceptor"/>
        </list>
    </property>
    <property name="mappings">
        <value>/**/*.view=someController</value>
    </property>
</bean>