Basic principles

This documentation explains how i18n works in the Login theme. In the Account Multi-Page theme, everything works the same as in the Login theme. You just need to replace /login/ by /account/ in the import paths.

In the Account Single-Page theme, things works differently. See relevent doc.

In the Keycloak Admin Console you can enable localisation by selecting a set of language that you wish to support:

The language that you want to support isn't in the default set? You can add support for it with Keycloakify. See how.

When Internationalization is enabled you will see a language dropdown select in your UIs:

You shouldn't rely on the language select to let your users select their language.

Infact, I encourage you to hide or remove it.

What you should do instead is, when redirecting your user from your application to your Keycloak login page, add an extra query param to let Keycloak know in what language the page should be rendered.

The parameter to add is ?ui_locales=fr (Example if we want the UI to be in French).

See oidc-spa documentation for more info on how to provide this parameter. (You can do the same if you use keycloak-js or NextAuth)

If you eject some pages, you'll see in your component how the internationalization is actually implemented:

src/login/Register.tsx

export default function Register(props: RegisterProps) {
    const { i18n } = props;
    
    const { msg, msgStr, advancedMsg, advancedMsgStr } = i18n;

    return (
        //...
        <a href={url.loginUrl}>
            {msg("backToLogin")}
        </a>
        // ...
    );
}

src/login/pages/Register.svelte

<script lang="ts">
  // ...
  const props: RegisterProps = $props();
  const { i18n } = props;
  const { msg, msgStr, advancedMsg } = $i18n;
</script>

<a href={url.loginUrl}>{@render msg('backToLogin')()}</a>

src/login/pages/register/register.component.html

<a
  [href]="url.loginUrl"
  [innerHTML]="i18n.msgStr('backToLogin') | kcSanitize: 'html'"
></a>

If you want to see the base message translations you can navigate to the node_modules/keycloakify/src/login/i18n/messages_defaultSet/ directory:

Don't edit this file directly, it's just for seeing what are the default set of i18n messages.

As you can see, the translation message for the key backToLogin in English (en.ts) is:

We are sorry ...

As a result calling {msg("backToLogin")} returns the following JSX.Eement:

<p>
  <span data-kc-msg="backToLogin">We are <strong>sorry</strong> ...</span>
</p>

If you need to get the litteral string "We are sorry ..." instead of a JSX.Element you can use msgStr("backToLogin").

As a result calling {@render msg("backToLogin")} returns the following snippet:

<span data-kc-msg="backToLogin">We are <strong>sorry</strong> ...</span>

As a result calling i18n.msgStr('errorTitleHtml') return the string "We are sorry ..." and you need to pass it sanitarized as [innerHTML] so that "sorry" be redered in bold:

    <p
        [innerHTML]="i18n.msgStr('errorTitleHtml') | kcSanitize: 'html'"
    ></p>

What will actually be rendered in the DOM will be:

<p>
  <span data-kc-msg="backToLogin">We are <strong>sorry</strong> ...</span>
</p>

The purpose of the data-kc-msg attribute is to help you identify the i18n key of the text you want to change when inspecting the DOM.

Now that you get the main idea, let's see how to preview your pages in different languages:

Previewing Your Pages in Different Languages

Last updated 3 days ago

export default function Register(props: RegisterProps) { const { i18n } = props; const { msg, msgStr, advancedMsg, advancedMsgStr } = i18n; return ( //... <a href={url.loginUrl}> {msg("backToLogin")} </a> // ... ); }

<script lang="ts"> // ... const props: RegisterProps = $props(); const { i18n } = props; const { msg, msgStr, advancedMsg } = $i18n; </script> <a href={url.loginUrl}>{@render msg('backToLogin')()}</a>