ngbinh / sbt-i18n

An sbt plugin to transform your i18n bundles into Scala code

sbt i18n

Sbt i18n is a very simple internationalization tools, that reads resources bundles files in properties files, json, or HOCON format and generate Scala code.

A configuration file like this

en = {
  key1 = a text
  key2 ="a parametrized text {0}"
  subsection {
    key3 = some text
  }
}

will generate the following Scala code

object Bundle {

  abstract class I18N {
    def key1: String
    def key2(x0: String): String
    
    abstract class Subsection {
      def key4: String
    }
    
    def subsection: Subsection
  }

  object en extends I18N {
    val key1 = """a text"""
    def key2(x0: String): String = java.text.MessageFormat.format("""a parametrized text {0}""", x0)
   
    object subsection  extends Subsection {
       val key4= """2"""
    }
}
}
     

The motivation here is to depart from the traditional way of doing "stringly typed" message fetching and to have a stronger coupling between the application code and the message translations. Having your build break when a translation is missing or on a faulty pattern is something you may want.

Usage

This plugin requires sbt 1.0.0+.

Add the following to project/plugins.sbt:

addSbtPlugin("tech.ant8e" % "sbt-i18n" % "0.2")

Write a config file in src/main/i18n/xxx.conf.

en = {
  msg1 = a text
  msg2 ="a parametrized text {0}"
}

fr = {
  msg1 = un texte
  msg2 ="un texte paramétré {0}"
}

And access your translations in your Scala code

val msg1 = org.example.i18n.Bundle.en.msg1
val msg2 = org.example.i18n.Bundle.en.msg2("hello")

The scala Bundle will be generated by default in package org.example.i18n this can of course be configured:

In oder to change the output package set i18nBundlePackageName := "org.myorganisation.i18n" in build.sbt.

Input files

the plugin will parse all files within src/main/i18n with the Typesafe config library and build one single config hierarchy that will be the source of the code generation. The top level keys are assumed to be language selectors.

Caveats

The plugin will merge multiple files will no guarantee about order or conflict resolution. When two or more files defines the exact same configuration path it is undefined who will "win".

Scala Code

Overview

The plugin will generate one scala object named Bundle in the specified package.

This object contains one abstract class named I18N that defines the structure of each language.

For each language (or top level key), an object, named like the key, implementing the I18N class is generated.

Simple message will appear as val and parametrized messages as methods.

Parametrized messages

A message that is a valid java.text.MessageFormat pattern will be generated as a method. See MessageFormat documentation for details about the supported patterns.

During generation the plugin will infer the correct argument type from the pattern. number will have type Double by default and Long when the integer format style is selected. Date and time will have type java.util.Date. choice being a number format will lead to a Double. By default (when no format is specified), the argument will be of type String.

Missing keys

The structure of a bundle is a merge of all the keys of all the languages. Should a key not be defined in a specific language, it will be generated as ??? [key] ???.

Contribution policy

Contributions via GitHub pull requests are gladly accepted from their original author. Along with any pull requests, please state that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.

License

This code is open source software licensed under the Apache 2.0 License.