Internationalization

Internationalizing Scala strings

We use Play's i18n framework for translations.

To translate a string, define a key/message in conf/messages (in alphabetical order, please!) and then call play.api.i18n.Messages(key, arg1, arg2, ...) from your Scala code.

Note: there must be an implicit play.api.i18n.Lang variable in scope. (A Request will do, since there's an implicit conversion.)

We add some sugar on top of that:

• From views, you may call t(key, arg1, arg2, ...) (see app/views/Magic.scala)
• You may call val m = views.ScopedMessages("some.sub.path"). Then when you call m("end", arg1, arg2, ...), that's like calling t("some.sub.path.end", arg1, arg2, ...).

Strings use Java's horrid MessageFormat. If you're confused about pluralization, you're completely sane; search for {0 in conf/messages and mimic existing examples. The vastly confusing documentation for MessageFormat is here: http://docs.oracle.com/javase/7/docs/api/java/text/MessageFormat.html.

Internationalizing JavaScript strings

You must pass translation strings through the template, in the main() call. Let's phrase that in two other ways:

• You cannot pass translation strings in sub-templates.
• You must include all potential translation strings in the enclosing template (the one which calls main()).

To include them, put something like this in your template:

@jsMessageKeys = @{Seq(
  "my.key.that.js.will.translate"
})

And add jsMessageKeys=jsMessageKeys to the parameters of main().

Then, in CoffeeScript (or JavaScript), you may call this:

translated_string = i18n('my.key.that.js.will.translate')

The i18n variable is a global.

See app/views/JsMessages.scala and app/views/main.scala.html for implementation details.

Warning: some particularly confusing translation strings may trigger bugs in our JavaScript MessageFormat implementation. If this happens, the proper course of action is to correct the JavaScript. There's not much point in striving for a perfect MessageFormat implementation (because the format is so complex, and it has changed between Java API versions); we just need something that's Good Enough.