Help

Built with Seam

You can find the full source code for this website in the Seam package in the directory /examples/wiki. It is licensed under the LGPL.

The default locale defined in the JSF configuration file (i.e., faces-config.xml) is used to set the application's locale when the browser sends a locale in the HTTP headers that the application does not claim to support. The supported locales are defined using <supported-locale> elements within <locale-config> in faces-config.xml.

Assume the locale configuration is as follows:

<locale-config>
    <default-locale>fr</default-locale>
    <supported-locale>fr</supported-locale>
    <supported-locale>it</supported-locale>
</locale-config>

With this configuration in place, if my browser claims to support the locale en_US, then JSF would make fr (French) the current locale (for my session). That's because the application does not claim to support en_US or en. If my browser claimed to support the locale it (Italian), then the locale for my session would be Italian (as the browser requested) because it's a supported locale.

JSF will select the exact locale the browser sends if the application claims to support it. So if the browser prefers the regional English locale en_US_tmwa, then the JSF configuration would have to claim to support this locale. Otherwise, JSF will select the nearest locale for the English language from the list of supported locales, falling back to the default locale if no English locales are supported.

<locale-config>
    <default-locale>en</default-locale>
    <supported-locale>en</supported-locale>
    <supported-locale>en_US</supported-locale>
    <supported-locale>en_US_tmwa</supported-locale>
    ...
</locale-config>

It would be inconvenient for the user to change their browser settings every time they wanted to use a website in a different language. Therefore, Seam provides a locale switcher that can be bound to a select menu to allow the user to select the locale of their choice. This setting is retained until the session ends. Of course, you could retrieve the user's setting from the database and assign it automatically when their session begins using a @Scope(SESSION) @Startup component.

<h:form>
    <h:selectOneMenu valueChangeListener="#{localeSelector.select}">
        <f:selectItems value="#{locale.supportedLocales}"/>
    </h:selectOneMenu>
    <h:commandButton value="Set Locale"/>
</h:form>

The moral of the story is that the <default-locale> really doesn't mean much. It is basically a fall back scenario.