feat(#13881): sys_user.locale + per-recipient notification locale — translations, docs regen, retry-path fix

Author: claude

content/docs/references/automation/io-node-config.mdx

@@ -96,7 +96,7 @@ const result = HttpConfigSchema.parse(data);
 | **recipients** | `string \| string[]` | ✅ | Recipient user id(s) / audience selector(s); `{token}` templates resolve per run |
 | **title** | `string` | optional | Notification title, sent to every recipient verbatim (not localizable — use `template` for per-locale content). Either this or `template` is required; the two are mutually exclusive. |
 | **message** | `string` | optional | Notification body, sent verbatim like `title` (not localizable). Only valid with inline `title`, never with `template`. |
-| **template** | `string` | optional | Email template name (`sys_email_template.name`, e.g. `crm.large_deal_won`) — the localizable content path: the delivery path resolves `(name, locale)` against sys_email_template at delivery time and renders subject/body from that row. The locale is ONE value for the whole notification, not one per recipient: `payload.locale` if the producer set one, else the deployment default (`II18nService.getDefaultLocale()`) — the platform has no per-user locale, so recipients with different personal languages all receive the same row (deferred by the 2026-08-13 ruling; it layers in as an override when it lands). Mutually exclusive with inline `title`/`message`, which are the non-localizable path. Read raw — no `{token}` interpolation. |
+| **template** | `string` | optional | Email template name (`sys_email_template.name`, e.g. `crm.large_deal_won`) — the localizable content path: the delivery path resolves `(name, locale)` against sys_email_template at delivery time and renders subject/body from that row. The locale is resolved per recipient, after fan-out: the recipient's own `sys_user.locale` when set, else the deployment default (`II18nService.getDefaultLocale()`) — so recipients whose personal languages differ receive different rows of the same bundle (maintainer ruling 2026-09-01). A producer-set `payload.locale` is not consulted. Mutually exclusive with inline `title`/`message`, which are the non-localizable path. Read raw — no `{token}` interpolation. |
 | **templateData** | `Record<string, any>` | optional | Render context for the referenced template's `{{var}}` placeholders; values interpolate `{token}` templates per run. Only valid together with `template`. |
 | **channels** | `string \| string[]` | optional | Channels to fan out to (default: inbox) |
 | **topic** | `string` | optional | Event topic (default: "notify") |

packages/platform-objects/src/apps/translations/en.objects.generated.ts

@@ -91,6 +91,10 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       image: {
         label: "Profile Image"
       },
+      locale: {
+        label: "Locale",
+        help: "Preferred language for notifications, as a BCP-47 tag (e.g. zh-CN, ja-JP). Read per recipient at delivery time; when unset the deployment default applies. Owned by objectql (better-auth is oblivious to this column)."
+      },
       manager_id: {
         label: "Manager",
         help: "This user's direct manager. Forms the reporting chain the `own_and_reports` hierarchy scope walks (ADR-0057 / @objectstack/security-enterprise)."

packages/platform-objects/src/apps/translations/es-ES.objects.generated.ts

@@ -91,6 +91,10 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       image: {
         label: "Imagen de perfil"
       },
+      locale: {
+        label: "Idioma",
+        help: "Idioma preferido para las notificaciones, como etiqueta BCP-47 (p. ej. zh-CN, ja-JP). Se lee por destinatario en el momento de la entrega; si no está definido, se aplica el idioma predeterminado del despliegue. Propiedad de objectql (better-auth ignora esta columna)."
+      },
       manager_id: {
         label: "Gerente",
         help: "This user's direct manager. Forms the reporting chain the `own_and_reports` hierarchy scope walks (ADR-0057 / @objectstack/security-enterprise)."

packages/platform-objects/src/apps/translations/es-ES.source-hashes.generated.ts

@@ -589,6 +589,8 @@ export const esESGeneratedSourceHashes: Readonly<Record<string, string>> = {
   "objects.sys_two_factor.fields.locked_until.label": "c7f013ad9b7208d2",
   "objects.sys_two_factor.fields.verified.help": "0d351ba4c31608c2",
   "objects.sys_two_factor.fields.verified.label": "866e3a245ef04734",
+  "objects.sys_user.fields.locale.help": "51a0ce37d494be54",
+  "objects.sys_user.fields.locale.label": "92b39430e88d3b51",
   "objects.sys_user.fields.manager_id.help": "a53dec9ccd9d131f",
   "objects.sys_user.fields.primary_business_unit_id.help": "e01690f4a9b83956",
   "objects.sys_view_definition.fields.id.label": "00b0385c9c152888",

packages/platform-objects/src/apps/translations/ja-JP.objects.generated.ts

@@ -91,6 +91,10 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       image: {
         label: "プロフィール画像"
       },
+      locale: {
+        label: "言語",
+        help: "通知に使用する優先言語（BCP-47 タグ、例: zh-CN、ja-JP）。配信時に受信者ごとに読み取られ、未設定の場合はデプロイのデフォルト言語が適用されます。objectql が所有します（better-auth はこの列を認識しません）。"
+      },
       manager_id: {
         label: "マネージャー",
         help: "This user's direct manager. Forms the reporting chain the `own_and_reports` hierarchy scope walks (ADR-0057 / @objectstack/security-enterprise)."

packages/platform-objects/src/apps/translations/ja-JP.source-hashes.generated.ts

@@ -580,6 +580,8 @@ export const jaJPGeneratedSourceHashes: Readonly<Record<string, string>> = {
   "objects.sys_two_factor.fields.locked_until.label": "c7f013ad9b7208d2",
   "objects.sys_two_factor.fields.verified.help": "0d351ba4c31608c2",
   "objects.sys_two_factor.fields.verified.label": "866e3a245ef04734",
+  "objects.sys_user.fields.locale.help": "51a0ce37d494be54",
+  "objects.sys_user.fields.locale.label": "92b39430e88d3b51",
   "objects.sys_user.fields.manager_id.help": "a53dec9ccd9d131f",
   "objects.sys_user.fields.primary_business_unit_id.help": "e01690f4a9b83956",
   "objects.sys_view_definition.fields.id.label": "00b0385c9c152888",

packages/platform-objects/src/apps/translations/zh-CN.objects.generated.ts

@@ -91,6 +91,10 @@ export const zhCNObjects: NonNullable<TranslationData['objects']> = {
       image: {
         label: "头像"
       },
+      locale: {
+        label: "语言",
+        help: "通知使用的首选语言，BCP-47 标签（如 zh-CN、ja-JP）。投递时按收件人读取；未设置时采用部署默认语言。归 objectql 所有（better-auth 不感知此列）。"
+      },
       manager_id: {
         label: "经理",
         help: "This user's direct manager. Forms the reporting chain the `own_and_reports` hierarchy scope walks (ADR-0057 / @objectstack/security-enterprise)."

packages/platform-objects/src/apps/translations/zh-CN.source-hashes.generated.ts

@@ -527,6 +527,8 @@ export const zhCNGeneratedSourceHashes: Readonly<Record<string, string>> = {
   "objects.sys_two_factor.fields.locked_until.label": "c7f013ad9b7208d2",
   "objects.sys_two_factor.fields.verified.help": "0d351ba4c31608c2",
   "objects.sys_two_factor.fields.verified.label": "866e3a245ef04734",
+  "objects.sys_user.fields.locale.help": "51a0ce37d494be54",
+  "objects.sys_user.fields.locale.label": "92b39430e88d3b51",
   "objects.sys_user.fields.manager_id.help": "a53dec9ccd9d131f",
   "objects.sys_user.fields.primary_business_unit_id.help": "e01690f4a9b83956",
   "objects.sys_view_definition.fields.id.label": "00b0385c9c152888",

packages/services/service-messaging/src/email-channel.test.ts

@@ -396,14 +396,14 @@ describe('email channel', () => {
             const data = fakeData({ users: {} });
             await build(data, email, 'ja-JP').send(silentCtx(), templated('bob@example.com'));
             expect(email.templated[0]).toMatchObject({ to: 'bob@example.com', locale: 'ja-JP' });
-            expect(data.findOnes.filter((q) => q.object === 'sys_user')).toHaveLength(0);
+            expect(data.findOnes.filter((q: { object: string }) => q.object === 'sys_user')).toHaveLength(0);
         });
 
         it('reads the locale off the SAME sys_user row as the address — one query per recipient, no second read point', async () => {
             const email = templateEmail();
             const data = fakeData({ users: { user_1: { email: 'ada@example.com', locale: 'zh-CN' } } });
             await build(data, email, 'ja-JP').send(silentCtx(), templated());
-            const userReads = data.findOnes.filter((q) => q.object === 'sys_user');
+            const userReads = data.findOnes.filter((q: { object: string }) => q.object === 'sys_user');
             expect(userReads).toHaveLength(1);
             expect(userReads[0].query).toEqual({ where: { id: 'user_1' }, fields: ['email', 'locale'] });
         });

packages/services/service-messaging/src/email-channel.ts

@@ -168,11 +168,16 @@ export function createEmailChannel(opts: EmailChannelOptions): MessagingChannel
         }
         if (!data) return undefined;
         let user: Record<string, unknown> | null | undefined;
+        // Set only when the row was read WITH the locale projection: after a
+        // retry the column was never asked for, so whatever the row carries
+        // under that key is not a read — rung 2 applies.
+        let localeRead = false;
         try {
             user = await data.findOne(userObject, {
                 where: { id: recipient },
                 fields: ['email', RECIPIENT_LOCALE_FIELD],
             });
+            localeRead = true;
         } catch (err) {
             // Ruling item 3: NO path may dead-letter because of the locale
             // read. A `userObject` override that lacks the column must still
@@ -193,7 +198,7 @@ export function createEmailChannel(opts: EmailChannelOptions): MessagingChannel
         if (!(typeof email === 'string' && EMAIL_SHAPE(email))) return undefined;
         return {
             address: email,
-            locale: resolveRecipientLocale(user?.[RECIPIENT_LOCALE_FIELD], deploymentLocale),
+            locale: resolveRecipientLocale(localeRead ? user?.[RECIPIENT_LOCALE_FIELD] : undefined, deploymentLocale),
         };
     }