i18n with UTF-8 encoded properties files in JSF 2.0 application

I am using jsf-ri 2.0.3 where Hebrew and Russian support is needed. The problem is that I see gibberish on the screen instead of the correct text.

First of all I have defined bundles (*_locale.properties) for each language. The files is in UTF-8 encoding. Secondly, I've defined the default and supported locales in faces-config.xml

<locale-config>
    <default-locale>iw</default-locale>
    <supported-locale>en</supported-locale>
    <supported-locale>ru</supported-locale>
</locale-config>

Than I've added a custom filter that will set the response charcter encoding to UTF-8.

<filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
    <init-param>
        <param-name>forceEncoding</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>encodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

And finally when I create a simple xhtml to debug the output I see a very strange results

<f:loadBundle basename="i18n.frontend.homepage" var="msg"/>
<strong>i18n: </strong><h:outputText value="#{msg.language}"/>
<br/>
<strong>Locale: </strong>
<h:outputText value="#{facesContext.externalContext.response.locale}"/>
<br/>
<strong>Encoding: </strong>
<h:outputText value="#{facesContext.externalContext.response.characterEncoding}"/>

The result is:

i18n: ×¢×ר×ת
Locale: en_US
Encoding: UTF-8 

What is wrong with my configuration?

Right, you can create a custom ResourceBundle or use the native2ascii converter (if necessary with the Maven 2 plugin to make the conversion more transparent). Since the other answer only goes with the last approach in detail, here's another answer how you could create a custom ResourceBundle to load properties files as UTF-8 in a JSF 2.x application on Java SE 1.6 based environment.

faces-config.xml

<application>
    <resource-bundle>
        <base-name>com.example.i18n.Text</base-name>
        <var>text</var>
    </resource-bundle>
</application>

com.example.i18n.Text

package com.example.i18n;

import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;
import java.util.Enumeration;
import java.util.Locale;
import java.util.PropertyResourceBundle;
import java.util.ResourceBundle;

import javax.faces.context.FacesContext;

public class Text extends ResourceBundle {

    protected static final String BUNDLE_NAME = "com.example.i18n.text";
    protected static final String BUNDLE_EXTENSION = "properties";
    protected static final String CHARSET = "UTF-8";
    protected static final Control UTF8_CONTROL = new UTF8Control();

    public Text() {
        setParent(ResourceBundle.getBundle(BUNDLE_NAME, 
            FacesContext.getCurrentInstance().getViewRoot().getLocale(), UTF8_CONTROL));
    }

    @Override
    protected Object handleGetObject(String key) {
        return parent.getObject(key);
    }

    @Override
    public Enumeration<String> getKeys() {
        return parent.getKeys();
    }

    protected static class UTF8Control extends Control {
        public ResourceBundle newBundle
            (String baseName, Locale locale, String format, ClassLoader loader, boolean reload)
                throws IllegalAccessException, InstantiationException, IOException
        {
            // The below code is copied from default Control#newBundle() implementation.
            // Only the PropertyResourceBundle line is changed to read the file as UTF-8.
            String bundleName = toBundleName(baseName, locale);
            String resourceName = toResourceName(bundleName, BUNDLE_EXTENSION);
            ResourceBundle bundle = null;
            InputStream stream = null;
            if (reload) {
                URL url = loader.getResource(resourceName);
                if (url != null) {
                    URLConnection connection = url.openConnection();
                    if (connection != null) {
                        connection.setUseCaches(false);
                        stream = connection.getInputStream();
                    }
                }
            } else {
                stream = loader.getResourceAsStream(resourceName);
            }
            if (stream != null) {
                try {
                    bundle = new PropertyResourceBundle(new InputStreamReader(stream, CHARSET));
                } finally {
                    stream.close();
                }
            }
            return bundle;
        }
    }
}

This expects UTF-8 encoded properties files like text.properties, text_en.properties, etc in com.example.i18n package. No need for native2ascii.

By the way, with the new JSF 2.0 style <resource-bundle> declaration in faces-config.xml, you don't need <f:loadBundle> in the views anymore. All text will be directly available by #{text} in all views.

Well, after a deep investigation I have found the solution.

Earlier to java 1.6 PropertyResourceBundle had only one constructor which has the following documentation The property file read with this constructor must be encoded in ISO-8859-1. This means that it is possible to use only English text in the resource bundles.

There are two solutions for this issue:

The first one is writing a custom loadBundle component wich will use the correct ResourceBundle instantiation method.

The second one (My choice) is using the Native-to-ASCII converter which can be used with maven using the Native2Ascii maven plugin.

Here is the configuration example:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>native2ascii-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>native2ascii</goal>
            </goals>
            <configuration>
                <src>${basedir}/src/main/resources</src>                
                <dest>${project.build.directory}/native2ascii</dest>
                <encoding>UTF8</encoding>
                <includes>**/*.properties</includes>
            </configuration>
        </execution>
    </executions>
</plugin>