跳至主要內容

UI 語言區域 (UI locales)

Logto 支援標準 OIDC 驗證 (Authentication) 參數 ui_locales,用於控制特定互動流程中的登入體驗 (Sign-in experience) 及後續溝通語言。

功能說明

  • 決定 Logto 託管登入體驗 (Sign-in experience) 的 UI 語言。Logto 會於 ui_locales 中選擇租戶語言庫支援的第一個語言標籤。
  • 影響互動過程觸發的郵件本地化(例如驗證碼郵件)。詳見 郵件範本本地化
  • 將原始值以變數 uiLocales 暴露給郵件範本,方便你在郵件主旨/內容中引用。

參數格式

決議順序與優先權

決定登入體驗 (Sign-in experience) 及相關郵件的 UI 語言時,Logto 依下列順序解析終端使用者語言:

  1. 目前驗證 (Authentication) 請求中的 ui_locales(優先採用第一個支援的標籤)。
  2. 若無,則採用 Accept-Language 標頭(使用體驗 (Experience) API/使用者帳號 (Account) API)或 messagePayload.locale(如組織邀請等 Management API)。
  3. 若仍無,則採用登入體驗 (Sign-in experience) 設定的租戶預設語言。

此行為不會永久變更你的語言設定,僅適用於當前互動。

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 以加拿大法語顯示;否則依序退回 fren
  • ui_locales=ja 但未啟用日文 → 退回至 Accept-Language 或租戶預設語言。