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
:
Property | Default | Description |
---|---|---|
|
class name + LOCALE |
Cookie name |
|
Default servlet container |
The maximum time that a cookie is stored on the client side. If |
|
/ |
Limits the visibility of cookies to a specific part of your site. If |
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>