Messages and Internationalization

Nothing here has a phase of its own; it hangs off the phases described on the request processing lifecycle page:

A jakarta.faces.application.FacesMessage has three parts: a severity, a summary (the short text) and a detail (the longer explanation). The severity is one of four constants in ascending order: SEVERITY_INFO, SEVERITY_WARN, SEVERITY_ERROR and SEVERITY_FATAL. Constructing a message without a severity gives INFO, and getDetail() returns the summary when no detail was set, so a message built with null as the detail still has something to show in places that display the detail.

Since Faces 4.1 a message can be compared. FacesMessage gained equals(), hashCode() and toString() (issue 1823 in the specification’s change log; the Javadoc marks the three methods Since: 4.1), and FacesMessage.VALUES and FacesMessage.VALUES_MAP became generic (issue 1789): a List<FacesMessage.Severity> in ascending order and a Map<String, FacesMessage.Severity> keyed by the severity names. The first is useful to code that queues messages: it can look for an equal message before adding another one, and a Set<FacesMessage> now behaves as a set.

Source: Jakarta Faces 4.1 API: FacesMessage and Jakarta Faces 4.1 specification, Changes between 4.1 and 4.0

Compiled against the Mojarra 4.1.17 jar and, separately, the MyFaces API 4.1.4 jar, the program printed on both equals same fields: true hash equal: true, equals other severity: false and set size: 2 (three messages, two of them equal), and typed lookup for "ERROR" returned the severity (the first attempt used the key "Error" and got null: the keys are the upper-case names). VALUES printed [INFO 0, WARN 1, ERROR 2, FATAL 3] on Mojarra and [INFO, WARN, ERROR, FATAL] on MyFaces. The one visible difference is toString(): FacesMessage[severity='ERROR 2', summary='Bad', detail='detail'] on Mojarra and FacesMessage[severity='ERROR', summary='Bad', detail='detail'] on MyFaces, so do not parse the string. What the equality is compared on beyond severity, summary and detail was not tested, and nothing here shows Faces itself dropping duplicates from the queue; the removal of a duplicate is code you write. Faces 5.0 is planned to add a fifth severity, SUCCESS (issue 1592, listed on the 5.0 specification page); it is not in 4.1, so keep using INFO for a success text and style it yourself (see the versions page).

The client id is not part of the message; it is the first argument of FacesContext.addMessage(String, FacesMessage). A message added with a client id ("review:title") belongs to that component and is shown by an h:message whose for names it. A message added with a null client id is a global message: it belongs to the page and is shown by an h:messages. The Bookshelf review bean uses both:

Source: FacesMessage API documentation and Jakarta EE Tutorial: Registering Application Messages

Three details of that bean are worth a sentence each:

A bean that lives longer than a request, or code that has no injected bundle, asks the application, which returns the bundle for the locale of the current view:

Source: Application API documentation, getResourceBundle and ManagedProperty API documentation

h:message renders one message for one component, the first message queued for the client id in its for attribute. h:messages renders all queued messages, as an HTML list by default or as a table with layout="table". Their defaults differ on purpose: h:message shows the detail (showDetail defaults to true, showSummary to false), because it sits beside one field and has room for the explanation; h:messages shows the summary (showSummary defaults to true, showDetail to false), because it lists many.

The Bookshelf layout (a template, see the templating page) shows global messages once, so every page gets them:

And a review page puts one h:message beside each field:

Source: VDL documentation: h:message, VDL documentation: h:messages and Jakarta EE Tutorial: Adding Components to a Page Using HTML Tag Library Tags

Submitting that form with a two-letter title, the text abc as the rating and an empty review produced, in Spanish (Accept-Language: es), the following text beside the fields on both Mojarra and MyFaces:

(The example number inside the rating message differs between implementations; see the comparison table below.)

The attributes both tags share, from the VDL documentation:

A few behaviours you will meet quickly:

The messages in the table above, such as Título: al menos 3 caracteres, were not written in Java by the Bookshelf. They are standard messages: when a converter, a validator or the required check fails, the implementation creates a FacesMessage from a message key. The specification requires every implementation to ship a resource bundle named jakarta.faces.Messages with the same keys, in several languages. Each key looks up the summary, and the same key with _detail appended looks up the detail. The values are java.text.MessageFormat patterns.

Some of the keys in the Mojarra 4.1.17 bundle (the specification lists the full set):

The last placeholder of the converter and validator messages is the label of the input: the value of its label attribute, or, when the attribute is absent, its client id. That is why the review form above sets label="#{msg['review.field.title']}": without it a failure starts with the bare id, for example j_idt22 or review:title, which means nothing to a reader. In the scratch run a converter on an h:outputText without a label reported the generated id j_idt22 in its message.

Three attributes on input components replace a standard message for that one component, without any bundle: requiredMessage, converterMessage and validatorMessage. The values are ordinary EL, so they come from the resource bundle and follow the view locale. The review form above uses requiredMessage="#{msg['review.text.required']}", and the empty review showed Escribe algo en tu reseña. in Spanish and Please write something in your review. in English. Note that validatorMessage replaces the message of every validator attached to the input, including Bean Validation’s, which is why it is better for a single, generic sentence and not for per-constraint texts. How a Bean Validation violation becomes a FacesMessage, how the constraint messages are localised with ValidationMessages bundles and how the label placeholder is filled are on the Bean Validation page; validatorMessage versus Bean Validation messages was not run on this page.

Source: Jakarta Faces 4.1 specification, Localized Application Messages and Jakarta EE Tutorial: Using the Standard Converters

To change the wording of the standard messages, supply your own bundle in faces-config.xml with the message-bundle element. Faces then follows this algorithm, taken from the specification, every time it needs a message for a key:

Only the keys you override need to be present; everything else falls back to the implementation’s bundle, in the language of the view. The Bookshelf declares its bundle for view text and its bundle for standard messages side by side:

Source: Jakarta Faces 4.1 specification, Localized Application Messages and Jakarta Faces 4.1 specification, 11.3.5 Application Configuration Resource Format

Posting the review form with an empty title in English and with the title ab and the rating abc in Spanish produced, on both implementations:

Two things stand out. The MINIMUM key has no _detail partner in the bundle, and the page still shows the text: FacesMessage.getDetail() falls back to the summary, so a field with an h:message (which shows the detail) reads correctly even when you only translated the summary. And the rating example was 9346 on Mojarra and 21 on MyFaces: the {1} example value is the implementation’s choice, which is one more reason not to quote it in tests.

The message bundle above is only for Faces' own messages. The text of your pages (headings, labels, button captions, your own messages) goes in a second bundle, a normal java.util.ResourceBundle, and the views read it through an EL variable. There are two ways to expose it.

Bundle values are java.text.MessageFormat patterns. In a view, h:outputFormat fills them in from nested f:param elements. The Bookshelf catalogue header needs singular and plural, which a choice format expresses in the pattern itself, so the translator controls the grammar for each language:

Source: VDL documentation: h:outputFormat and VDL documentation: f:param

With a catalogue of 3 books, the three counts 0, 1 and 3 rendered, in English and then Spanish:

Four rules for these patterns:

Mojarra and MyFaces differ on one more point. With no f:param children, the VDL documentation says the value is rendered unmodified, which is what Mojarra did (Don't panic stayed intact). MyFaces applied MessageFormat anyway and printed Dont panic. Do not depend on either: a message that contains an apostrophe should be doubled, or never sent through h:outputFormat without parameters.

Faces keeps one active locale per view, on UIViewRoot. Everything locale-aware reads it: the resource bundle variable, converters and validators, the messages above and f:convertNumber. Declare what the application supports in faces-config.xml (the block shown earlier):

When a view is created, the ViewHandler calculates a locale: it compares the browser’s preferences, the Accept-Language header, with the supported locales and uses the default when none matches. The specification leaves the details to the Javadoc, so they were observed. Both Mojarra and MyFaces, with a JVM whose default locale was English, gave the same answers:

The last row hides the trap again: the "default" for a request without the header is the server’s, not the application’s default-locale. On a JVM whose default was es, a header-less request rendered in Spanish because es was a supported locale. If you want the application’s default for header-less clients, set the JVM default locale deliberately (-Duser.language=en) or keep an explicit choice in the session, as below.

The active locale can also be set by hand. UIViewRoot.getLocale() follows an algorithm that is spelled out in its Javadoc:

Two consequences follow from it. A null from the expression is harmless: Faces falls back to the calculated locale. And an explicit UIViewRoot.setLocale() call wins over a f:view expression for that view; use one mechanism, not both. In a page, f:view takes a locale as a java.util.Locale or as a string in the form language[{-|_}country[{-|_}variant]], for example es or ja_JP.

Source: Jakarta Faces 4.1 specification, Localization and Internationalization, UIViewRoot API documentation, getLocale and VDL documentation: f:view

The browser’s preference is a good start, but users want to override it. The pieces are a place to remember the choice (a session-scoped bean), f:view locale to apply it, and a control that changes it. The bean starts from the locale Faces would have chosen:

The layout shown earlier wraps the whole document in <f:view locale="#{localeBean.locale}"> and its language links call #{localeBean.switchTo('es')}. Those links, the bundle and the formats on the catalogue page produced the following, one request per row (JVM default locale es, so the _en bundles matter):

After a click on Español the same session received Spanish on the redirected page and on the next request, on both implementations, whatever the browser’s header said.

Several details of the bean deserve attention:

A drop-down is a small variation on the same bean. Render the supported locales as select items, bind the selection to language, and let the button reload the view:

Source: Jakarta EE Tutorial: Registering Application Messages and VDL documentation: f:view

l.getDisplayLanguage(l) asks each locale to name itself in its own language, so the menu showed English and español whatever the page language. Posting the form with es selected switched the application to Spanish.

Where a choice should survive the session, store it where it fits your application: a cookie read in the bean’s @PostConstruct, a user-profile column, or a locale segment in the URL. The session-scoped bean is the minimum, and the part of the page that depends on it, f:view locale, does not change.

Converters read the active locale unless told otherwise. The catalogue page above shows the effect without extra work: f:convertDateTime type="localDate" dateStyle="long" printed December 23, 1815 in English and 23 de diciembre de 1815 in Spanish, and f:convertNumber type="currency" currencyCode="EUR" printed €12.50 and 12,50 €. The type="localDate" form is the way to format java.time.LocalDate; the older date and time types expect a java.util.Date.

Both converters accept a locale attribute, a java.util.Locale or a language string, that overrides the view locale for one value. That is the right tool when a number must be written one way regardless of the reader, for instance with the invoice’s own convention or a machine-readable value:

That printed 12.50 on the Spanish page, where the surrounding currency converter printed 12,50 €. For dates, timeZone is the other attribute you will want: a date is formatted in the JVM’s time zone unless the converter names one, and an international audience seldom shares the server’s zone.

Source: VDL documentation: f:convertDateTime and Jakarta EE Tutorial: Using the Standard Converters

At the start of Render Response the ViewHandler sets the response locale to the view’s locale, which can influence the response’s character encoding according to the Servlet specification. f:view also has encoding and contentType attributes to set both explicitly. In the scratch run every page, English or Spanish, rendered the accented characters correctly with no extra configuration other than the UTF-8 resource files. Keep your sources, templates and bundles in UTF-8 and the three agree.

Source: Jakarta Faces 4.1 specification, Determining the Character Encoding

Everything above behaved the same on both implementations except these points, observed with Mojarra 4.1.17 and MyFaces Core 4.1.4:

When you write a test that posts a form to MyFaces without a browser, remember that it also expects the hidden <formId>_SUBMIT field and identifies a link by <formId>:_idcl, while Mojarra accepts the link’s client id as a parameter. A real browser sends both correctly.

Use the books for the reasoning about why messages carry a severity, a summary and a detail, and why locales belong to the view. Use this page and the specification for the keys and attributes to type today.

Source: Burns and Schalk, JavaServer Faces 2.0: The Complete Reference (McGraw-Hill, 2010, ISBN 978-0-07-162509-8), Leonard, JSF 2.0 Cookbook (Packt, 2010, ISBN 978-1-847199-52-2) and Jakarta Faces 4.1 specification, Localization and Internationalization