OIDC ui_locales 로 Logto 로그인 경험 현지화하기

왜 ui_locales 를 사용해야 하죠?#

Logto 는 이미 다국어 콘텐츠와 자동 감지를 지원하지만, 특정 상호작용에서 명시적으로 언어를 지정하고 싶을 때가 있습니다:

• 조직별로 다른 언어 선호도를 가진 다중 조직 제품
• 특정 언어 캠페인에서 딥링크로 진입하는 경우
• 현지화된 CTA 로 시작하는 제품 페이지에서 로그인도 같은 언어로 시작해야 할 때
• 현지화된 온보딩의 A/B 테스트

게다가, ui_locales 는 많은 신원 제공자들과 SDK 들이 지원하는 표준 파라미터입니다.

ui_locales 가 하는 일#

• 현재 상호작용에서 로그인 UI 언어를 설정합니다(가장 먼저 지원되는 태그가 우선).
• 이 상호작용 중 트리거되는 이메일 메시지의 현지화에 영향을 줍니다.
• 원래 값을 이메일 템플릿의 변수 uiLocales 로 노출합니다 (예: "요청한 언어: {{uiLocales}}")

자세한 내용은 참고 문서를 확인하세요: UI locales docs.

사전 준비#

• Logto 테넌트 (Cloud 또는 OSS)
• 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: authorize URL 에 ui_locales 추가하기#

OIDC 인증 요청을 직접 작성(혹은 범용 OIDC 클라이언트 통해) 하는 경우, URL 에 ui_locales 를 직접 추가하세요:

이메일이 현지화되는 방식#

상호작용이 이메일(예: 인증 코드)을 트리거할 때, Logto 는 다음 우선순위로 언어를 판단합니다:

1. ui_locales (가장 먼저 지원되는 태그)
2. 없으면 HTTP Accept-Language 헤더로 자동 감지
3. 그래도 없으면 테넌트 기본 언어

이후 Logto 는 판단된 언어와 템플릿 종류에 맞는 커스텀 이메일 템플릿을 먼저 찾고; 없으면 커넥터 기본값으로 대체합니다.

공급자 관리형 템플릿(예: Postmark, HTTP Email)의 경우: Logto 는 uiLocales 와 locale 을 공급자에게 전달합니다. ui_locales 가 있으면 locale 은 그 중 첫 번째 지원되는 태그가 됩니다.

자세한 안내: 이메일 템플릿 현지화.

참고 자료#

• UI locales docs
• 현지화된 언어
• 이메일 템플릿
• OIDC Core – ui_locales