UI 語言區域 (UI locales)
Logto 支援標準 OIDC 驗證 (Authentication) 參數 ui_locales
,用於控制特定互動流程中的登入體驗 (Sign-in experience) 及後續溝通語言。
功能說明
- 決定 Logto 託管登入體驗 (Sign-in experience) 的 UI 語言。Logto 會於
ui_locales
中選擇租戶語言庫支援的第一個語言標籤。 - 影響互動過程觸發的郵件本地化(例如驗證碼郵件)。詳見 郵件範本本地化。
- 將原始值以變數
uiLocales
暴露給郵件範本,方便你在郵件主旨/內容中引用。
參數格式
- 名稱:
ui_locales
- 類型:
string
- 值:以空格分隔的 BCP 47 語言標籤列表,例如
fr-CA fr en
。 - 參考:OpenID Connect Core - ui_locales
決議順序與優先權
決定登入體驗 (Sign-in experience) 及相關郵件的 UI 語言時,Logto 依下列順序解析終端使用者語言:
- 目前驗證 (Authentication) 請求中的
ui_locales
(優先採用第一個支援的標籤)。 - 若無,則採用
Accept-Language
標頭(使用體驗 (Experience) API/使用者帳號 (Account) API)或messagePayload.locale
(如組織邀請等 Management API)。 - 若仍無,則採用登入體驗 (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 以加拿大法語顯示;否則依序退回fr
、en
。ui_locales=ja
但未啟用日文 → 退回至Accept-Language
或租戶預設語言。