Internationalization

Mentawai supports internationalization (i18n) out of the box. It makes it very easy for your web application to support multiple languages. Another very useful feature is that all i18n files will automatically reload if changed.

Placing your text in an i18n file:

An i18n file is just a properties file you place inside the WEB-INF/i18n folder (or webapp/i18n maven projects). The name must be master_locale.i18n. For example, the i18n file master_en_US.i18n might have the following contents:

#############################################################
# Example of an i18n file: WEB-INF/i18n/master_en_US.i18n    
#############################################################

# General text
title = The Java Community portal!

# For the /jsp/index.jsp page
index.hello = Hello
index.welcome = Welcome to the online Java community!

# For the UserAction
UserAction.required_field = Required Field!
UserAction.bad_username = Invalid username!
UserAction.bad_email = Invalid email!

NOTE: Because you will be maintaining all your text inside a single file, you should use prefixes to organize the keys. But as you will see below, you don't need to pass the prefixes when getting the texts.

Getting text inside an action:

Validation and dynamic messages automatically support i18n and you can pass the text key to its methods in the action.

// Validation:
val.requiredFields("required_field", "username", "password", "email", "groupId", "languageId"); // varargs for field names
val.requiredLists("required_field", "groupId", "languageId"); // varargs for field names
val.add("username", RegexRule.getInstance(username_regex), "bad_username"); // validates using any regex

// Adding field erros by hand:
addError("bad_email", "email"); // UserAction.bad_email will be loaded, assuming you are inside UserAction.class

// Dynamic messages:
addMessage("added_ok"); // UserAction.added_ok
addError("db_error"); // UserAction.db_error

And you can get any text inside the action with the getLocalizedText method:

String localizedMsg = getLocalizedText("bad_email");

String localizedTitle = getLocalizedText("title", true); // true => noPrefix => do not use the prefix

NOTE: As you can see the prefix is inferred from the action class so you don't need to include in your keys.

Showing text inside a JSP page:

<%@ page contentType="text/html; charset=UTF-8"%>
<%@taglib prefix="mtw" uri="http://www.mentaframework.org/tags-mtw/"%>

<!-- First declare you want to use i18n and specify the prefix -->
<mtw:useI18N prefix="index" />

<!-- The key that will be resolved is index.hello from the i18n file -->
<mtw:i18n key="hello" />

<!-- If you want to bypass the prefix, in other words, the a general key that does not have a prefix -->
<mtw:i18n key="title" noPrefix="true" />

Localizing images and other files:

You can localize images by dynamically changing their path through mtw:i18nDir tag:

<!-- If the locale is pt_BR, the path will be /images/pt_BR/hello.gif -->
<img src="/images/<mtw:i18nDir />/hello.gif" />

Setting the locale for an authenticated user:

You may want to set the locale of a user when he logs in the web application. He may have chosen his language when he registered and this information is now saved in the database together with his profile. To set the locale of a user, do the following in the login action:

         setSessionObj(u);  // <==== Note: You must authenticate the user BEFORE setting his information in the session.

         Locale theUserLocale = u.getLocale();         
                  
         setSessionLocale(theUserLocale); // <== From now on, until the user logs out, the web application will use this locale

Forcing a locale change:

You may force a locale change at any time by passing the special lang parameter in any URL of the web application:

http://www.myapp.com/thecontext/index.jsp?lang=en_US

http://www.myapp.com/thecontext/Hello.hi.mtw?msg=blahblah&lang=pt_BR

TIP: That's how Kawai implements the little flags in the top right corner that allows you to change the language at any time.

Specifying the locales supported in the application manager:

	@Override
	public void loadLocales() {
		addLocales("en_US", "pt_BR");
	}