简体中文
  • 本地化
  • 国际化
  • i18n
  • l10n
  • ui_locales
  • locale

通过 OIDC ui_locales 本地化你的 Logto 登录体验

让你的登录体验对每位用户都像原生应用。在本教程中，你将学习如何使用标准 OIDC 参数 ui_locales 设置 Logto 登录界面及相关邮件的运行时语言。

Charles
Charles
Developer

不要在用户认证上浪费数周时间
使用 Logto 更快地发布安全应用。几分钟内集成用户认证，专注于您的核心产品。
立即开始
Product screenshot

为什么要使用 ui_locales？

Logto 已经支持多语言内容和自动检测，但有些场景你可能想为某个具体交互明确选择语言：

  • 多组织产品每个组织偏好不同语言
  • 来自特定语言市场活动的深度链接
  • 产品页面中的本地化 CTA，确保登录流程语言一致
  • 本地化引导流程的 A/B 测试

此外，ui_locales 是许多身份提供商和 SDK 支持的标准参数。

ui_locales 的作用

  • 为当前交互设置登录界面语言（优先使用支持的第一个 tag）
  • 影响因该交互触发的邮件的本地化
  • 将原始值以变量 uiLocales 暴露给邮件模板（例如：“请求的语言：{{uiLocales}}”）

参考文档查看更多：界面本地化文档。

前置条件

  • 一个 Logto 租户（云端或 OSS）
  • 一个已经集成 Logto 的应用（快速入门）
  • 登录体验中至少开启了一种额外语言（本地化语言）

可选但很实用：

  • 已启用自定义邮件模板或由提供商管理的模板，用以体验邮件本地化效果（邮件模板）

方案一：通过 SDK extraParams 传递 ui_locales

Logto SDK 支持在登录时传递额外的 OIDC 参数。将 ui_locales 加入 extraParams：

注意：

  • 需提供以空格分隔的 BCP 47 标签 列表。Logto 会选择租户语言库中支持的第一个标签（比如 fr-CA，否则 fr，再否则 en）。
  • 仅影响当前交互，不会改变租户默认语言。
  • 你可以将 ui_locales 和其它标准/自定义参数组合使用（如 login_hint、organization_id 或首屏指令等）。

方案二：在授权 URL 中添加 ui_locales

如果你手动拼装 OIDC 授权请求（或使用通用 OIDC 客户端），可以直接添加 ui_locales：

邮件如何本地化

当某次交互触发邮件（例如验证码）时，Logto 按如下优先级解析语言：

  1. ui_locales（首先支持的 tag）
  2. 否则通过 HTTP Accept-Language 头自动检测
  3. 否则使用租户默认语言

随后 Logto 会尝试查找与已解析语言和模板类型匹配的自定义邮件模板；如未找到，则回退到连接器默认模板。

由服务商托管的模板（如 Postmark、HTTP Email）：Logto 会同时传递 uiLocales 和 locale 给你的服务商。如果 ui_locales 存在，locale 会使用 ui_locales 的第一个支持标签。

详见：邮件模板本地化。

参考

免费试用 Logto 云