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 text, date, or other fields should be presented in a form specific to a region.
Note
PrimeFaces only provides English translations. Translations for other languages should be provided explicitly. In the following sections, you will find 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 is a text file with the .properties suffix that would contain 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 stands for English, and the supported locale is tr_TR, which stands for Turkish. For projects structured by Maven, the messages_{localekey}.properties file can be created under the src/main/resources project path. The following image was made in the IntelliJ IDEA:
How to do it…
To showcase Internationalization, we will broadcast an information message via the FacesMessage mechanism that will be displayed in PrimeFaces' growl component. We need two components—growl itself and a command button—to broadcast the message:
<p:growl id="growl" />
<p:commandButton action="#{localizationBean.addMessage}" value="Display Message" update="growl" />The addMessage method of localizationBean is as follows:
public String addMessage() {
addInfoMessage("broadcast.message");
return null;
}The preceding code 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 with a java.util.Locale instance.
Components such as calendar and schedule use a shared PrimeFaces.locales property to display labels. As stated before, PrimeFaces only provides English translations, so in order to localize the calendar, we need to put the 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; you can find it in the showcase application Here's the code snippet we talked about:
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'
};The definition of the calendar components both with and without 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 PrimeFaces message, the addInfoMessage method retrieves the message bundle via the defined msg variable. 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 PrimeFaces message with the FacesMessage.SEVERITY_INFO severity level.
There's more…
For some components, localization could be accomplished by providing labels to the components via attributes, such as with p:selectBooleanButton:
<p:selectBooleanButton
value="#{localizationBean.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 the PrimeFaces configuration file. The English version of the bundle key definitions in the messages_en.properties file that resides under the classpath would be as follows:
booleanButton.onLabel=Yes booleanButton.offLabel=No
The PrimeFaces Cookbook Showcase application
This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, and build and deploy the WAR file on application servers compatible with Servlet 3.x, such as JBoss WildFly and Apache TomEE.
For the demos of this recipe, refer to the following:
- Internationalization is available at
http://localhost:8080/pf-cookbook/views/chapter1/internationalization.jsf - Localization of the calendar component is available at
http://localhost:8080/pf-cookbook/views/chapter1/localization.jsf - Localization with resources is available at
http://localhost:8080/pf-cookbook/views/chapter1/localizationWithResources.jsf
For already translated locales of the calendar, see http://code.google.com/p/primefaces/wiki/PrimeFacesLocales.
Right to left language support
In PrimeFaces, components such as accordionpanel, datatable, dialog, fileupload, schedule, tabview, and tree offer right-to-left text direction support for languages such as Arabic, Hebrew, and so on. These components possess the dir attribute that can either get the value ltr (which is the default behavior with left-to-right text direction) or rtl.
How to do it...
We are going to create a dialog box that contains Arabic characters, as given here:
<p:commandButton value="Show Dialog" onclick="PF('arabicDlg').show();" type="button" />
<p:dialog widgetVar="arabicDlg" dir="rtl">
<h:outputText value="PrimeFaces هو مصدر للمساهمة في المشروع المكون جناح مفتوح مع الملحقات المختلفة." />
</p:dialog>When you click on the Show Dialog button, you will get the following output:
How it works…
Within the example, we're setting the dir attribute of the <p:dialog> component to rtl, stating that the text direction will be right to left.
There's more…
The direction of text can also be changed globally by setting primefaces.DIR in the web.xml file:
<context-param> <param-name>primefaces.DIR</param-name> <param-value>rtl</param-value> </context-param>
A parameter value can either be ltr or rtl. It can also be an EL expression to provide dynamic values.
The PrimeFaces Cookbook Showcase application
This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, and build and deploy the WAR file on application servers compatible with Servlet 3.x, such as JBoss WildFly and Apache TomEE.
The showcase for the recipe is available at http://localhost:8080/pf-cookbook/views/chapter1/rightToLeft.jsf.
