Merge pull request #7802 from logto-io/charles-log-12192-log-12163-support-ui-locales

feat(core,experience,schemas): support ui_locales in Experience UI

Author: charIeszhao

packages/core/src/middleware/koa-experience-ssr.ts

@@ -49,6 +49,7 @@ export default function koaExperienceSsr<StateT, ContextT extends WithI18nContex
       ctx,
       languageInfo: signInExperience.languageInfo,
       customLanguages,
+      lng: typeof ctx.query.lng === 'string' ? ctx.query.lng : undefined,
     });
     const phrases = await libraries.phrases.getPhrases(language);
 

packages/core/src/oidc/init.ts

@@ -218,6 +218,7 @@ export default function initOidc(
             removeUndefinedKeys({
               appId: typeof appId === 'string' ? appId : undefined,
               organizationId: params.organization_id,
+              uiLocales: params.ui_locales,
             }) satisfies LogtoUiCookie
           ),
           { sameSite: 'lax', overwrite: true, httpOnly: false }

packages/core/src/utils/i18n.ts

@@ -35,7 +35,7 @@ export const getExperienceLanguage = ({
   lng,
 }: GetExperienceLanguage) => {
   const acceptableLanguages = conditionalArray<string | string[]>(
-    lng,
+    lng?.split(/\s+/).filter(Boolean),
     autoDetect && detectLanguage(ctx),
     fallbackLanguage
   );

packages/experience/src/i18n/utils.ts

@@ -7,17 +7,24 @@ import i18next from 'i18next';
 import LanguageDetector from 'i18next-browser-languagedetector';
 
 import { getPhrases as getPhrasesApi } from '@/apis/settings';
+import { searchKeys } from '@/utils/search-parameters';
 
 const getPhrases = async (language?: string) => {
-  // Directly use the server-side phrases if it's already fetched
-  if (isObject(logtoSsr) && (!language || logtoSsr.phrases.lng === language)) {
+  const uiLocales = sessionStorage.getItem(searchKeys.uiLocales) ?? undefined;
+  const uiLocalesFirst = uiLocales?.trim().split(/\s+/)[0];
+  const preferredLanguage = language ?? uiLocales;
+
+  if (
+    isObject(logtoSsr) &&
+    (!preferredLanguage || logtoSsr.phrases.lng === (language ?? uiLocalesFirst))
+  ) {
     return { phrases: logtoSsr.phrases.data, lng: logtoSsr.phrases.lng };
   }
 
   const detectedLanguage = detectLanguage();
   const response = await getPhrasesApi({
     localLanguage: Array.isArray(detectedLanguage) ? detectedLanguage.join(' ') : detectedLanguage,
-    language,
+    language: preferredLanguage,
   });
 
   const remotePhrases = await response.json<LocalePhrase>();

packages/experience/src/utils/search-parameters.ts

@@ -1,6 +1,6 @@
 import { condString } from '@silverhand/essentials';
 
-export const searchKeysCamelCase = Object.freeze(['organizationId', 'appId'] as const);
+export const searchKeysCamelCase = Object.freeze(['organizationId', 'appId', 'uiLocales'] as const);
 
 type SearchKeysCamelCase = (typeof searchKeysCamelCase)[number];
 
@@ -9,8 +9,15 @@ export const searchKeys = Object.freeze({
    * The key for specifying the organization ID that may be used to override the default settings.
    */
   organizationId: 'organization_id',
-  /** The current application ID. */
+  /**
+   * The current application ID.
+   */
   appId: 'app_id',
+  /**
+   * The end-user's preferred languages, presented as a space-separated list of BCP47 language tags.
+   * E.g. `en` or `en-US` or `en-US en`.
+   */
+  uiLocales: 'ui_locales',
 } satisfies Record<SearchKeysCamelCase, string>);
 
 export const handleSearchParametersData = () => {

packages/schemas/src/types/cookie.ts

@@ -5,8 +5,9 @@ import { type ToZodObject } from '../utils/zod.js';
 export type LogtoUiCookie = Partial<{
   appId: string;
   organizationId: string;
+  uiLocales: string;
 }>;
 
 export const logtoUiCookieGuard = z
-  .object({ appId: z.string(), organizationId: z.string() })
+  .object({ appId: z.string(), organizationId: z.string(), uiLocales: z.string() })
   .partial() satisfies ToZodObject<LogtoUiCookie>;

packages/schemas/src/types/ssr.ts

@@ -9,6 +9,7 @@ export type SsrData = {
   signInExperience: {
     appId?: string;
     organizationId?: string;
+    uiLocales?: string;
     data: FullSignInExperience;
   };
   phrases: {