Setting up i18n
Internationalization is a means of adapting your application to different languages to allow for regional differences. Follow these steps to enable internationalization in your application.
Only use UTF-8!
Play supports only one encoding: UTF-8. Since encoding problems can be weird and difficult to deal with, we made the choice to support only one encoding. UTF-8 allows you to display all characters for all languages.
Be sure to be consistent with UTF-8 usage throughout your application:
- Edit all your source files as UTF-8
- Define proper encoding headers in HTTP
- Set your HTML meta tags to UTF-8
- If you use a database, configure it to use UTF-8, and always connect to it using UTF-8
Note
The UTF-8 encoding issue is the reason why most of the Play configuration files, even though they are Java properties files, are not named *.properties. Java imposes the requirement that properties files must be encoded with iso-8859-1. Play configuration files must be UTF-8 encoded. Need we say more?
Externalize your messages
To support i18n you have to externalize all messages in your application.
Create a file named messages in the application’s conf/ directory. This file is really just a Java properties file.
hello=Hello!
back=Back
Then you can define a specific message file for each language used in your application. Just add the ISO language code as a file extension.
For example, the message file containing the corresponding French translations is conf/messages.fr:
hello=Bonjour!
back=Retour
Define languages supported by the application
In the conf/application.conf file, define a list of supported languages:
application.langs=fr,en,ja
On the first request from a new user, Play will guess the default language to use. It does so by parsing the HTTP Accept-language header. It will then save the chosen language in a PLAY_LANG cookie. So the next request will use the same language.
From your application code your can retrieve the current language for the user by accessing the play.i18n.Lang object:
String lang = Lang.get();
If you want to permanently change the user language, use the change() method:
Lang.change("ja");
The new value will be saved back to the user’s language cookie.
Retrieve localized messages
From the application code, you can retrieve messages defined in message files. From Java, use the play.i18n.Messages object.
public static void hello() {
renderText(Messages.get("hello"));
}
We support message formatting through the standard Java formatting syntax. You can also define dynamic content in your messages:
hello=Hello %s!
and
public static void hello(String user) {
renderText(Messages.get("hello", user));
}
From a template you can use the special &{…} syntax to display localized messages:
<h1>&{'hello'}</h1>
or using dynamic content:
<h1>&{'hello', params.user}</h1>