How to localise a Play framework 1.0 web application

There are two separate steps to perform: internationalisation and localisation. Both are mostly about text.

Internationalisation, in programming terms, is a refactoring to remove locale-specific code from the application code. In a web application, this is almost entirely about replacing user-interface text in view templates with references to messages. It also includes formatting non-text data types: dates, currency and other numbers.

Localisation is making a locale-specific version of an application. If the application is internationlised, this means having one or more selectable locale-specific versions. In a web application, this localisation is mostly about translating the user-interface text into the chosen natural language. Language selection is typically a combination of language preferences set in the web browser, and a language selection user-interface in the application itself.

In practice, the two steps go together: you both internationalise and localise one part of the application at a time.

The rest of this article covers how to localise the 'Yet Another Blog Engine' example application, used in the Play tutorial. The starting point is the code in the Play distribution’s samples-and-tests/yabe directory. The goal is to fully internationalise the application, and add several language localisations.

To get started, see the instructions in the Play manual’s Setting up i18n cookbook, which covers the basic cases. First, edit conf/application.conf and uncomment (in the default configuration file) or add a line with three supported languages:

If you load a page in the application now, the Play console will show three warnings because you do not have any locale-specific message files yet:

The warnings above mean that you need to replace the existing conf/messages file with one message file for each language:

At this point we encounter the first improvement over the normal Java way of doing things. These files use the same syntax as Java properties files, but they are not properties files because they must use UTF-8 encoding. Java Properties, on the other hand, specifies ISO-8859-1 'Latin-1' character encoding for streaming to and from text files.

Being able to use UTF-8 message files is a big deal for language localisation, because it means that you can write localised language messages in 'plain text'. For example, this means that for a Greek localisation, instead of:

you can use Greek letters instead of those Unicode character escapes:

For the rest of this tutorial, code samples will either define messages in one of these files, or show internationalised mark-up in one of the HTML view templates.

The simple case is a text string that does not change, and that is not interrupted by other markup. For example, the first such text in the yabe/app/views/main.html template, in the tools list:

To internationalise this, we replace the text with a message look-up, using the &{'key'} syntax:

To add the localisations, add the corresponding line in each of the three message files. In conf/messages.en

In conf/messages.nl

In conf/messages.fr

The message key can be anything you like; in this example I have used a key to indicate the location views/main.html#tools

Once you have saved these changes, you can see the different language versions in your web browser by changing the setting that results in a different Accept-Language HTTP request header. In Firefox, select Preferences » Content » Languages » Choose…, add French [fr] and Dutch [nl] if they are not already in the list, change which one is at the top of the list, close the dialogue box and reload the page.

If you use that link to log in to the blog’s 'admin' pages, you can access lists of posts, tags, comments and users. These pages are provided by the CRUD module. For each of these pages, the title (light pink) and the column headers are terms from the application’s model, i.e. JavaBean class and property names.

The CRUD module internationalises these names using the JavaBean class or property name as the message key, which means you can localise them with messages such as the following.

In conf/messages.nl

In conf/messages.fr

You will notice that this does not change the rounded purple navigation links:

Those are defined views/admin.html which you can internationalise to use the same localisations simply by surrounding the existing text with &{'…'} as follows:

As well as simple messages, our application includes messages that contain a variable, such as Posts tagged with Play

To localise a message that contains a single parameter, use a Java format string to insert the parameter value in the message:

and in the template, add the parameter like this:

When a message contains multiple parameters, add an index to the format string to allow for different word order in another language:

… with a list in the template:

In this example, we would also like to use the correct plural form for the word 'post', so make that word a parameter too:

… and use the pluralize extension in the template

Note that we have to use messages.get to look up the localised singular and plural.

Play module localisation works the same was as localisation within your application. This application uses the CRUD and Secure modules, which means that we must localise the messages in play/modules/crud/conf/messages and play/modules/secure/conf/messages that our application uses.

In conf/messages.nl

In conf/messages.fr

Of course, once you have done this it is also a good idea to contribute the localisations back to the module.

In 2008 I was localising an application that was built using Seam 2 and JavaServer Faces (JSF) 1.2. There turned out to have three special cases that were awkward to implement in JSF, which I reported as javaserverfaces-spec-public issue 517.

All three cases turn out to be straightforward in Play.

The first case happens when you want to use a phrase with a parameter in an attribute value in the template, such as:

This is a problem in JSF, because you would normally use an XML tag to perform the parameter replacement, which you cannot do in an attribute value. The Play syntax simply avoids this problem, and you can just do:

The second case is when you want to format a value, such as a date, for use as a message parameter in a phrase like By Bob on 2009-06-14. Again, the problem in JSF is caused by having to an XML tag to format the value, while needing to be able to use the result in an XML attribute value. In Play the formatting extensions do not get in the way of the message parameter syntax, so you can do:

You can, of course, localise the format pattern as well:

The third case typically occurs when you want part of a localised message to be a hyperlink, as in the message Log in to write something. This is a problem in JSF because the hyperlink is a JSF component that is rendered in a way that means the link’s mark-up cannot be in the message file. Play on the other hand, lets you use plain HTML in your templates, so you can just put the mark-up in your message with a parameter for the URL:

Our application was using the <a href="@{Admin.index()}"> syntax in the hyperlink to get the framework to generate the URL based on the routes file. To do this in the message parameter, do:

The end result of applying the above steps is a localised version of the 'Yet Another Blog Engine' example that works in English, Dutch and French: yabe-l10n-1.0.2.zip

The 'Yet Another Blog Engine' admin interface in Dutch (above) and French (below).