Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
March 10, 2016 17:19
March 18, 2016 13:55
March 18, 2016 13:55
March 10, 2016 17:19
December 3, 2014 19:02
March 18, 2016 13:55
March 18, 2016 13:55
March 10, 2016 17:19
March 10, 2016 17:19

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.x and 3.x introduced new APIs and aren't backward compatible, you must use the following versions of this plugin:

i18n-asset-pipeline version required for
0.x asset-pipeline up to version 1.9.9
1.x asset-pipeline version 2.0.0 or higher
2.x Grails 3.x


To use this plugin you have to add the following code to your build.gradle:

buildscript {
    dependencies {
        classpath 'org.amcworld.plugins:i18n-asset-pipeline:2.0.0'

dependencies {
    runtime 'org.grails.plugins:i18n-asset-pipeline:2.0.0'

The first dependency declaration is needed to precompile your assets (e. g. when building a WAR file). The second one provides the necessary <asset:i18n> tag and compiles the assets on the fly (e. g. in development) mode.


i18n-asset-pipeline uses special files in your asset folders (we recommend grails-app/assets/i18n) 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.:


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 import statements and 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:


Then, you should have the same set of files in e. g. grails-app/assets/i18n:

  • 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/i18n (the leading underscore prevents the i18n file to be compiled itself):

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

# Add your messages codes here:

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

# messages.i18n
# Client-side i18n, English messages.

@import _messages

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

@import _messages

# messages_es.i18n
# Client-side i18n, Spanish 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 representing 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).


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


This plugin was written by Daniel Ellermann (AMC World Technologies GmbH).


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


An asset-pipeline plugin for client-side i18n.







No packages published