Java & internationalization / localization

by Piotr Likus on January 25, 2015


Below you will find necessary tips to implement internationalized texts in Java / JSF applications.

Main areas:

  • message files (file name, file format, ide)
  • Java code: resource bundle + bean
  • JSF: define message bundle (faces-config.xml), extract texts from JAR
  • PrimeFaces: JavaScript + XHTML / resource bundle + message bundle, extract texts from JAR

Define resource(s)

Message files

Messages are stored inside *.properties files with name pattern where xx is locale code like “en” (English) or “fr” (French). Files should be stored under “src” directory directly or inside selected package. File format is a standard “.properties” format, encoding “ISO 8859-1”, UTF-8 can be used with additional class (see below). Default encoding (understood by Netbeans, IntelliJ IDEA) uses Unicode characters in form u00f1a, so it’s safe for each language, it just doesn’t look nice outside of IDE when you view the messae file.

Example file for English (file name “”):

auto.config.successful=Auto-config successful!
auto.config.failed=Auto-config failed!
reg.welcome.mail=Welcome to '{'service-name'}'n
Please keep this e-mail for your records. Your account information is asn

Message bundle

  • used to replace build-in messages
  • define in faces-config.xml


Resource bundle

  • used to define own messages (one or more sets)

  • define in faces-config.xml (for resource files src/

  • can be defined as class name that supports reading of texts:



  • use to specify message bundle at document (XHTML) level

  • inside XHTML write:

    <f:loadBundle   var="msg"     basename="ApplicationResource"/>

Resource encoding

  • normally you can use only ISO 8859-1 in properties files
  • if you want something more, you can use “native2ascii” command

    /path/to/jdk/bin/native2ascii -encoding UTF-8
  • example output:

    some.dutch.text = u00c9u00e9n van de wijken van Curau00e7ao heet Saliu00f1a
  • in order to use UTF-8 inside properties you must use own ResourceBundle class:

  • you can load texts from database


Use in XHTML

  • select locale in XHTML

    <f:view locale="fr">
  • example using EL with var “msg” and message code “welcome.general”

    <h:outputLabel value="#{msg['welcome.general']}" />
  • example with variable fragments (parameters) inside text

    <h:outputFormat value="Hello {0}!.">                
       <f:param value="World" />
  • example with escaping value

    <h:outputFormat value="#{msg['welcome']}" escape="false">
        <f:param value="#{fn:escapeXml(param)}"/>

HTML tags inside texts

  • using getBookmarkableURL

    <h:outputFormat value="#{msg['activation.failed.desc']}" escape="false">
        <f:param value="&lt;a href='#{facesContext.application.viewHandler.getBookmarkableURL(facesContext, '/register', null, false)}'&gt;#{msg['register']}&lt;/a&gt;" />
  • using encoded code

    <h:outputFormat value="#{msg['activation.failed.desc']}" escape="false">
        <f:param value="&lt;a href='#{request.contextPath}/register.xhtml'&gt;#{template['activation.register']}&lt;/a&gt;" />
  • using omniFaces o:param

    <h:outputFormat value="#{msg['activation.failed.desc']}" escape="false">
        <o:param><h:link outcome="register" value="#{template['activation.register']}" /></o:param>
  • using backing bean

        <h:outputFormat value="#{msg['activation.failed.desc']}"
            <f:param value="#{activateController.textLinkRegister}" />
            <f:param value="#{activateController.textLinkEnd}" />
            <f:param value="#{activateController.textLinkHome}" />
            <f:param value="#{activateController.textLinkEnd}" />

Language selection

Session storage

    // From:

    import java.util.Locale;

    import javax.faces.bean.ManagedBean;
    import javax.faces.bean.SessionScoped;
    import javax.faces.context.FacesContext;

    public class LocaleBean {
        private Locale locale = FacesContext.getCurrentInstance().getViewRoot().getLocale();

        public Locale getLocale() {
            return locale;

        public String getLanguage() {
            return locale.getLanguage();

        public void setLanguage(String language) {
            this.locale = new Locale(language);

Dynamic locale in XHTML

  • code example

    <f:view locale="#{localeBean.locale}">

Change global language in code

   public String changeLanguage(Locale locale) {

In-code usage of texts

  • define helper class for reading texts from resource bundle

    // From: JSF 2.0 Cookbook, Anghel Leonard, PACKT Publishing, 2010
    public class LocaleHelper {
        protected static ClassLoader getClassLoader(Object defaultObject)
            ClassLoader loader =
            if (loader == null) {
                loader = defaultObject.getClass().getClassLoader();
            return loader;
        public static String getLocaleString(
                String bundle,
                String key,
                Object parameters[],
                Locale locale) {
            String message = null;
            ResourceBundle resourceBundle = ResourceBundle.getBundle(bundle,
                    locale, getClassLoader(parameters));
            try {
                message = resourceBundle.getString(key);
            } catch (MissingResourceException e) {
                message = "ERROR MESSAGE!";
            if (parameters != null) {
                StringBuffer stringBuffer=new StringBuffer();
                MessageFormat messageFormat = new MessageFormat(message,
                message = messageFormat.format(parameters, stringBuffer,
            return message;
  • usage

    // From: JSF 2.0 Cookbook, Anghel Leonard, PACKT Publishing, 2010
    FacesContext context = FacesContext.getCurrentInstance();
    //get default locale
    Locale myLoc = context.getViewRoot().getLocale();
    String message = LocaleHelper.getLocaleString(
            "USER_AGE", null, myLoc);
  • read application message bundle name

    public static String getMessageBundle(FacesContext context) {
      return context.getApplication().getMessageBundle();


  • define message bundle in faces-config.xml
  • extract messages from file:
  • translate these messages and include in your own message bundle file


  • extract messages from file:

  • add JS script with texts from Primefaces page:

    • upload to resources/default/js/primefaces_xx.js
    • add to page <h:outputScript library="default" name="js/primefaces_pl.js" />
  • add message attributes in HTML:

    • p:inputText requeredMessage
    • p:dataTable emptyMessage
    • p:password *Label
Fonts by Google Fonts. Icons by Fontello. Full Credits here »