Internationalization (i18n) - geetools/geemvc GitHub Wiki

geeMVC supports the use of standard Java ResourceBundles for Internationalization (i18n). To make it easier for web developers to extend the Java MVC framework with their own custom resource bundles, geeMVC will search for the following files:

Location	Example
Default geeMVC resource bundle	locale/_messages.properties
Global application resource bundle	locale/messages.properties
Application controller resource bundle	locale/account-messages.properties

In a Maven project the locale folder typically resides in the PROJECT_ROOT/src/main/resources directory. After a successful build they should end up in either PROJECT_ROOT/target/classes or in the /WEB-INF/classes directory of your web application.

The resource bundles mentioned above do not contain any language information. When specifying our messages in a particular language we need to add the language and optionally the country to the filename. For example:

Location	Example
Messages in English	locale/messages_en.properties
Messages in English for the US	locale/messages_en_US.properties
Messages in English for Great Britain	locale/messages_en_GB.properties
Messages in German	locale/messages_de.properties
Messages in German for Switzerland	locale/messages_de_CH.properties
Account messages in German for Switzerland	locale/account-messages_de_CH.properties

geeMVC will attempt to find the translated text in a specific order, starting with the most specific file, e.g. account-messages_en_US.properties and finishing at _messages.properties.

To ensure that there is always a text message available, it is advisable to have a default resource bundle to fallback to. So if the default language is English, then the filename would be »messages.properties« and not »messages_en.properties«. Any additional language files would of course contain the locale information.

Retrieving and Displaying i18n Messages

There are two recommended ways of getting messages from resource bundles, depending on where you need them.

Context	Method	Example
JSP or template	Taglib	<h:message key="welcome.message" p1="Tom" />
Controller	Messages object	messages.getString("welcome.message", "Tom");

Taglib

The taglib is fairly straightforward if you have worked with the technology before. The possible parameters are:

Attribute Name	Type	Mand.	Description	Example
key	String	Y	The message key to retrieve from the resource bundle.	key="welcome.message"
locale	java.util.Locale	N	The locale in which the message should be displayed in.	locale="${locale}"
lang	String	N	The language in which the message should be displayed in. Can be combined with the country attribute and should be used as an alternative to "locale".	lang="en"
country	String	N	See "lang".	country="US"
p[NUMBER]	Object	N	Enables you to pass any number of parameters. Just add the index number to the p (parameter) keyword. The index starts at 1.	p1="Tom" p2="Smith"

Example JSP Page

<!-- /WEB-INF/jsp/pages/account/update-success.jsp -->

<%@ taglib uri="http://geetools.com/jsp/geemvc/html" prefix="h"%>

<h1><h:message key="account.success.title" /></h1>

<p><h:message key="account.success.message" p1="${account.forename}" p2="${account.surname}" /></p>

Messages Object

Sometimes you need to access the resource bundles from within your controller. You can do this by injecting the Messages object as follows:

    @Request(path = "/welcome-message")
    public String showWelcomeMessage(@Param("id") String id, Messages messages) {
        if (id != null) {
            return messages.getString("welcome.message", "Tom");
        } else {
            return messages.getString("account.not.found");
        }
    }

In the above example geeMVC will automatically locate the correct locale and for you, although you could decide to provide your own. By default geeMVC will throw an error when a message cannot be found in any of the available bundles. You can turn this off however with the parameter failQuietly="true".