Internationalization (i18n) and Localization (L10n)

Internationalization (i18n) and Localization (L10n) are two important features that should be provided in the web application's world to make it accessible globally.

With Internationalization, we are emphasizing that the web application should support multiple languages; and with Localization, we are stating that the texts, dates, or any other fields should be presented in the form specific to a region.

Note

PrimeFaces only provides the English translations. Translations for the other languages should be provided explicitly. In the following sections, you will find the details on how to achieve this.

Getting ready

For Internationalization, first we need to specify the resource bundle definition under the application tag in faces-config.xml, as follows:

    <application>
        <locale-config>
            <default-locale>en</default-locale>
            <supported-locale>tr_TR</supported-locale>
        </locale-config>
        <resource-bundle>
            <base-name>messages</base-name>
            <var>msg</var>
        </resource-bundle>
    </application>

A resource bundle would be a text file with the .properties suffix that would contain the locale-specific messages. So, the preceding definition states that the resource bundle messages_{localekey}.properties file will reside under classpath and the default value of localekey is en, which is English, and the supported locale is tr_TR, which is Turkish. For projects structured by Maven, the messages_{localekey}.properties file can be created under the src/main/resources project path.

How to do it...

For showcasing Internationalization, we will broadcast an information message via FacesMessage mechanism that will be displayed in the PrimeFaces growl component. We need two components, the growl itself and a command button, to broadcast the message.

<p:growl id="growl" />
<p:commandButton action="#{localizationController.addMessage}" value="Display Message" update="growl" />

The addMessage method of localizationController is as follows:

    public String addMessage() {
        addInfoMessage("broadcast.message");
        return null;
    }

That uses the addInfoMessage method, which is defined in the static MessageUtil class as follows:

public static void addInfoMessage(String str) {    
FacesContext context = FacesContext.getCurrentInstance();
    ResourceBundle bundle = context.getApplication().getResourceBundle(context, "msg");
    String message = bundle.getString(str);
    FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(FacesMessage.SEVERITY_INFO, message, ""));
}

Localization of components, such as calendar and schedule, can be achieved by providing the locale attribute. By default, locale information is retrieved from the view's locale and it can be overridden by a string locale key or the java.util.Locale instance.

Components such as calendar and schedule use a shared PrimeFaces.locales property to display labels. PrimeFaces only provides English translations, so in order to localize the calendar we need to put corresponding locales into a JavaScript file and include the scripting file to the page.

The content for the German locale of the Primefaces.locales property for calendar would be as shown in the following code snippet. For the sake of the recipe, only the German locale definition is given and the Turkish locale definition is omitted.

PrimeFaces.locales['de'] = {
    closeText: 'Schließen',
    prevText: 'Zurück',
    nextText: 'Weiter',
    monthNames: ['Januar', 'Februar', 'März', 'April', 'Mai', 
    'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 
    'Dezember'],
    monthNamesShort: ['Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 
    'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez'],
    dayNames: ['Sonntag', 'Montag', 'Dienstag', 'Mittwoch', 
    'Donnerstag', 'Freitag', 'Samstag'],
    dayNamesShort: ['Son', 'Mon', 'Die', 'Mit', 'Don', 'Fre', 
    'Sam'],
    dayNamesMin: ['S', 'M', 'D', 'M ', 'D', 'F ', 'S'],
    weekHeader: 'Woche',
    FirstDay: 1,
    isRTL: false,
    showMonthAfterYear: false,
    yearSuffix: '',
    timeOnlyTitle: 'Nur Zeit',
    timeText: 'Zeit',
    hourText: 'Stunde',
    minuteText: 'Minute',
    secondText: 'Sekunde',
    currentText: 'Aktuelles Datum',
    ampm: false,
    month: 'Monat',
    week: 'Woche',
    day: 'Tag',
    allDayText: 'Ganzer Tag'
};

Definition of the calendar components with the locale attribute would be as follows:

<p:calendar showButtonPanel="true" navigator="true" mode="inline" id="enCal"/>

<p:calendar locale="tr" showButtonPanel="true" navigator="true" mode="inline" id="trCal"/>

<p:calendar locale="de" showButtonPanel="true" navigator="true" mode="inline" id="deCal"/>

They will be rendered as follows:

How it works...

For Internationalization of the Faces message, the addInfoMessage method retrieves the message bundle via the defined variable msg. It then gets the string from the bundle with the given key by invoking the bundle.getString(str) method. Finally, the message is added by creating a new Faces message with severity level FacesMessage.SEVERITY_INFO.

There's more...

For some components, Localization could be accomplished by providing labels to the components via attributes, such as with p:selectBooleanButton.

<p:selectBooleanButtonvalue="#{localizationController.selectedValue}"onLabel="#{msg['booleanButton.onLabel']}"offLabel="#{msg['booleanButton.offLabel']}" />

The msg variable is the resource bundle variable that is defined in the resource bundle definition in Faces configuration file. The English version of the bundle key definitions in the messages_en.properties file that resides under classpath would be as follows:

booleanButton.onLabel=Yes
booleanButton.offLabel=No

PrimeFaces Cookbook Showcase application

This recipe is available in the PrimeFaces Cookbook Showcase application on GitHub at https://github.com/ova2/primefaces-cookbook. You can find the details there for running the project. For the demos of the showcase, refer to the following:

• Internationalization is available at http://localhost:8080/primefaces-cookbook/views/chapter1/internationalization.jsf

• Localization of the calendar component is available at http://localhost:8080/primefaces-cookbook/views/chapter1/localization.jsf

• Localization with resources is available at http://localhost:8080/primefaces-cookbook/views/chapter1/localizationWithResources.jsf

For already translated locales of the calendar, see http://code.google.com/p/primefaces/wiki/PrimeFacesLocales.