> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hanko.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<div class="hidden">
  **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
</div>

## Default behavior

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

Script

```js theme={null}
register("YOUR_HANKO_API_URL");
```

Markup

```html theme={null}
<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:

```js theme={null}
// 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:

```js theme={null}
import { all } from "@teamhanko/hanko-elements/i18n/all";
```

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

```js theme={null}
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:

```html theme={null}
<hanko-auth lang="de"></hanko-auth>
```

<Warning>
  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.
</Warning>

## Modifying translations

You can modify existing translations as follows:

```js theme={null}
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

```js theme={null}
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

```html theme={null}
<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

```js theme={null}
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

```html theme={null}
<!-- 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

```js theme={null}
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

```html theme={null}
<!-- 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](https://teamhanko.github.io/hanko/jsdoc/hanko-frontend-sdk/HankoOptions.html) when instantiating the main
`Hanko` [client](https://teamhanko.github.io/hanko/jsdoc/hanko-frontend-sdk/Hanko.html). 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`](https://docs.hanko.io/api-reference/flow/registration),
[`/login`](https://docs.hanko.io/api-reference/flow/login),
[`/profile`](https://docs.hanko.io/api-reference/flow/profile)).