Skip to content
Scala compiler plugin that acts like GNU xgettext command to extract i18n strings in Scala source code files to Gettext .po file
Scala
Branch: master
Clone or download
Latest commit 8a2b753 May 29, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dev Update release doc Jan 22, 2019
project
src/main Handle double quotes and newlines (#21) May 29, 2019
.gitignore
CHANGELOG.rst Release 1.5.3 May 29, 2019
MIT-LICENSE First commit Jan 4, 2013
README.rst Do not support Scala 2.10 any more (too old in 2019) Jan 22, 2019
build.sbt
poedit.png

README.rst

poedit.png

This is a Scala 2.11, and 2.12 compiler plugin that acts like GNU xgettext command to extract i18n strings in Scala source code files to Gettext .po file, when you compile the Scala source code files.

More info on Scala compiler plugin: http://www.scala-lang.org/node/140

Presentation: I18nize Scala programs à la gettext

Discussion group: https://groups.google.com/group/scala-xgettext

For Play: https://github.com/georgeOsdDev/play-xgettext

Usage

This plugin can be used by frameworks like Xitrum to add i18n feature to them. For an example, see this SBT project.

Create I18n trait or class

In your Scala source code, you need to mark the strings you want to extract by using a trait or class that has these method signatures:

t(singular: String): String
tn(singular: String, plural: String, n: Long): String

tc(context: String, singular: String): String
tcn(context: String, singular: String, plural: String, n: Long): String

The methods can also be:

t(singular: String, args: Any*): String
tn(singular: String, plural: String, n: Long, args: Any*): String

tc(context: String, singular: String, args: Any*): String
tcn(context: String, singular: String, plural: String, n: Long, args: Any*): String

That is, only the first arguments (1 first argument for t, 3 first arguments for tn etc.) are required, all the following arguments are ignored (like params above).

You can use Scaposer to implement the methods above. See example.

Then in your Scala source code, use them like this:

t("Hello World")
t("Hello %s").format("World")

t("%,.3f").format(1234.5678)                                // => 1,234.568
t("%,.3f").formatLocal(java.util.Locale.FRANCE, 1234.5678)  // => 1 234,568

If you have more than one placeholder:

// 1$ and 2$ are placeholders
t("%1$s says hello to %2$s, then %2$s says hello back to %1$s").format("Bill", "Hillary")

// {0} and {1} are placeholders
java.text.MessageFormat.format(t("{0} says hello to {1}, then {1} says hello back to {0}"), "Bill", "Hillary")

Important: The arguments ``singular``, ``plural``, and ``context`` MUST be literal constant string, like in the above examples. Otherwise exception will be thrown during compilation. Alternatively, one can add the option ``ignoreNonLiteralStrings:true`` to ignore those cases instead of throwing an exception

Extract i18n strings to .pot file

To extract i18n strings like "Hello World" in the above snippet:

  • Clean your Scala project to force the recompilation of all Scala source code files.
  • Create an empty i18n.pot file in the current working directory. It will be filled with i18n string resources extracted from compiled Scala source code files.
  • Compile your Scala project with -P:xgettext:<i18n trait or class> option. Example: -P:xgettext:xitrum.I18n.

If you use SBT, build.sbt should look like this:

...
autoCompilerPlugins := true
addCompilerPlugin("tv.cntt" %% "xgettext" % "1.5.1")
scalacOptions += "-P:xgettext:xitrum.I18n"
...

Copy or rename the .pot file to a .po file, and translate the strings in it to the language if want. "t" in ".pot" means "template".

You can use plain text editor to edit the .po file, or you can use Poedit. Poedit is very convenient, it can merge new .pot file to existing translated .po file.

Content of the .pot file is sorted by msgid, so that it's easier too see diffs between versions of the .pot/.po file.

Configure i18n marker method names

t, tn, tc, and tcn above are the defaults.

If you want to use other names, you can change them to, for example, tr, trn, trc, and trcn, by adding options to Scala compiler:

scalacOptions ++= Seq(
  "xitrum.I18n", "t:tr", "tn:trn", "tc:trc", "tcn:trcn"
).map("-P:xgettext:" + _)

If you skip an option, its default value will be used.

Multiple marker method names

Multiple marker methods for t can be configured like this:

scalacOptions ++= Seq(
  "xitrum.I18n", "t:tr", "t:notr"
).map("-P:xgettext:" + _)

Similar for tn, tc, and tcn.

With this feature you can, for example, create an i18n library that can display both original strings and translated strings.

Explicitly specifying the plural forms for the template

Some translation software require the plural forms formula used in the template to be explicitly stated.

scalacOptions ++= "-P:xgettext:sourceLang:en"

Or:

scalacOptions ++= "-P:xgettext:rawPluralForm:<nplurals=#; formula>"

Using one of these options will cause the template to have a Plural-Forms header. Many languages are supported, but see src/main/scala/scala/PluralForms.scala for all of the languages supported and examples of the common formulas.

Omitting this option will omit a Plural-Forms header from the template output.

Load .po file

Use Scaposer.

You can’t perform that action at this time.