Resolving ui_locales Issues with Language Variants in Auth0 Universal Login

Knowledge Articles
1

Overview

This article explains how to resolve an issue where Auth0 Universal Login falls back to the default language instead of the intended language. This can occur when an application passes a language code with a regional variant, such as de-DE , in the ui_locales parameter. This guide provides a solution to ensure the correct localization is displayed.

Applies To

  • Branding
  • Universal Login

Cause

Auth0 supports specific language codes. This support varies; some languages might only be supported by their base code (e.g., de), while others require specific regional variants (e.g., fr-FR or fr-CA).

If Auth0 primarily supports a language via its base code (e.g., de for German), providing a regional variant like de-DE alone will cause the system to fall back to the tenant’s default locale (often English).

Solution

To ensure consistent localization and prevent fallbacks, use the space-delimited list capability of the ui_locales parameter.

  1. Structure the ui_locales parameter value to specify the most precise locale first, followed by the more general fallback locale.
  2. For example, if an application sends de-DE and German is enabled in the tenant as de, set the parameter as follows:
de-DE de
  1. With this configuration, Auth0 first attempts to match de-DE. If that specific locale is not enabled, it evaluates the next locale in the list, successfully matching de and rendering the Universal Login page in German. The HTML page’s lang attribute is set to de.
  2. A complete authorization URL would appear similar to this:
https://<auth0-domain>.auth0.com/authorize?ui_locales=de-DE de&client_id=<CLIENT_ID>&scope=openid profile&redirect_uri=<REDIRECT_URI>&response_type=code

This [variant] [base_language] format provides forward compatibility. If Auth0 later adds support for a specific variant like de-DE, no changes are needed in the application. The new language variant only needs to be enabled in the tenant settings to be matched directly. For a current list of supported languages, refer to the Universal Login Internationalization documentation.