Internationalization

Sources for internationalized Text

Text that is displayed on web pages comes from one of the following sources:

• hard-coded data in an XHTML file
• hard-coded data in a Java class
• data retrieved by calling a web service
• data read from a database
• text read from a Java properties file

The generators JSF Common Web-Fragment, JSF Web-Fragment and JSF Application create Java properties files that are meant to be used to provide texts for different languages that then are shown on web pages.

Note

By default the generators create messages properties files for the languages ‘de’ and ‘en’. In the future you will be able to customize that list of languages by setting generator options:
- Generator Options for JSF Web Fragment
- Generator Options for JSF Web Application

Reading Entries from generated Properties Files

Java ships the ResourceBundle mechanism that is being used to read entries from the properties files. If you call the method getMsg(String key) or getMessageProperty(String key) that is defined in a parent class of your managed bean (Abstract[capability-Name]ManagedBean or AbstractManagedBean), the given key is searched for in the following messages properties files (in the given order):

1. [capability-name]-messages-overwrite.properties … located in a web application project
2. [capability-name]-messages.properties
3. messages-overwrite.properties … located in a web application project and NOT generated
4. messages.properties

If an entry for the given key is found in any of the above files, the subsequent properties files are not checked any further.

The generated properties file app-messages.properties is not used by any web fragment. The purpose of it is to be able to add internationalized texts to web applications where those texts are being needed in that single web application only.

The locale that is going to be used to read the properties is gotten by the call to FacesContext.getCurrentInstance().getViewRoot().getLocale();.

Algorithm of getLocale(), taken from JavaDoc

If we have a locale ivar, return it. If we have a value expression for “locale”, get its value. If the value is null, return the result of calling {@link javax.faces.application.ViewHandler#calculateLocale}. If the value is an instance of java.util.Locale return it. If the value is a String, convert it to a java.util.Locale and return it. If there is no value expression for “locale”, return the result of calling {@link javax.faces.application.ViewHandler#calculateLocale}.

In case FacesContext.getCurrentInstance().getViewRoot() returns null, the locale is gotten from Locale.getDefault(); instead. This fall-back is installed, since most often it is better to display text for the wrong language instead of displaying nothing at all.

There is also a mechanism built-in to JSF to read entries from properties files. The generators add entries to the generated faces-config.xml files, e.g. in the commons web fragment:

...
        <locale-config>
            <default-locale>de</default-locale>
            <supported-locale>en</supported-locale>
            <supported-locale>de</supported-locale>
        </locale-config>

        <resource-bundle>
            <base-name>messages</base-name>
            <var>msg</var>
        </resource-bundle>
...

You can then access the properties files by using the variable msg:

...
<title>#{msg['ErrorPageTitle']}</title>
...

This mechanism does not provide a built-in way to overwrite existing messages properties, though.

Commonly used Texts

Ideally, the properties file messages.properties contains commonly needed texts that potentially are going to be used by all other web fragments and web applications. The entries in those properties files can also be overwritten by providing a file messages-overwrite.properties. However, the JSF Web Application generator does not generate such files since it is a rare case that you would want to overwrite those entries.

Salutation and notification level examples for messages.properties:

commons.salutation.mr=Herr
commons.salutation.mrs=Frau
commons.salutation.ms=Fräulein
commons.salutation.dr=Doktor
commons.salutation.prof=Professor

commons.notification.level.error=Fehler
commons.notification.level.warning=Warnung
commons.notification.level.info=Information