Skip to content

Latest commit

 

History

History
155 lines (113 loc) · 4.52 KB

README.md

File metadata and controls

155 lines (113 loc) · 4.52 KB
Raw

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.