Internationalization in JSF, when to use message-bundle and resource-bundle?

When and how should I use <resource-bundle> and <message-bundle> tags for localization in faces-config.xml? The differences between those two are not very clear to me.

Solution 1:

<message-bundle>

The <message-bundle> is to be used whenever you want to override JSF default warning/error messages which is been used by the JSF validation/conversion stuff. You can find keys of the default warning/error messages in chapter 2.5.2.4 of the JSF specification.

For example, Messages_xx_XX.properties files in com.example.i18n package as below which overrides the default required="true" message:

com/example/i18n/Messages_en.properties

javax.faces.component.UIInput.REQUIRED = {0}: This field is required

com/example/i18n/Messages_nl.properties

javax.faces.component.UIInput.REQUIRED = {0}: Dit veld is vereist

can be configured as follows (without the locale specifier _xx_XX and the file extension!):

<message-bundle>com.example.i18n.Messages</message-bundle>

<resource-bundle>

The <resource-bundle> is to be used whenever you want to register a localized resource bundle which is available throughout the entire JSF application without the need to specify <f:loadBundle> in every single view.

For example, Text_xx_XX.properties files in com.example.i18n package as below:

com/example/i18n/Text_en.properties

main.title = Title of main page
main.head1 = Top heading of main page
main.form1.input1.label = Label of input1 of form1 of main page

com/example/i18n/Text_nl.properties

main.title = Titel van hoofd pagina
main.head1 = Bovenste kop van hoofd pagina
main.form1.input1.label = Label van input1 van form1 van hoofd pagina

can be configured as follows (without the locale specifier _xx_XX and the file extension!):

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

and be used in main.xhtml as follows:

<h:head>
    <title>#{text['main.title']}</title>
</h:head>
<h:body>
    <h1 id="head1">#{text['main.head1']}</h1>
    <h:form id="form1">
        <h:outputLabel for="input1" value="#{text['main.form1.input1.label']}" />
        <h:inputText id="input1" label="#{text['main.form1.input1.label']}" />
    </h:form>
</h:body>

ValidationMessages (JSR303 Bean Validation)

Since Java EE 6 / JSF 2, there's also the new JSR303 Bean Validation API which is represented by those @NotNull, Size, @Max, etc annotations of the javax.validation.constraints package. You should understand that this API is completely unrelated to JSF. It is not part of JSF, but JSF just happens to have support for it during validations phase. I.e. it determines and recognizes the presence of a JSR303 implementation (e.g. Hibernate Validator) and then delegates the validation to it (which can be disabled by using <f:validateBean disabled="true"/>, by the way).

As per chapter 4.3.1.1 of the JSR303 specification, the custom JSR303 validation messages file needs to have exactly the name ValidationMessages_xx_XX.properties and it needs to be placed in the root of the classpath (thus, not in a package!).

Localization

In the above examples, the _xx_XX in the filename represents the (optional) language and country codes. If this is absent altogether, then it becomes the default (fallback) bundle. If the language is present, e.g. _en, then it'll be used when the client has explicitly requested for this language in the Accept-Language HTTP request header. The same applies to the country, e.g. _en_US or _en_GB.

You can specify the supported locales for both the message and resource bundle generically in <locale-config> element of faces-config.xml.

<locale-config>
    <default-locale>en</default-locale>
    <supported-locale>nl</supported-locale>
    <supported-locale>de</supported-locale>
    <supported-locale>es</supported-locale>
    <supported-locale>fr</supported-locale>
</locale-config>

The desired locale needs to be set via <f:view locale>. See also Localization in JSF, how to remember selected locale per session instead of per request/view.