Mentawai Web Framework

Internationalization (i18n)

I18n is central to any serious web application and mentawai does it automatically for you through the org.mentawai.i18n.LocaleManager class. Of course there is no problem if you want to develop your site in just one language, but if you change your mind later on, mentawai will offer you automatic and easy i18n support.

You can download a simple mentawai application that uses localized text by clicking here.


I18n Files

I18n in mentawai is accomplished through i18n files. An i18n file (*.i18n) is just a properties file with some localized text. I18n files must have the locale it represents appended at the end of its name, for example the contents below are for the file HelloWorld_en_US.i18n. 

###########################
# Example of an i18n file #
###########################

hello = Hello
welcome = Welcome to the online Java community!

Mentawai keeps all i18n files in memory for fast access and will automatically reload them if you change something. That's a great feature not supported by the resource bundle (java.util.ResourceBundle) default approach to i18n, that forces you to restart your web server if you need to make any changes to your localized text.

When you start working with data lists and dynamic messages, you will use i18n files to define them in a very easy way.


Defining the supported locales

If you don't do anything, Mentawai will have just one default locale: en_US. Therefore it will expect to find at least *_en_US.i18n files. However, you should explicit define which locales you have chosen to support through the ApplicationManager's loadLocales() method. (Note that if you just want to use the useI18N and i18n menta tags, you do not need to do this!) 

public class ApplicationManager extends org.mentawai.core.ApplicationManager {
	
	public void loadActions() {
		// your actions are defined here...		
	}				
	
	public void loadLocales() {
		// my site will support just one locale
		LocaleManager.add(new Locale("pt", "BR"));
	}
}

The above code is indicating that your site will only support the pt_BR locale. It will ignore all i18n files that do not end with a _pt_BR.i18n.

If later on, you decide to add support to french, you can specify an extra locale with the code below: 

	public void loadLocales() {
		LocaleManager.add(new Locale("pt", "BR"));
		LocaleManager.add(new Locale("fr"));
	}


Using i18n tags to localize JSPs

You can localize your JSP page content through the use of some very simple mentawai tags.

You indicate that you want to use localized text in a page through the <mtw:useI18N /> tag.

The <mtw:useI18N /> uses i18n files inside the /i18n directory in the document root. The tag creates a search path with the following files:

[ (1) specified files in the tag, if any ]
		↓ 
[ (2) corresponding i18n file for the jsp, if any ]
		↓
[ (3) master i18n file ]
It returns the first match it finds for the key it is looking for. It looks for 1, 2 and 3 in that order. Below we explain 1, 2 and 3:
  • (1) - You can specify i18n files in the <mtw:useI18N /> tag through the files attribute.
    Ex: If you do <mtw:useI18N files="somefile, mydir/another" />, then you are adding files /i18n/somefile and /i18n/mydir/another to the search path.

  • (2) - If your jsp page is /mypage.jsp, mentawai automatically looks for a file called /i18n/mypage_loc.i18n. Note that the directory structure is also taken into account, so if your page is /pags/mypage.jsp, the i18n file will be /i18n/pags/mypage_loc.i18n.

  • (3) - The last i18n file in the search path is, by default, /i18n/master_loc.i18n.
  • Notice that these files need not exist. If that's the case the file is ignored and the next file in the search path is searched for the key.

    This search path is useful because it allows you to override keys if you need to.

    You may change the name of the master i18n file with the code below: 

    	public void loadLocales() {
		LocaleManager.add(new Locale("pt", "BR"));
		LocaleManager.add(new Locale("fr"));
		LocaleManager.setMaster("mywebsite"); // master = /mywebsite_loc.i18n
	}

    Once you have declared in a JSP page that you want to use i18n files through the <mtw:useI18N /> tag, you can print localized text through the <mtw:i18n key="hello" /> mentawai tag.

    If you need to localize images, you can use the <mtw:i18nDir /> tag to print the locale being used, for example pt_BR. So you would localize an image like that:

    <img src="/images/<mtw:i18nDir />/hello.gif">


    How the user locale is determined

    By default, the user locale is the browser locale, in other words, the locale that the browser sends in every http request.

    You may change that if you want, for example, a user may have his locale information saved in a database, so whenever he logs in, he should see the site in his database locale, not his browser locale. To accomplish that, all you need to do is place the user locale in the session with the code below: 

    	session.setAttribute(BaseLoginAction.LOCALE_KEY, userLocaleFromDatabase);

    If you are using the convenient org.mentawai.action.BaseLoginAction for user authentication, you can also use the method setUserLocale() to do the same thing.

    What happens if the user locale (from a database or from a browser) is not supported by the web site?

    Mentawai uses the following rule to return a locale:

    • Let's say the locale sent by the browser is en_UK
    • Mentawai first checks whether this locale is supported, in other words it looks for en_UK.
    • If en_UK is not found, it looks for the en locale, the general english.
    • If en is not found, it looks for the first locale that has the same language, for example en_US, en_AU, etc.
    • If there is no locale with the same language, than it returns the default locale, in other words, the first locale added to LocaleManager.