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:

Enabling English, French and Spanish as supported languages in a Keycloak Realm

Want to add languages not in the default set into 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:

React

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>
        // ...
    );
}

Svelte

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>

Angular

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

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

msg("backToLogin") gets rendered as « Back to Login

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 <strong>sorry</strong> ...

React

As a result calling <p>{msg("backToLogin")}<p> 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 <strong>sorry</strong> ..." instead of a JSX.Element you can use msgStr("backToLogin").

Svelte

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

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

Angular

As a result calling i18n.msgStr('errorTitleHtml') return the string "We are <strong>sorry</strong> ..." 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.

Inspecting the DOM we can see that if we want to change the "Back to Login..." we need to change the "backToLogin" key.

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

Previewing Your Pages in Different Languages