使用 OIDC ui_locales 本地化你的 Logto 登入體驗

為什麼要使用 ui_locales？#

Logto 已支援多語系內容和自動檢測，但有些時候你會希望明確選擇某次互動所使用的語言：

• 多組織產品，每個組織有不同語言偏好
• 來自特定語言活動的深層連結
• 具有本地化呼叫至行動 (CTA) 的產品頁面，並在相同語言啟動登入
• 用於本地化導入流程的 A/B 測試

此外，ui_locales 是許多身份提供者和 SDK 支援的標準參數。

ui_locales 做了什麼#

• 為當前互動設定登入 UI 語言（第一個支援的標籤優先）
• 影響此互動所觸發訊息的郵件本地化
• 讓原始值以變數 uiLocales 的方式暴露給郵件模板（例如："請求語言：{{uiLocales}}")

參閱更多說明：UI locales 文件。

先決條件#

• 一個 Logto 租戶（雲端或開源版）
• 已整合至 Logto 的應用程式（快速入門）
• 已在登入體驗中啟用至少一種額外語言（本地化語言）

非必要但很方便：

• 已啟用自訂郵件模板或由供應者管理的模板，來實際觀察郵件本地化（郵件模板）

選項 1：透過 SDK extraParams 使用 ui_locales#

Logto SDK 允許你在登入時傳遞額外的 OIDC 參數。在 extraParams 中加入 ui_locales：

注意事項：

• 提供以空格分隔的 BCP 47 標籤 列表。Logto 會選擇你租戶語言庫中存在的第一個標籤（例如 fr-CA，否則選擇 fr，否則選擇 en）。
• 依互動而定，不會改變你租戶的預設語言。
• 你可以將 ui_locales 與其他標準/自訂參數結合使用（例如 login_hint、organization_id，或第一畫面指令）。

選項 2：將 ui_locales 加到授權網址#

如果你是手動（或透過通用 OIDC 用戶端）構建 OIDC 授權請求，直接加上 ui_locales：

郵件如何本地化#

當一次互動會觸發郵件（例如驗證碼）時，Logto 會依下列順序決定語言：

1. ui_locales（第一個支援標籤）
2. 否則自動偵測 HTTP Accept-Language 標頭
3. 否則使用租戶的預設語言

然後 Logto 會嘗試尋找一個符合解析語言與模板類型的自訂郵件模板；如果找不到，則退回到連接器預設值。

由供應者管理的模板（例如 Postmark、HTTP Email）：Logto 會同時將 uiLocales 和 locale 傳遞給你的供應者。如果有 ui_locales，locale 就會使用 ui_locales 中第一個支援的標籤。

詳見：郵件模板本地化。

參考資料#

• UI locales 文件
• 本地化語言
• 郵件模板
• OIDC Core – ui_locales