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

為什麼要用 ui_locales？#

Logto 已經支援多語言內容和自動偵測，但有時你希望為特定互動明確選擇語言：

• 多組織產品，每個組織設定不同語言偏好
• 由特定語言推廣活動開出的 Deep link
• 本地化 CTA 的產品頁，開啟登入頁時用相同語言
• 本地化用戶入門流程的 A/B 測試

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

ui_locales 有什麼作用#

• 設置這次互動用的登入 UI 語言（使用第一個支援的標記）
• 影響由此次互動觸發訊息的電郵本地化
• 以變量 uiLocales 向電郵模板傳遞原始值（例如：「請求語言：{{uiLocales}}」）

詳情參閱：UI locales 說明文件。

前置條件#

• 一個 Logto 租戶（雲端版或 OSS 都可）
• 一個已整合 Logto 的應用程式（快速入門）
• 在登入體驗裡至少啟用了另一種語言（本地化語言）

可選但建議：

• 啟用自訂電郵模板或供應商模板，方便測試電郵本地化是否生效（電郵模板）

方案一：經 SDK extraParams 使用 ui_locales#

Logto SDK 讓你在登入時傳遞額外 OIDC 參數。於 extraParams 加入 ui_locales：

注意：

• 提供一組以空格分隔的 BCP 47 標記。Logto 會以租戶語言庫中第一個命中的標記為主（如 fr-CA，若無則 fr，再無則 en）。
• 只影響單次互動——不會更改租戶預設語言。
• 可將 ui_locales 同時與其他標準／自訂參數一起用（如 login_hint、organization_id 或指定初始畫面）。

方案二：於授權網址加上 ui_locales#

如果你用手動（或通用 OIDC client）組裝 OIDC 授權請求，在網址直接加上 ui_locales：

電郵如何本地化#

當某次互動觸發電郵（例如驗證碼），Logto 會按以下順序決定語言：

1. ui_locales（第一個支援的標記）
2. 如果沒有，則按 HTTP Accept-Language 標頭自動偵測
3. 如再沒有，則用租戶的預設語言

然後 Logto 會尋找符合語言及模板類型的自訂電郵模板，若找不到會用連接器的預設。

供應商管理模板（例如 Postmark、HTTP Email）：Logto 會把 uiLocales 和 locale 兩個傳給你的供應商。一旦有 ui_locales，locale 也用當中第一個支援的標記。

參見：電郵模板本地化。

參考資料#

• UI locales 說明文件
• 本地化語言
• 電郵模板
• OIDC 規範 – ui_locales