Merge pull request #7811 from logto-io/charles-log-12162-core-update-email-template-to-support-ui_locales-param

feat(core,toolkit): add ui_locales support in email template variables

Author: charIeszhao

packages/core/src/libraries/passcode.ts

@@ -28,7 +28,7 @@ export const passcodeMaxTryCount = 10;
 
 export type PasscodeLibrary = ReturnType<typeof createPasscodeLibrary>;
 
-export type SendPasscodeContextPayload = Pick<SendMessagePayload, 'locale'> &
+export type SendPasscodeContextPayload = Pick<SendMessagePayload, 'locale' | 'uiLocales'> &
   VerificationCodeContextInfo;
 
 export const createPasscodeLibrary = (queries: Queries, connectorLibrary: ConnectorLibrary) => {

packages/core/src/routes-me/verification-code.ts

@@ -7,6 +7,7 @@ import type { RouterInitArgs } from '#src/routes/types.js';
 
 import RequestError from '../errors/RequestError/index.js';
 import assertThat from '../utils/assert-that.js';
+import { getLogtoCookie } from '../utils/cookie.js';
 
 import type { AuthedMeRouter } from './types.js';
 
@@ -31,7 +32,11 @@ export default function verificationCodeRoutes<T extends AuthedMeRouter>(
     }),
     async (ctx, next) => {
       const code = await createPasscode(undefined, codeType, ctx.guard.body);
-      await sendPasscode(code, { locale: ctx.locale });
+      const { uiLocales } = getLogtoCookie(ctx);
+      await sendPasscode(code, {
+        locale: ctx.locale,
+        uiLocales,
+      });
 
       ctx.status = 204;
 

packages/core/src/routes/experience/verification-routes/verification-code-helpers.ts

@@ -1,21 +1,19 @@
 import {
   InteractionEvent,
-  logtoCookieKey,
-  logtoUiCookieGuard,
   SentinelActivityAction,
   SignInIdentifier,
   type VerificationCodeIdentifier,
   VerificationType,
   type Sentinel,
 } from '@logto/schemas';
 import { Action } from '@logto/schemas/lib/types/log/interaction.js';
-import { trySafe } from '@silverhand/essentials';
 
 import RequestError from '#src/errors/RequestError/index.js';
 import { type PasscodeLibrary } from '#src/libraries/passcode.js';
 import { type LogContext } from '#src/middleware/koa-audit-log.js';
 import type Libraries from '#src/tenants/Libraries.js';
 import type Queries from '#src/tenants/Queries.js';
+import { getLogtoCookie } from '#src/utils/cookie.js';
 
 import type ExperienceInteraction from '../classes/experience-interaction.js';
 import { withSentinel } from '../classes/libraries/sentinel-guard.js';
@@ -55,10 +53,7 @@ const buildVerificationCodeTemplateContext = async (
     return {};
   }
 
-  // Safely get the orgId and appId context from cookie
-  const { appId: applicationId, organizationId } =
-    trySafe(() => logtoUiCookieGuard.parse(JSON.parse(ctx.cookies.get(logtoCookieKey) ?? '{}'))) ??
-    {};
+  const { appId: applicationId, organizationId } = getLogtoCookie(ctx);
 
   return passcodeLibrary.buildVerificationCodeContext({
     applicationId,
@@ -116,6 +111,7 @@ export const sendCode = async ({
   // Send verification code
   await codeVerification.sendVerificationCode({
     locale: ctx.locale,
+    uiLocales: getLogtoCookie(ctx).uiLocales,
     ...templateContext,
   });
 

packages/core/src/routes/interaction/additional.ts

@@ -1,15 +1,12 @@
 import {
   InteractionEvent,
-  logtoCookieKey,
-  logtoUiCookieGuard,
   MfaFactor,
   type RequestVerificationCodePayload,
   requestVerificationCodePayloadGuard,
   webAuthnAuthenticationOptionsGuard,
   webAuthnRegistrationOptionsGuard,
 } from '@logto/schemas';
 import { getUserDisplayName } from '@logto/shared';
-import { trySafe } from '@silverhand/essentials';
 import { type Context } from 'koa';
 import type Router from 'koa-router';
 import { type IRouterParamContext } from 'koa-router';
@@ -25,6 +22,7 @@ import koaGuard from '#src/middleware/koa-guard.js';
 import { type WithI18nContext } from '#src/middleware/koa-i18next.js';
 import type TenantContext from '#src/tenants/TenantContext.js';
 import assertThat from '#src/utils/assert-that.js';
+import { getLogtoCookie } from '#src/utils/cookie.js';
 
 import { parseUserProfile } from './actions/helpers.js';
 import { interactionPrefix, verificationPath } from './const.js';
@@ -56,9 +54,7 @@ const buildVerificationCodeTemplateContext = async (
   }
 
   // Safely get the orgId and appId context from cookie
-  const { appId: applicationId, organizationId } =
-    trySafe(() => logtoUiCookieGuard.parse(JSON.parse(ctx.cookies.get(logtoCookieKey) ?? '{}'))) ??
-    {};
+  const { appId: applicationId, organizationId } = getLogtoCookie(ctx);
 
   return passcodeLibrary.buildVerificationCodeContext({
     applicationId,
@@ -129,7 +125,13 @@ export default function additionalRoutes<T extends IRouterParamContext>(
       const messageContext = await buildVerificationCodeTemplateContext(passcodes, ctx, guard.body);
 
       await sendVerificationCodeToIdentifier(
-        { event, ...guard.body, locale: ctx.locale, messageContext },
+        {
+          event,
+          ...guard.body,
+          locale: ctx.locale,
+          uiLocales: getLogtoCookie(ctx).uiLocales,
+          messageContext,
+        },
         interactionDetails.jti,
         createLog,
         passcodes

packages/core/src/routes/interaction/utils/verification-code-validation.ts

@@ -26,6 +26,7 @@ export const sendVerificationCodeToIdentifier = async (
   payload: RequestVerificationCodePayload & {
     event: InteractionEvent;
     locale?: string;
+    uiLocales?: string;
     messageContext?: VerificationCodeContextInfo;
   },
   jti: string,

packages/core/src/routes/verification/index.ts

@@ -13,6 +13,7 @@ import {
 import { z } from 'zod';
 
 import koaGuard from '#src/middleware/koa-guard.js';
+import { getLogtoCookie } from '#src/utils/cookie.js';
 
 import {
   buildVerificationRecordByIdAndType,
@@ -118,8 +119,11 @@ export default function verificationRoutes<T extends UserRouter>(
           ? await libraries.passcodes.buildVerificationCodeContext({ user, applicationId })
           : undefined;
 
+      const { uiLocales } = getLogtoCookie(ctx);
+
       await codeVerification.sendVerificationCode({
         locale: ctx.locale,
+        uiLocales,
         ...emailContextPayload,
       });
 

packages/core/src/utils/cookie.ts

@@ -0,0 +1,7 @@
+import { logtoUiCookieGuard, logtoCookieKey } from '@logto/schemas';
+import { trySafe } from '@silverhand/essentials';
+import { type Context } from 'koa';
+
+export const getLogtoCookie = (ctx: Context) =>
+  trySafe(() => logtoUiCookieGuard.parse(JSON.parse(ctx.cookies.get(logtoCookieKey) ?? '{}'))) ??
+  {};

packages/toolkit/connector-kit/src/types/passwordless.ts

@@ -66,6 +66,19 @@ export type SendMessagePayload = {
    * @example 'en-US'
    */
   locale?: string;
+  /**
+   * The `ui_locales` parameter from the authentication request, which can be used to localize the message.
+   * This is different from `locale` as it is the original request parameter and may contain multiple language
+   * tags sorted by user's preference.
+   * The `locale` field, is the single language tag resolved from multiple sources, and the precedence is:
+   * `ui_locales` > HTTP `Accept-Language` header > default fallback (en).
+   *
+   * @remarks
+   * For email connectors that handle email templates at the provider side, use this field to indicate the user's preferred language.
+   *
+   * @example 'en-US en'
+   */
+  uiLocales?: string;
 } & Record<string, unknown>;
 
 /** The guard for {@link SendMessagePayload}. */
@@ -74,6 +87,7 @@ export const sendMessagePayloadGuard = z
     code: z.string().optional(),
     link: z.string().optional(),
     locale: z.string().optional(),
+    uiLocales: z.string().optional(),
   })
   .catchall(z.unknown()) satisfies z.ZodType<SendMessagePayload>;