Theme Localization

Overview

The FusionAuth theme can be localized to better server your end users. In each theme you may specify one to many language specific message bundles to translate text rendered in a theme into a user’s preferred language.

If you’re just looking into localizing your theme, take a look at our community provided and maintained message bundles.

You may also want to review our localization and internationalization documentation.

• Messages

• Locale

• Identity Provider Login Buttons

Messages

In the Messages tab of your theme editor you may specify one to many languages. Once you have specified a key and value the key may be used in any template to display a localized string.

Consider the following message bundle and theme usage example with English and German messages defined.

greeting=Good day

greeting=Guten Tag
optional-greeting=Mitmensch

<p>${theme.message('greeting')} ${theme.optionalMessage('optional-greeting')}</p>

If I have selected German as my locale, I will be greeted with Guten Tag Mitmensch rendered on the page.

If I have English selected I will instead find the greeting Good day optional-greeting.

The behavior differs between theme.message and theme.optionalMessage only when the key doesn’t exist in any of the messages files, including the default one.

When there is no suitable key found and theme.message is used, an exception is thrown and the template fails to completely render. When there is no suitable key found and theme.optionalMessage is used, the key value is returned: optional-message in the example above.

Here’s an example of a template that will render for a user with a German locale but fail for a user with an English locale, because message fails when there is no key found:

<p>${theme.message('optional-greeting')}</p>

Here’s a Freemarker function which returns an empty string when there is no value found for an optional message:

[#function getOptionalMessage key=""]
  [#if "${theme.optionalMessage(key)}" == "${key}"]
    [#return "" /]
  [/#if]
  [#return theme.optionalMessage(key) /]
[/#function]

If you add this to your _helpers.ftl file, you can call it like this:

[@helpers.getOptionalMessage key="optional-greeting" /]

There’s an open issue on changing the behavior of optionalMessage.

Locale

The locale is determined by the locale value. The locale is resolved on each request using the following precedence:

Identity Provider Login Buttons

The button text displayed in the login pages for identity providers such as Google, Facebook or SAML, is retrieved from the identity provider configuration. The API documentation documents how to set and retrieve this value, which is identityProvider.buttonText.

This text is used in the default theme like so:

<div class="text">${identityProvider.lookupButtonText(clientId)?trim}</div>

The buttonText value stored in the identity provider configuration cannot be localized.

However, you can replace this line in the theme template to pull a localized value from the messages bundle.

First, add the translated text to all messages bundles, including the default bundle:

google-login=Login With Google

google-login=Mit Google Einloggen

Then, update the relevant templates to display the localized text. Here’s an excerpt of an updated login page:

<div class="text">${theme.message('google-login')}</div>