Hanko Elements internationalization (i18n) guide

Hanko Elements support multiple languages and translations can be modified to alter headlines, labels, descriptions and all other texts displayed in Hanko Elements.

Hanko Elements Translations Guide:

About Hanko:

Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

What This Guide Covers: This guide demonstrates how to implement internationalization (i18n) for Hanko web components, including setting up multiple languages, customizing translations, and configuring language preferences. You’ll learn to provide a localized authentication experience for users worldwide.

Key Technologies:

• Hanko Elements
• Internationalization (i18n)
• Translation management
• Language configuration
• Web Components localization
• Multilingual user interfaces

Prerequisites:

• Basic knowledge of internationalization concepts, frontend development, and Hanko Elements setup
• Understanding of JSON file structures will be helpful

Tasks You’ll Complete:

• Configure default language settings for Hanko components
• Install and import additional language translations
• Customize existing translations to match your application’s tone
• Create new translations for unsupported languages
• Set up external translation files for dynamic language loading
• Configure fallback languages for incomplete translations
• Implement language switching in your authentication flows

Default behavior

The hanko-elements package includes English translations by default, so the lang attribute can be omitted.

Script

register("YOUR_HANKO_API_URL");

Markup

<hanko-auth></hanko-auth>

Installing additional translations

Translations are currently available for the following languages:

Value	Language
bn	Bengali (Bangla)
de	German
en	English
fr	French
it	Italian
pt-BR	Brazilian Portuguese
zh	Chinese

You can import them individually:

// Replace the paths below with
// "https://cdn.jsdelivr.net/npm/@teamhanko/hanko-elements/dist/i18n/{en|de|all|...}.js"
// if you're using CDN.

import { bn } from "@teamhanko/hanko-elements/i18n/bn";
import { de } from "@teamhanko/hanko-elements/i18n/de";
import { en } from "@teamhanko/hanko-elements/i18n/en";
import { fr } from "@teamhanko/hanko-elements/i18n/fr";
import { it } from "@teamhanko/hanko-elements/i18n/it";
import { ptBR } from "@teamhanko/hanko-elements/i18n/ptBR";
import { zh } from "@teamhanko/hanko-elements/i18n/zh";

Or import all translations at once:

import { all } from "@teamhanko/hanko-elements/i18n/all";

After importing, provide the translations through the register() function:

register("https://hanko.yourdomain.com", { translations: { bn, de, en, fr, it, ptBR, zh } });
// or
register("https://hanko.yourdomain.com", { translations: all });

You can now set the lang attribute of the element to the desired language:

<hanko-auth lang="de"></hanko-auth>

In contrast to the named import of the translation object for Brazilian Portuguese (“ptBR”), the lang attribute value must be provided as “pt-BR”. Otherwise the language is not recognized by the backend and outgoing emails will default to English.

Modifying translations

You can modify existing translations as follows:

import { en } from "@teamhanko/hanko-elements/i18n/en";

en.errors.somethingWentWrong = "Aww, snap!";

register("YOUR_HANKO_API_URL", { translations: { en } });

Adding new translations

To create a new translation, pass an object that implements (or partially implements) the Translation interface.

Script

import { all } from "@teamhanko/hanko-elements/i18n/all";
import { Translation } from "@teamhanko/hanko-elements"; // if you're using typescript

const myLang: Translation = {...}

register("YOUR_HANKO_API_URL", {translations: {...all, myLang}});

Markup

<hanko-auth lang="myLang"></hanko-auth>

Using external translation files

For languages provided via the element’s lang attribute, or via the fallback language option, that are not included in the object passed to the translations option, the component will fetch a JSON file from the location specified by the translationsLocation option. For example, if “en” is missing due to an empty object being passed, as shown in the example below, the component will fetch a file named /i18n/en.json.

Script

register("https://hanko.yourdomain.com", {
  translations: {}, // An empty object, so even the default "en" translation won't be available.
  translationsLocation: "/i18n", // A public folder containing language files, e.g., "en.json".
});

Markup

<!-- Will fetch "/i18n/en.json" -->
<hanko-auth lang="en"></hanko-auth>

Fallback language

The fallbackLanguage option is used to specify a fallback language for the web components when translations are missing or incomplete for a particular language. By setting the fallbackLanguage option to a valid language string like “en” or “de”, the missing translation strings will be automatically retrieved from the specified fallback language. When the translation for the specified fallbackLanguage is not available in the translations option, the web components will attempt to fetch it from an external file.

Script

import { en } from "@teamhanko/hanko-elements/i18n/en";
import { Translation } from "@teamhanko/hanko-elements";

const symbols: Partial<Translation> = {
  labels: { continue: "➔" },
};

register("https://hanko.yourdomain.com", {
  fallbackLanguage: "en",
  translations: { en, symbols },
});

Markup

<!-- Will appear in English, but the "continue" button label will be "➔"  -->
<hanko-auth lang="symbols"></hanko-auth>

Translation of outgoing emails

If you use Hanko Elements the language supplied to the lang attribute of any of the components is also used to convey to the Hanko API the language to use for outgoing emails. If you have disabled email delivery through Hanko and configured a webhook for the email.send event, the value for the lang attribute is reflected in the JWT payload of the token contained in the webhook request in the language claim.

If you do not use Hanko Elements but use the Hanko Frontend SDK to build your own UI you can provide a lang option when instantiating the main Hanko client. Again, if you choose to opt out of email delivery by Hanko and subscribe to the email.send event via webhook, the value used as the argument is reflected in the JWT payload of the token contained in the webhook request in the language claim.

If you do not use the Hanko frontend SDK but communicate with the Hanko API directly, then you must supply an X-Language header to requests targeting the Flow API endpoints (/registration, /login, /profile).