English
  • localization
  • internationalization
  • i18n
  • l10n
  • ui_locales
  • locale

Localize your Logto sign-in experience with OIDC ui_locales

Make your sign-in experience feel native to every user. In this tutorial, you’ll learn how to use the standard OIDC parameter ui_locales to set the runtime language of Logto’s sign-in UI and related emails.

Charles
Charles
Developer

Stop wasting weeks on user auth
Launch secure apps faster with Logto. Integrate user auth in minutes, and focus on your core product.
Get started
Product screenshot

Why use ui_locales?

Logto already supports multi-language content and auto-detection, but there are times you want to explicitly pick the language for a specific interaction:

  • Multi-organization products with different language preferences per org
  • Deep links from campaigns in a specific language
  • Product pages with localized CTAs that start sign-in in the same language
  • A/B tests for localized onboarding

Besides, ui_locales is a standard parameter supported by many identity providers and SDKs.

What ui_locales does

  • Sets the sign-in UI language for the current interaction (first supported tag wins)
  • Influences email localization for messages triggered by this interaction
  • Exposes the original value to email templates as a variable uiLocales (e.g., "Requested languages: {{uiLocales}}")

Learn more in the reference: UI locales docs.

Prerequisites

  • A Logto tenant (Cloud or OSS)
  • An application integrated with Logto (Quick-starts)
  • At least one additional language enabled in Sign-in Experience (Localized languages)

Optional but handy:

  • Custom email templates or provider-managed templates enabled, to see email localization in action (Email templates)

Option 1: Use ui_locales via SDK extraParams

Logto SDKs let you pass extra OIDC parameters during sign-in. Add ui_locales in extraParams:

Notes:

  • Provide a space-separated list of BCP 47 tags. Logto will pick the first tag that exists in your tenant’s language library (e.g., fr-CA, otherwise fr, otherwise en).
  • Works per interaction—your tenant’s default language is not changed.
  • You can combine ui_locales with other standard/custom parameters (e.g., login_hint, organization_id, or first screen directives).

Option 2: Add ui_locales to your authorize URL

If you’re wiring the OIDC authorization request manually (or via a generic OIDC client), add ui_locales directly:

How emails are localized

When an interaction triggers an email (e.g., verification code), Logto resolves language in this order:

  1. ui_locales (first supported tag)
  2. Otherwise auto detects via HTTP Accept-Language header
  3. Otherwise tenant default language

Then Logto tries to find a custom email template that matches the resolved language and template type; if none is found, it falls back to the connector default.

Provider-managed templates (e.g., Postmark, HTTP Email): Logto passes both uiLocales and locale to your provider. If ui_locales is present, locale uses the first supported tag from ui_locales.

See: Email template localization.

Reference

Try Logto Cloud for free