I18n asset-pipeline plugin

The Grails plugin i18n-asset-pipeline is an asset-pipeline plugin that generates a JavaScript file with localized texts which can be used for client-side i18n.

For more information on how to use asset-pipeline, visit asset-pipeline project page.

Version information

Because asset-pipeline 2.0.0 introduced a new API and isn't backward compatible, you must use the following versions of this plugin:

• for asset-pipeline up to version 1.9.9 use version 0.9.x of this plugin
• for asset-pipeline version 2.0.0 or higher use version 1.0.0 or higher of this plugin

Usage

i18n-asset-pipeline uses special files in your standard grails-app/assets/javascripts folder with extension '.i18n'. The names of these files must contain a language specification separated by underscore, e. g. messages_de.i18n or messages_en_UK.i18n. Files without a language specification (e. g. messages.i18n) are files for the default locale. These files mainly contain message codes that are resolved to localized texts.

The plugin generates a JavaScript file, that contains a function named $L which can be called to obtain the localized message by a given code, e. g.:

$(".btn").text($L("default.btn.ok"));

If you have a message with a placeholder, you can give the value to apply as an additional argument:

$(".message").text($L("flash.message", "21"));

With multiple placeholders, you can give your values either as single arguments or as an array:

$(".message").text($L("flash.message", "foo", "21"));
$(".message").text($L("flash.message", ["foo", "21"]));

I18n file syntax

Each i18n file must be defined according to the following rules:

• Files are line based.
• Lines are trimmed (i. e. leading and terminating whitespaces are removed).
• Empty lines and lines starting with a hash # (comment lines) are ignored.
• Lines starting with @import url are resolved by importing file url, processing it according to these rules, and replacing the @import statement by its content. The import file may contain further import statements, even circular ones. You may omit file extension .i18n in url.
• All other lines are treated as messsage codes which are translated to the required language. Comments after message codes are not allowed.

Each i18n file may contain asset-pipeline require statements to load other assets such as JavaScript files. ATTENTION! Don't use require to load other i18n files because they will not be processed correctly. Use the @import declaration instead.

Typical file structure

Typically, you have one i18n file for each language in the application. Given, you have the following message resources in grails-app/i18n:

• messages.properties
• messages_de.properties
• messages_en_UK.properties
• messages_es.properties
• messages_fr.properties

Then, you should have the same set of files in grails-app/assets/javascripts:

• messages.i18n
• messages_de.i18n
• messages_en_UK.i18n
• messages_es.i18n
• messages_fr.i18n

Normally, you would have to declare the same set of message codes in each file. To DRY, add a file _messages.i18n to grails-app/assets/javascripts:

#
# _messages.i18n
# List of message codes that should be available on client-side.
#

# Add your messages codes here:
default.btn.cancel
default.btn.ok
contact.foo.bar

Then, you can import this file in all other files, e. g. in messages_de.i18n:

#
# messages_de.i18n
# Client-side i18n, German messages.
#

@import _messages

Including localized assets

In order to include a localized asset you can either use an asset-pipeline require directive or the tag <asset:i18n>. The tag supports the following attributes:

• locale. Either a string or a java.util.Locale object reprenting the locale that should be loaded. This attribute is mandatory.
• name. A string indicating the base name of the i18n files to load (defaults to messages).

Examples:

<asset:i18n locale="en_UK" />

<asset:i18n name="texts" locale="${locale}" />

Author

This plugin was written by Daniel Ellermann.

License

This plugin was published under the Apache License, Version 2.0.