跳到主要内容

UI 语言环境

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

功能说明​

  • 决定 Logto 托管的登录体验界面在运行时的 UI 语言。Logto 会选择 ui_locales 中在你租户语言库中支持的第一个语言标签。
  • 影响由该交互触发的邮件本地化（如验证码邮件）。详见 邮件模板本地化。
  • 将原始值作为变量 uiLocales 暴露给邮件模板，你可以根据需要将其包含在邮件主题或内容中。

参数格式​

解析顺序与优先级​

在确定登录体验和相关邮件的 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 或租户默认语言。