Skip to main content

UI locales

Logto supports the standard OIDC authentication parameter ui_locales to control the language of the sign-in experience and downstream communications for a given interaction.

What it does​

  • Determines the UI language of the Logto-hosted sign-in experience at runtime. Logto picks the first language tag in ui_locales that is supported in your tenant's language library.
  • Affects email localization for messages triggered by the interaction (e.g., verification code emails). See Email template localization.
  • Exposes the original value to email templates as a variable uiLocales, allowing you to include it in the email subject/content if needed.
  • Sets the default phone number country code in the sign-in experience. For example, if ui_locales=fr, the phone number input field will default to France (+33). This is useful when you want to control the default country code programmatically for specific user groups or regions.

Parameter format​

Resolution order and precedence​

When determining the UI language for the sign-in experience and related emails, Logto resolves the end-user language using this order:

  1. ui_locales from the current authentication request (first supported tag wins).
  2. Otherwise, Accept-Language header (Experience APIs / User Account APIs) or messagePayload.locale (Management APIs like organization invitations).
  3. Otherwise, the tenant's default language configured in Sign-in Experience.

This behavior does not permanently change your language settings; it only applies to the current interaction.

SDK usage​

If you're using a Logto SDK, pass ui_locales via the extraParams of the sign-in call so it is forwarded to the authorization request:

await logtoClient.signIn({
  redirectUri: 'https://your.app/callback',
  extraParams: {
    ui_locales: 'fr-CA fr en',
  },
});

Examples​

  • ui_locales=fr-CA fr en → If fr-CA exists in your language library, the sign-in UI renders in French (Canada); otherwise it falls back to fr, then en.
  • ui_locales=ja but Japanese is not enabled → Falls back to Accept-Language or tenant default.