4.7. Internationalization

Caution

This version is already obsolete. Please check the latest guideline.

4.7.1. Overview

Internationalization is a process wherein the display of labels and messages in an application is not fixed to a specific language. It supports multiple languages. The language switching can be achieved by specifying a unit called “Locale” expressing language, country and region.

This section explains how to internationalize messages to display on the screen.

In order to internationalization, following requrements should be meeted.

• Text elements on the screen(code name, messages, labels of GUI components etc.) should be retrieve from external definitions such as properties file. (should not be hard-coding in the source code)
• The mechanism to specify the locale of the clients should be provided.

Methods to specify the locale are as follows:

• Using standard request header (specify the locale by language settings of browsers)
• Saving the locale into the Cookie using request parameter
• Saving the locale into the Session using request parameter

The image of switching locale is as follows:

Note

For internationalization of Codelist, refer to Codelist.

Note

When the error screen is to be internationalised, transition to error screen is performed by using MVC Controller of Spring. If a direct transition to error screen is performed without Spring MVC, it may happen that the message is not output in intended language.

For details, refer Measures when Internationalization is not applied.

Tip

The most commonly known abbreviation of internationalization is i18n. Internationalization is abbreviated as i18n because the number of letters between the first “i” and the last “n” is 18 i.e. “nternationalizatio”.

4.7.2. How to use

4.7.2.1. Configuration to define messages

To internationalize the messages on the screen, use the one of following MessageSourceimelementations for managing messages.

• org.springframework.context.support.ResourceBundleMessageSource
• org.springframework.context.support.ReloadableResourceBundleMessageSource

The information here explains an example of using the ResourceBundleMessageSource.

applicationContext.xml

<bean id="messageSource"
    class="org.springframework.context.support.ResourceBundleMessageSource">
    <property name="basenames">
        <list>
            <value>i18n/application-messages</value>  <!-- (1) -->
        </list>
    </property>
</bean>

Sr. No.	Description
(1)	Specify i18n/application-messages as base name of properties file. It is recommended to store message properties file under i18n directory to support internationalization. For MessageSource details and definition methods, refer to Message Management.

Example of storing properties files

Properties file should be created in accordance with the following rules.

• File name should be defined in application-messages_XX.properties format. (Specify locale in XX portion)
• The messages defined in application-messages.properties should be created in default language.
• Make sure you create application-messages.properties. If it does not exist, messages cannot be fetched from MessageSource and JspTagException occurs while setting the messages in JSP.

When creating property files as above, it is determined which to use the file as follows:

• When the locale resolved by LocaleResolver is zh, application-messages_zh.properties is used.
• when the locale resolved by LocaleResolver is ja, application-messages_ja.properties is used.
• When properties file does not exist corresponding to the locale resolved by LocaleResolver, application-messages.properties is used as default. (“_XX” portion does not exist in file name)

Note

The locate to use is determined in the following order until a properties file is found corresponding to the locale.

1. Locale sent from clients
2. Locale specified by JVM on which application server runs (it may not be set in some cases)
3. Locale specified by OS on which application server runs

It is frequently misunderstood that default properties file is used when properties file does not exist corresponding to the locale sent from clients . In this case, then it is checked whether the file is available corresponding to the locale specified by the application server. If not found, finally the default properties file is used.

Tip

For description of message properties file, refer to Message Management.

4.7.2.2. Changing locale as per browser settings

4.7.2.2.1. Settings of AcceptHeaderLocaleResolver

If switch the locale using browser settings, use the AcceptHeaderLocaleResolver.

spring-mvc.xml

<bean id="localeResolver"
    class="org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver" /> <!-- (1) -->

Sr. No.	Description
(1)	Specify org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver in id attribute “localeResolver” of bean tag. If this LocaleResolver is used, HTTP header “accept-language” is added for each request and locale gets specified.

Note

When LocaleResolver is not set, org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver is used by default; hence LocaleResolver need not be set.

4.7.2.2.2. Definition of messages

See the example of definition of messages below.

application-messages.properties

title.admin.top = Admin Top

application-messages_ja.properties

title.admin.top = 管理画面 Top

4.7.2.2.3. Implementation of JSP

See the example of implementaion of messages below.

include.jsp(Common jsp file to be included)

<%@ page session="false"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt"%>
<%@ taglib uri="http://www.springframework.org/tags" prefix="spring"%>  <!-- (1) -->
<%@ taglib uri="http://www.springframework.org/tags/form" prefix="form"%>
<%@ taglib uri="http://www.springframework.org/security/tags" prefix="sec"%>
<%@ taglib uri="http://terasoluna.org/functions" prefix="f"%>
<%@ taglib uri="http://terasoluna.org/tags" prefix="t"%>

Sr. No.	Description
(1)	When message is to be output in JSP, it is output using Spring tag library; hence custom tag needs to be defined. <%@taglib uri="http://www.springframework.org/tags" prefix="spring"%> should be defined.

Note

For details on common jsp files to be included, refer to Creating common JSP for include.

JSP file for screen display

<spring:message code="title.admin.top" />  <!-- (2) -->

Sr. No.	Description
(2)	Output the message using <spring:message> which is a Spring tag library of JSP. In code attribute, set the key specified in properties. In this example, if locale is ja, “管理画面 Top” is output and for other locales, “Admin Top” is output.

4.7.2.3. Changing locale depending on screen operations dynamically

The method of dynamic changing the locale depending on screen operations etc. is effective in case of selecting a specific language irrespective of user terminal (browser) settings.

Following is an example of changing locale depending on screen operations.

To use the language selected by a user, chooose org.springframework.web.servlet.i18n.LocaleChangeInterceptor.

LocaleChangeInterceptoris an interceptor to save the locale value specified by the request parameter using org.springframework.web.servlet.LocaleResolver.

Select the implementation class of LocaleResolver from the following table.

Types of LocaleResolver

No	Implementation class	How to save locale
	org.springframework.web.servlet.i18n.SessionLocaleResolver	Save in server(using HttpSession)
	org.springframework.web.servlet.i18n.CookieLocaleResolver	Save in client(using Cookie)

Note

When org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver is used in LocaleResolver, locale cannot be changed dynamically using org.springframework.web.servlet.i18n.LocaleChangeInterceptor.

4.7.2.3.1. How to define LocaleChangeInterceptor

If switching the locale using the request parameter, use the LocaleChangeInterceptor.

spring-mvc.xml

<mvc:interceptors>
  <mvc:interceptor>
    <mvc:mapping path="/**" />
    <mvc:exclude-mapping path="/resources/**" />
    <mvc:exclude-mapping path="/**/*.html" />
    <bean
      class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">  <!-- (1) -->
    </bean>
    <!-- omitted -->
  </mvc:interceptor>
</mvc:interceptors>

Sr. No.	Description
(1)	Define org.springframework.web.servlet.i18n.LocaleChangeInterceptor in interceptor of Spring MVC.

Note

How to change the name of request parameter to specify locale

<bean
    class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
    <property name="paramName" value="lang"/>  <!-- (2) -->
</bean>

Sr. No.	Description
(2)	In paramNameproperty, specify the name of request parameter. In this example, it is “request URL?lang=xx”. When paramName property is omitted, “locale” gets set. With “request URL?locale=xx”, it becomes enabled.

4.7.2.3.2. How to define SessionLocaleResolver

If saving the locale in the server side, use the SessionLocaleResolver.

spring-mvc.xml

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.SessionLocaleResolver">  <!-- (1) -->
    <property name="defaultLocale" value="en"/>  <!-- (2) -->
</bean>

Sr. No.	Description
(1)	Define id attribute of bean tag in “localeResolver” and specify the class wherein org.springframework.web.servlet.LocaleResolver is implemented. In this example, org.springframework.web.servlet.i18n.SessionLocaleResolver that stores locale in session is specified. id attribute of bean tag should be set as “localeResolver”. By performing these settings, SessionLocaleResolver will be used at the LocaleChangeInterceptor.
(2)	Specify Locale in defaultLocale property. When Locale cannot be fetched from the session, setup value of value becomes valid. Note When defaultLocale property is omitted, Locale set in the user terminal (browser) becomes valid.

4.7.2.3.3. How to define CookieLocaleResolver

If saving the locale in the client side, use the CookieLocaleResolver.

spring-mvc.xml

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">  <!-- (1) -->
      <property name="defaultLocale" value="en"/>  <!-- (2) -->
      <property name="cookieName" value="localeCookie"/>  <!-- (3) -->
</bean>

Sr. No.	Description
(1)	In id attribute “localeResolver” of bean tag, specify org.springframework.web.servlet.i18n.CookieLocaleResolver. id attribute of bean tag should be set as “localeResolver”. By performing these settings, CookieLocaleResolver will be used at the LocaleChangeInterceptor.
(2)	Specify Locale in defaultLocale property. When Locale cannot be fetched from Cookie, setup value of value becomes valid. Note When defaultLocale property is omitted, Locale configured in the user terminal (browser) becomes valid.
(3)	The value specified in cookieName property is used as cookie name. If not specified, the value of org.springframework.web.servlet.i18n.CookieLocaleResolver.LOCALEis used as default. It is recommended to change not to tell the user explicitly Spring Framework is used.

4.7.2.3.4. Messages settings

See the example below for messages settings.

application-messages.properties

i.xx.yy.0001 = changed locale
i.xx.yy.0002 = Confirm change of locale at next screen

application-messages_ja.properties

i.xx.yy.0001 = Localeを変更しました。
i.xx.yy.0002 = 次の画面でのLocale変更を確認

4.7.2.3.5. Implementation of JSP

See the example of implementation of JSP below.

JSP file for screen display

<a href='${pageContext.request.contextPath}?locale=en'>English</a>  <!-- (1) -->
<a href='${pageContext.request.contextPath}?locale=ja'>Japanese</a>
<spring:message code="i.xx.yy.0001" />

Sr. No.

Description

(1)

Submit the request parameter to switch the locale. Request parameter name is specified in paramName property of LocaleChangeInterceptor. (In the example above, the default parameter name is used) In the above example, it is changed to English locale in English link and to Japanese locale in Japanese link. Hereafter, the selected locale is enabled. As “en” properties file does not exist, English locale is read from properties file by default.

Tip

• Spring tag library should be defined in common jsp files to be included.
• For details on common jsp files to be included, refer to Creating common JSP for include.

4.7.2.3.6. Measures when Internationalization is not applied

Since LocaleChangeInterceptor is an interceptor which is called while executing Controller process of Spring MVC, it should be noted that internationalization is not applied when the transition is not done via Controller.

For example, when a JSP file is to be specified directly in the settings for transition to error screen, Controller is not used in the transition to error screen. In such a case, in order to internationalize error screen, a Controller must be created for transition to error screen and it must be set so as to enable use of LocaleChangeInterceptor, by using it in transition to error screen.

Note

Similarly, when a transition is to be performed by specifying JSP directly, Tiles is not applied since it does not pass through ViewResolver used by Screen Layout using Tiles.

Implementation of Authorization is shown below with an example, for the setting method.

Example for transition to error screen wherein LocaleChangeInterceptor is not applied

• spring-security.xml

<sec:http>
    <!-- omitted -->
    <sec:access-denied-handler
        error-page="/WEB-INF/views/common/error/accessDeniedError.jsp" /> <!-- (1) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Specify error screen for authorization error in error-page attribute of <sec:access-denied-handler> tag, by JSP.

Example for transition to error screen wherein LocaleChangeInterceptor is applied

• spring-security.xml

<sec:http>
    <!-- omitted -->
    <sec:access-denied-handler
        error-page="/common/error/accessDeniedError" /> <!-- (1) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Specify a path for transition to error screen for authorization error, in error-page attribute of <sec:access-denied-handler> tag.

• Controller class

@Controller
@RequestMapping("/common/error") // (1)
public class ErrorController {

    @RequestMapping("accessDeniedError") // (1)
    public String accessDeniedError() {
        return "common/error/accessDeniedError"; // (2)
    }

}

Sr. No.	Description
(1)	Define request mapping for transition to error screen.
(2)	Return View name of error screen for transition.

Warning

Generally, it is recommended not to use <mvc:view-controller> since transition to error screen is likely to occur by GET request as well as POST request.

For notes while using <mvc:view-controller>, refer HTML response.