Documentation

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

Internationalization

Internationalisation (I18N) is a means of adapting your application to different languages to allow for regional differences. Follow these steps to enable internationalisation 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:

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.

You can use language/country pair if you want to distinguish between variant, such as en_US and en_GB, or zh_CN and zh_TW. However, be aware that some users may only expose a language and not a country in their Accept-language. For that reason, you should always provide the “naked” language (e.g. en).

For example, if most of your users are from US but you also want to support British English, it is recommended to use simply “en” of US English and “en_GB” for British English.

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.

Define date format according to your locale

To set the default date format to use, edit your application.conf and set the following property:

date.format=yyy-MM-dd
    date.format.fr=dd/MM/yyyy

Please note that the language fr in the application.conf must be enabled as well (see above):
bc. application.langs=fr,en

This property affects how the dates are rendered in the templates using the ${date.format()}.
It also set the default date format when binding a date parameter.

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>

Continuing the discussion

Next: Cache.