An SBT plugin to check Play messages files for potential problems and generate a references object.

This plugin can:

• Check for duplicate message keys in the messages files
• Check for missing keys in the language specific messages files
• Check for message keys not in the default messages file
• Check for unused message keys
• Generate a references object, which can:
  • Provide simpler more accurate access to message keys
  • Convert message key typing mistakes into a compilation error
  • Convert removed message usage into a compilation error
  • Convert changed message keys not updated into a compilation error

Can be used with the Play Framework 2.3.x.

Requires SBT 0.13.5.

Generates code in Scala or Java.

Add the plugin to project/plugins.sbt. For example:

addSbtPlugin("com.github.evanbennett" % "sbt-play-messages" % "1.1.0-RC1")

Your project's build needs to enable a Play SBT plugin. For example in your build.sbt:

for Scala:

lazy val root = (project in file(".")).enablePlugins(PlayScala)

or for Java:

lazy val root = (project in file(".")).enablePlugins(PlayJava)

To enable seemless usage in your Twirl templates, you could add the following line into your build.sbt:

TwirlKeys.templateImports := (TwirlKeys.templateImports.value.diff(Seq("play.api.i18n._")) ++ Seq("conf.Messages", "play.api.i18n.Lang"))

The checking and generation functionality is automatically run whenever your project is compiled. You can also manually run the functionality using the following:

Import the generated object, instead of the Play 'Messages' object, and then usage is very similar to usage without this plugin.

Note: Methods are provided on the generated object, which allow existing code using the Play Messages object to compile.

Importing the generated object:

In a Scala file you would probably:

import play.api.i18n.Messages // Or with the wildcard '_'

and in a Java file you would probably:

import play.i18n.Messages; // Or with the wildcard '*'

To use the generated object, replace this with:

import conf.Messages

With a 'messages' file containing:

WELCOME=Welcome to our system.
ERRORS.INCORRECT_LENGTH={0} is the incorrect length.

Scala recommended usage:

Standard Play 'Messages' usage (which can still be used):

Messages("WELCOME")
Messages("ERRORS.INCORRECT_LENGTH", 2)

Equivalent usage with the plugin:

Messages.WELCOME()
Messages.ERRORS.INCORRECT_LENGTH(2)

You also have the option of using part of the key literally and part variably (obviously, the variable part could not exist):

val error = "INCORRECT_LENGTH" // Generated dynamically from some code

Messages.ERRORS(error, 2)

Java recommended usage:

Standard Play 'Messages' usage (which can still be used):

Messages.get("WELCOME");
Messages.get("ERRORS.INCORRECT_LENGTH", 2);

Equivalent usage with the plugin:

Messages.WELCOME.get();
Messages.ERRORS.INCORRECT_LENGTH.get(2);

You also have the option of using part of the key literally and part variably (obviously, the variable part could not exist):

String error = "INCORRECT_LENGTH"; // Generated dynamically from some code

Messages.ERRORS.get(error, 2);

The following settings can be modified by adding the provided line to your build.sbt file.

The requiring of a default messages file can be disabled by adding the following to your build configuration:

PlayMessagesKeys.requireDefaultMessagesFile := false

Checking that the 'application.langs' configuration matches the messages files can be disabled by adding the following to your build configuration:

PlayMessagesKeys.checkApplicationLanguages := false

Duplicate key checking can be disabled by adding the following to your build configuration:

PlayMessagesKeys.checkDuplicateKeys := false

Key consistency checking across multiple messages files can be disabled by adding the following to your build configuration:

PlayMessagesKeys.checkKeyConsistency := false

You can configure some messages files to be skipped by adding:

PlayMessagesKeys.checkKeyConsistencySkipFilenames := Set("messages.en-AU")

Key usage checking throughout your application code can be disabled by adding the following to your build configuration:

PlayMessagesKeys.checkKeysUsed := false

You can configure some keys to be ignored by adding:

PlayMessagesKeys.checkKeysUsedIgnoreKeys := Set("")

You can use regular expressions to configure keys to be ignored. For example, to ignore all keys starting with "PERMISSIONS", you could add:

PlayMessagesKeys.checkKeysUsedIgnoreFilenames := Set("PERMISSIONS.+")

Key references object generation can be disabled by adding the following to your build configuration:

PlayMessagesKeys.generateObject := false

You can configure the package and name of the object that will contain the key references by adding:

PlayMessagesKeys.generatedObject := "base.Messages"

This code is licensed under the BSD 3-Clause License.