5.13. 国際化

Caution

本バージョンの内容は既に古くなっています。最新のガイドラインはこちらからご参照ください。

5.13.1. Overview

国際化とは、アプリケーションで表示するラベルやメッセージを、特定の言語のみに固定せず、ロケール(Locale)と呼ばれる言語や国・地域を表す単位の指定により、複数言語の切替に対応させることである。

本章ではメッセージの国際化方法について説明する。

国際化に対応するには、以下の対応が必要となる。
  • 状態やメッセージ、GUIコンポーネントのラベルなど、テキスト要素をプログラム内でハードコードしない。
  • テキスト要素をプログラム以外の外部データに保持する。

国際化を実現するためには、Localeを保持する必要があり、主に

  • セッションにLocaleを保持する方法
  • CookieにLocaleを保持する方法

がある。

Localeを変更するイメージを以下に示す。

locale change image

実際にLocaleを保持する場所は実装方法により決定される。

本章では、国際化を使用する上での各種ルールや推奨実装方法を記述する。

Note

国際化はi18nという略称が広く知られている。 i18n という記述は、internationalization の先頭の i と語尾の n の間に nternationalizatio の 18文字があることに起因する。

Tip

Codelistの国際化方法については、 コードリスト を参照されたい。


5.13.2. How to use

5.13.2.1. Localeをユーザ端末(またはブラウザ)の設定により切り替える場合

Spring の org.springframework.context.support.ResourceBundleMessageSource を利用することでLocaleをユーザ端末(またはブラウザ)の設定による切り替えが実現できる。
ここでは、MessageSourceを利用した場合の、国際化方法について説明する。

Tip

MessageSourceの詳細や定義方法は、 メッセージ管理 を参照されたい。

bean定義ファイル

  • applicationContext.xml
<bean id="messageSource"
    class="org.springframework.context.support.ResourceBundleMessageSource">
    <property name="basenames">
        <list>
            <value>i18n/application-messages</value>  <!-- (1) -->
        </list>
    </property>
</bean>
項番
説明
(1)
プロパティファイルの基底名として、i18n/application-messagesを指定する。
国際化対応を行う場合、i18nディレクトリ配下にメッセージプロパティファイルを格納することを推奨する。
  • spring-mvc.xml
<bean id="localeResolver"
    class="org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver" /> <!-- (1) -->
項番
説明
(1)
beanタグのid属性”localeResolver”に org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver を指定する。
このlocaleResolverを使用すると、リクエスト毎にHTTPヘッダー”accept-language”が追加されLocaleが指定される。

Note

localeResolverが設定されていない場合、デフォルトで org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver が使用されるため、localeResolverの設定は、省略することもできる。

ファイルパス

properties filepath
ファイル名は、application-messages_XX.propertiesという形式で作成する。XX部分はLocaleを指定する。
LocaleResolverによって解決されたLocaleがzhの場合、application-messages_zh.propertiesが使用され、
LocaleResolverによって解決されたLocaleがjaの場合、application-messages_ja.propertiesが使用される。
LocaleResolverによって解決されたLocaleに対応するプロパティファイルが存在しない場合、デフォルトとして、application-messages.propertiesが使用される。(ファイル名に”_XX”部分が存在しない)
application-messages.propertiesを使うときは、以下のことに注意する。
  • application-messages.propertiesに定義するメッセージは、デフォルトで使用する言語で作成すること。
  • application-messages.properties必ず作成すること 。もし存在しない場合、MessageSourceからメッセージを取得できず、JSPにメッセージを設定する際に、JspTagExceptionが発生する。

Tip

メッセージプロパティファイルの記載方法については、 メッセージ管理 を参照されたい。

Note

Localeの判別方法は、以下の順番で該当するLocaleのプロパティファイルが発見されるまで、Localeを確認していくことである。

  1. リクエストのHTTPヘッダー”accept-language”に指定されているLocale
  2. アプリケーションサーバのJVMに指定されているLocale(設定されていない場合あり)
  3. アプリケーションサーバのOSに指定されているLocale

よく間違える例として、 リクエストのHTTPヘッダー”accept-language”の値に該当するLocaleのプロパティファイルが存在しない場合、デフォルトのプロパティファイルが使用されるとの誤解が挙げられる。 実際は、次にアプリケーションサーバに指定されているLocaleを確認して、それでも該当するLocaleのプロパティファイルが見つからない場合に、デフォルトのプロパティファイルが使用されるので注意する。

以下、メッセージ定義の設定例を示す。

プロパティファイル

  • application-messages.properties
title.admin.top = Admin Top
  • application-messages_jp.properties
title.admin.top = 管理画面 Top

JSPファイル

  • include.jsp(インクルード用の共通jspファイル)
<%@ 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"%>
項番
説明
(1)
JSPで出力する場合、Springのタグライブラリを用いてメッセージ出力を行うため、カスタムタグを定義する必要がある。
<%@taglib uri="http://www.springframework.org/tags" prefix="spring"%> を定義すること。

Note

インクルード用の共通jspファイルの詳細は インクルード用の共通JSPの作成 を参照されたい。

  • 画面表示用JSPファイル
<spring:message code="title.admin.top" />  <!-- (1) -->
項番
説明
(1)
JSPでは、Springのタグライブラリである、 <spring:message> を用いてメッセージ出力を行う。
code属性に、プロパティで指定したキーを設定する。
本例では、Localeが、jaの場合、”管理画面 Top”、それ以外のLocaleの場合、”Admin Top”が出力される。

5.13.2.2. Localeを画面操作等で動的に変更する場合

Localeを画面操作等で動的に変更する方法は、ユーザ端末(ブラウザ)の設定に関係なく、特定の言語を選択させたい場合に有効である。
org.springframework.web.servlet.i18n.LocaleChangeInterceptor を用いることで実現できる。
LocaleChangeInterceptorとは、リクエストパラメータの値に指定された
Localeの値を用いて、 org.springframework.web.servlet.LocaleResolver に保存するインタセプターである。
LocaleResolverの実装クラスは使用するLocaleの保存先により、以下の表から選択する。
Interceptorを利用する場合に使用するLocaleResolverの種類
No 実装クラス Locale保存方法
org.springframework.web.servlet.i18n.SessionLocaleResolver
サーバーに保存
org.springframework.web.servlet.i18n.CookieLocaleResolver
クライアントに保存

Note

LocaleResolverに org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver を使用する場合、 org.springframework.web.servlet.i18n.LocaleChangeInterceptor を使用してLocaleを動的に変更することはできない。

bean定義ファイル

SessionLocaleResolver の場合

  • spring-mvc.xml
<!-- omitted -->
<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>

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.SessionLocaleResolver">  <!-- (2) -->
    <property name="defaultLocale" value="en"/>  <!-- (3) -->
</bean>
項番
説明
(1)
Spring MVCのインタセプターに、 org.springframework.web.servlet.i18n.LocaleChangeInterceptor を定義する。
(2)
beanタグのid属性を”localeResolver”で定義し、 org.springframework.web.servlet.LocaleResolver を実装したクラスを指定する。
本例では、セッションにLocaleを保存する org.springframework.web.servlet.i18n.SessionLocaleResolver を指定している。
beanタグのid属性は”localeResolver”と設定すること。
この設定により、 org.springframework.web.servlet.i18n.LocaleChangeInterceptor 内で使用されるLocaleResolverが、(3)のLocaleResolverに設定される。
(3)
リクエストパラメータでLocaleを指定しない場合、defaultLocaleに指定されたLocaleが有効になる。この場合、 HttpServletRequest#getLocale での取得値が有効になる。
  • リクエストパラメータに設定するLocaleのキーを変更する場合
  • spring-mvc.xml
<bean
  class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
  <property name="paramName" value="lang"/>  <!-- (1) -->
</bean>
項番
説明
(1)
paramNameにリクエストパラメータに設定されたLocaleのキーを指定する。ここの例では”リクエストURL?lang=xx”となる。
キーを指定しない場合、”locale”が設定される。 “リクエストURL?locale=xx”で 使用可能 となる。

CookieLocaleResolverの場合

  • spring-mvc.xml
<!-- omitted -->
<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>

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">  <!-- (2) -->
      <property name="defaultLocale" value="en"/>  <!-- (3) -->
      <property name="cookieName" value="localeCookie"/>  <!-- (4) -->
</bean>
項番
説明
(1)
Spring MVCのインタセプターに、 org.springframework.web.servlet.i18n.LocaleChangeInterceptor を定義する。
(2)
beanタグのid属性”localeResolver”に org.springframework.web.servlet.i18n.CookieLocaleResolver を指定する。
beanタグのid属性は”localeResolver”と設定すること。
この設定により、 org.springframework.web.servlet.i18n.LocaleChangeInterceptor 内で使用されるLocaleResolverが、(3)のLocaleResolverに設定される。
(3)
Localeを指定しない場合、defaultLocaleに指定されたLocaleが有効になる。この場合、 HttpServletRequest#getLocale での取得値が有効になる。
(4)
cookieNameプロパティに指定した値が、cookie名となる。指定しない場合、 org.springframework.web.servlet.i18n.CookieLocaleResolver.LOCALE となる。springframeworkを使用していることがわかるため、変更することを推奨する。
  • リクエストパラメータに設定するLocaleのキーを変更する場合

SessionLocaleResolverと 設定 は同様である。

以下、プロパティの設定例を示す。

プロパティファイル

  • 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変更を確認

JSPファイル

  • 画面表示用JSPファイル
<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" />
項番
説明
(1)
LocaleChangeInterceptorのparamNameで指定された、リクエストパラメータのキーを送信する。
上記例の場合、Englishリンクで英語Locale、Japaneseリンクで日本語Localeに変更している。
以降は、選択したLocaleが有効になる。
英語Localeは”en”用のプロパティファイルが存在しないため、デフォルトのプロパティファイルから読み込まれる。

Tip

  • インクルード用の共通jspにSpringのタグライブラリを定義する必要がある。
  • インクルード用の共通jspファイルの詳細は インクルード用の共通JSPの作成 を参照されたい。

画面操作でLocaleを変更する場合のイメージを以下に示す。

i18n change locale on screen