Languages
The languages identity speaks, how it picks one for a page or an email, what stays in English, and how an application can ask for a language.
On this page
Identity has messages in three languages: English, Français (French) and Español (Spanish). English is the source of every message and the default, and it is always on. French and Spanish are served only where a deployment has switched them on. Until a language is switched on it is never offered and never chosen, from any source below. This page explains how identity decides which language to use, which parts are always English, and how an application can ask for a language.
What is translated#
The sign-in and registration pages, account recovery, the account area, the command palette and the emails identity sends have messages in all three languages, shown in each language that is switched on. The legal pages under Trust are translated too. A legal page that has no translation in your language is shown in English, with a notice above it saying so.
A language is matched by its primary tag. A regional tag such as fr-CA or es-MX shows French or Spanish, where that language is on. A language identity has no messages for, such as German, or has not switched on, is not chosen, and identity moves on to the next source below.
How the language of a page is chosen#
Identity looks at these sources in order and uses the first that names a supported language.
| Order | Source | When it applies |
|---|---|---|
| 1 | Your saved language | You are signed in and your profile has a language identity supports. |
| 2 | The application's request | You are in the middle of a sign-in that an application started with a ui_locales list. |
| 3 | The language switcher | You picked a language on a sign-in page in this browser. |
| 4 | Your browser | The Accept-Language setting your browser sends, best match first. |
| 5 | English | Nothing above named a language identity supports. |
Two consequences follow from the order. A signed-in person always sees their own saved language, whatever an application asks for. And while your saved language or an application's request decides the language, the switcher is not shown, because choosing a language there would change nothing. It is also not shown when English is the only language on.
Four signed-out pages are the exception: the signed-out page, the error page, the full-page Confirm it is you and the page where you choose a password (and can add a passkey) while you register. They are built ahead of time, once per language, so they cannot read your profile or the sign-in in progress. They use only the language switcher and your browser (rows 3 and 4 above), then English, and the switcher is shown on them whenever more than one language is on.
If identity cannot read your saved language or the sign-in's request, it does not fail the page. It falls through to the next source.
Save a language in your profile#
To make the account area and the sign-in pages follow a language, save it in your profile. Saving a supported language changes the interface language the next time a page loads. See Language and time zone.
The language switcher#
On the signed-out pages a switcher shows each language in its own name. Choosing one reloads the page in that language and remembers the choice in this browser. The remembered choice is a small cookie that holds only the language code and is set only when you use the switcher. It is listed on the Cookies and local storage page. Clearing it makes the pages follow your browser's language again.
Emails#
An email goes out in the language of the person who receives it:
- the language saved in their profile, if identity supports it;
- otherwise the
ui_localesof the sign-in or registration that caused the email; - otherwise English.
The browser's language and the switcher choice do not affect emails, because an email is sent to an address and not to a browser. Sign-in codes, links, security alerts and account notices all follow this rule. Dates in French and Spanish emails are written in the language's own style and are in UTC, with the zone named.
What stays in English#
| Part | Why |
|---|---|
| This documentation book | The pages are written in English. Navigation labels around them follow your language. |
error_description in protocol errors | It is text for an application's logs, not for a person. An application shows its own message. |
| Protocol values | Parameter names, scopes, claims, error codes and URLs are the same in every language. |
For developers: ask for a language#
An application can ask identity to show the sign-in pages in a language with the standard ui_locales parameter of OpenID Connect Core section 3.1.2.1. It is a space-separated list of language tags, best first. Identity uses the first tag it supports.
Send it in the pushed authorization request, where every other authorization parameter goes:
POST /parContent-Type: application/x-www-form-urlencodedclient_id=tdaid_c_example&response_type=code&scope=openid&ui_locales=fr-CA%20en&...With that request a visitor with no saved language and no earlier choice sees the sign-in in French. If the list were de en, identity would skip de and show English.
Rules for the value:
- At most eight tags.
- Each tag is a language followed by optional dash-separated subtags of letters and digits, at most 35 characters.
fr,fr-CAandzh-Hant-TWare well formed. - A badly formed or oversized list is refused with
invalid_request. - A well-formed tag for a language identity does not support is accepted and ignored.
ui_locales is only a preference. It never overrides a signed-in person's saved language, and it does not change the language of your application or of the protocol responses.
With the SDK, pass uiLocales when you start the authorization:
const { url, transaction } = await rp.startAuthorization({ scope: 'openid profile', uiLocales: ['fr-CA', 'en'],})The SDK joins the list with spaces and pushes it as ui_locales. See Relying-party module and Authorization code with PKCE.