UI 语言环境

Logto 支持标准 OIDC 认证 (Authentication) 参数 ui_locales，用于控制特定交互的登录体验和后续通信的语言。

功能说明

• 在运行时决定 Logto 托管的登录体验的 UI 语言。Logto 会在 ui_locales 中选择你租户语言库中支持的第一个语言标签。
• 影响由该交互触发的邮件本地化（例如，验证码邮件）。详见 邮件模板本地化。
• 将原始值作为变量 uiLocales 暴露给邮件模板，你可以在邮件主题 / 内容中引用它（如有需要）。
• 设置登录体验中的默认手机号码国家区号。例如，如果 ui_locales=fr，则手机号输入框默认法国 (+33)。当你希望为特定用户群体或地区以编程方式控制默认国家区号时，这非常有用。

参数格式

• 名称：ui_locales
• 类型：string
• 值：以空格分隔的 BCP 47 语言标签列表，例如 fr-CA fr en。
• 参考：OpenID Connect Core - ui_locales

解析顺序与优先级

在决定登录体验和相关邮件的 UI 语言时，Logto 按以下顺序解析终端用户语言：

1. 当前认证 (Authentication) 请求中的 ui_locales（第一个支持的标签优先）。
2. 否则，使用 Accept-Language 头（体验 (Experience) API / 用户账户 (Account) API）或 messagePayload.locale（如组织邀请等管理 (Management) API）。
3. 否则，使用登录体验中配置的租户默认语言。

此行为不会永久更改你的语言设置，仅适用于当前交互。

SDK 用法

如果你在使用 Logto SDK，请通过登录调用的 extraParams 传递 ui_locales，以便将其转发到授权 (Authorization) 请求：

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

示例

• ui_locales=fr-CA fr en → 如果你的语言库中存在 fr-CA，登录 UI 将以法语（加拿大）显示；否则依次回退到 fr，再到 en。
• ui_locales=ja 但未启用日语 → 回退到 Accept-Language 或租户默认语言。

相关内容

• 本地化语言
• 邮件模板
• 认证 (Authentication) 参数