Messages and internationalization in Play 2.4.x

Table of contents

Reading Time: 3 minutes

In this blog we would discuss about Messages and internationalization in Play Framework which would drive us through the implementation and testing of the Play MessagesAPI.

Messages and internationalization

Play supports Internationalization (i18n) out of the box by leveraging the underlying internationalization support. With Play you are able to customize the text that appears in a view based on the user’s Locale.

Specifying languages supported by your application

A valid language code is specified by a valid ISO 639-2 language code, optionally followed by a valid ISO 3166-1 alpha-2 country code, such as fr or en-US.

To start you need to specify the languages supported by your application in the conf/application.conf file:

play.i18n.langs = [ "en", "en-US", "fr" ]

File Externalization

You can externalize messages in the conf/messages.xxx files.

The default conf/messages file matches all languages. Additionally you can specify language-specific message files such as conf/messages.fr or conf/messages.hi.

You can then retrieve messages using the play.api.i18n.Messages object:

val title = Messages("home.title")

All internationalization API calls take an implicit play.api.i18n.Messages argument retrieved from the current scope. This implicit value contains both the language to use and (essentially) the internationalized messages.

The simplest way to get such an implicit value is to use the I18nSupport trait. For instance you can use it as follows in your controllers:

import play.api.i18n.I18nSupport
class AppController(val messagesApi: MessagesApi) extends Controller with I18nSupport {
  // ...

The I18nSupport trait gives you an implicit Messages value as long as there is a Lang or a RequestHeader in the implicit scope.

Note: If you have a RequestHeader in the implicit scope, it will use the preferred language extracted from the Accept-Language header and matching one of the MessagesApi supported languages. You should add a Messages implicit parameter to your template like this: @()(implicit messages: Messages).

Note: Also, Play “knows” out of the box how to inject a MessagesApi value (that uses the DefaultMessagesApi implementation), so you can just annotate your controller with the @javax.inject.Inject annotation and let Play automatically wire the components for you.

Implementation of Messages Format

Messages are formatted using the java.text.MessageFormat library. For example, assuming you have message defined like:

app.name=The application {0} is running on port {1}.

You can then specify parameters as:

Messages("app.name", "Message Example", 9000)

The output of above code is:

The application Message Example is running on port 9000.

Use of apostrophes

Since Messages uses java.text.MessageFormat, please be aware that single quotes are used as a meta-character for escaping parameter substitutions.

For example, if you have the following messages defined:

info.error=You aren''t logged in!

example.formatting=When using MessageFormat, '''{0}''' is replaced with the first parameter.

you should expect the following results:

Messages("info.error") == "You aren't logged in!"

Messages("example.formatting") == "When using MessageFormat, '{0}' is replaced with the first parameter."

Retrieving supported language from an HTTP request

You can retrieve the languages supported by a specific HTTP request:

def index = Action { request =>
  Ok("Languages: " + request.acceptLanguages.map(_.code).mkString(", "))
}

Testing Messages API

At the time of testing we can create a new object of DefaultMessagesApi and then pass it to the appropriate Controller/Services/Utils

new DefaultMessagesApi(Environment.simple(), app.configuration, new DefaultLangs(app.configuration))

Now we know about Play MessagesAPI implementations. So let’s start enjoy with i18n messages and Play easily. If you have any question then feel free to comment on the same 🙂 Stay tuned.