15 Internationalization - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari
Version: 2.5.0
Table of Contents
15 Internationalization
Grails supports Internationalization (i18n) out of the box by leveraging the underlying Spring MVC internationalization support. With Grails you are able to customize the text that appears in a view based on the user's Locale. To quote the javadoc for the Locale class:A Locale object represents a specific geographical, political, or cultural region. An operation that requires a Locale to perform its task is called locale-sensitive and uses the Locale to tailor information for the user. For example, displaying a number is a locale-sensitive operation--the number should be formatted according to the customs/conventions of the user's native country, region, or culture.A Locale is made up of a language code and a country code. For example "en_US" is the code for US English, whilst "en_GB" is the code for British English.
15.1 Understanding Message Bundles
Now that you have an idea of locales, to use them in Grails you create message bundle file containing the different languages that you wish to render. Message bundles in Grails are located inside thegrails-app/i18n directory and are simple Java properties files.Each bundle starts with the name messages by convention and ends with the locale. Grails ships with several message bundles for a whole range of languages within the grails-app/i18n directory. For example:
- messages.properties
- messages_da.properties
- messages_de.properties
- messages_es.properties
- messages_fr.properties
- ...
messages.properties for messages unless the user has specified a locale. You can create your own message bundle by simply creating a new properties file that ends with the locale you are interested. For example messages_en_GB.properties for British English.
15.2 Changing Locales
By default the user locale is detected from the incomingAccept-Language header. However, you can provide users the capability to switch locales by simply passing a parameter called lang to Grails as a request parameter:/book/list?lang=es
15.3 Reading Messages
Reading Messages in the View
The most common place that you need messages is inside the view. Use the message tag for this:<g:message code="my.localized.content" />messages.properties (with appropriate locale suffix) such as the one below then Grails will look up the message:my.localized.content=Hola, Me llamo John. Hoy es domingo.
<g:message code="my.localized.content" args="${ ['Juan', 'lunes'] }" />my.localized.content=Hola, Me llamo {0}. Hoy es {1}.Reading Messages in Controllers and Tag Libraries
It's simple to read messages in a controller since you can invoke tags as methods:def show() {
def msg = message(code: "my.localized.content", args: ['Juan', 'lunes'])
}g.:def myTag = { attrs, body ->
def msg = g.message(code: "my.localized.content", args: ['Juan', 'lunes'])
}15.4 Scaffolding and i18n
Grails scaffolding templates for controllers and views are fully i18n-aware. The GSPs use the message tag for labels, buttons etc. and controllerflash messages use i18n to resolve locale-specific messages.The scaffolding includes locale specific labels for domain classes and domain fields. For example, if you have a Book domain class with a title field:class Book {
String title
}book.label = Libro book.title.label = TÃtulo del libro
label as part of the key other than it's the convention used by the scaffolding.