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.
The <message-bundle> is to be used whenever you want to override Jakarta Faces default warning/error messages which is been used by the Jakarta Faces validation/conversion stuff.
You can find keys of the default warning/error messages in chapter 2.5.2.4 "Localized Application Messages" of the Jakarta Faces specification. They all have the jakarta.faces prefix.
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
jakarta.faces.component.UIInput.REQUIRED = {0}: This field is required
com/example/i18n/Messages_nl.properties
jakarta.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>
The <resource-bundle> is to be used whenever you want to register a localized resource bundle which is available throughout the entire Faces 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>
Since Java EE 6 / JSF 2, there's also the Jakarta Validation API (formerly known as JSR303 Bean Validation) which is represented by those @NotNull, Size, @Max, etc annotations of the jakarta.validation.constraints package. You should understand that this API is completely unrelated to Jakarta Faces. It is not part of Faces, but Faces just happens to have support for it during validations phase. I.e. it determines and recognizes the presence of a Jakarta Validation 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 6.3.1.1 "Default message interpolation algorithm" of the Jakarta Validation specification, the custom Jakarta 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!).
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.