fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;

.changeset/auth-email-locale-workspace-language.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default (#14319)
+
+Auth mail (verification, password reset, invitation, magic link, email-change
+notice) picked its `sys_email_template` row from
+`II18nService.getDefaultLocale()` alone — the app artifact's **build-time**
+`i18n.defaultLocale`, which is the bare `en` unless the app declares otherwise.
+The workspace's **runtime** language, `localization.locale` (ADR-0053, Setup ▸
+Localization), was never consulted, even though the very same `kernel:ready`
+pass already reads it a dozen lines earlier to localize auth SMS, and the four
+options that setting offers are exactly the four locales the auth templates
+ship rows for.
+
+A workspace that switched itself to Chinese therefore received Chinese OTP
+texts and English verification mail from one plugin, on one boot.
+
+`AuthPlugin` now prefers `localization.locale` whenever the operator has
+**explicitly** set it (`ResolvedSettingValue.source !== 'default'`) — the same
+precedence the sibling `branding.workspace_name` binding uses — and keeps the
+build-time `i18n.defaultLocale` standing underneath it, so a deployment that
+declared one is not demoted to the manifest default `en-US`. Neither producer
+answering leaves the locale unnamed, which is `EmailService`'s documented
+`en-US` fallback. The binding live-rebinds on `localization` settings changes,
+exactly as the SMS one does.
+
+The 2026-08-13 ruling is unchanged: the recipient locale is the deployment
+default, resolved at the plugin layer; `Accept-Language` stays rejected and
+there is still no per-user locale.

content/docs/permissions/system-context.mdx

@@ -97,7 +97,7 @@ that silently does not happen.
 | 8 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `security-plugin.ts:3857` |
 | 9 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `anonymous-deny.ts:154` |
 | 10 | Permission-set projection middleware skipped | plugin-security | Lose: projection of permission-set-derived columns | `permission-set-projection.ts:1015` |
-| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1301` |
+| 11 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `auth-plugin.ts:1345` |
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4552,11 +4552,19 @@ export class AuthManager {
  * localized `sys_email_template` rows can be selected at all.
  *
  * Maintainer ruling 2026-08-13: the recipient locale is the **deployment
- * default**, read from `II18nService.getDefaultLocale()` and resolved at the
- * plugin layer; `Accept-Language` is rejected (auth mail is frequently sent
- * outside the triggering request — invitations, admin-initiated resets — and
- * a per-device header is the wrong authority for it). AuthPlugin pushes the
- * value on `kernel:ready`, exactly as it pushes {@link setDefaultSmsLocale}.
+ * default**, resolved at the plugin layer; `Accept-Language` is rejected
+ * (auth mail is frequently sent outside the triggering request —
+ * invitations, admin-initiated resets — and a per-device header is the wrong
+ * authority for it). AuthPlugin pushes the value on `kernel:ready`, exactly
+ * as it pushes {@link setDefaultSmsLocale}.
+ *
+ * #14319 — that "deployment default" is the workspace's declared language,
+ * `localization.locale` (ADR-0053), whenever the operator has explicitly set
+ * one; `II18nService.getDefaultLocale()` (the app artifact's build-time
+ * `i18n.defaultLocale`) stands underneath it. Email read only the build-time
+ * half before, so a workspace that switched to Chinese in Setup received
+ * Chinese auth SMS and English auth mail. The precedence lives in
+ * `AuthPlugin`; this setter stays a plain sink.
  *
  * Unset ⇒ nothing is named and `EmailService`'s ladder resolves its
  * documented `en-US` default, i.e. today's behaviour.

packages/plugins/plugin-auth/src/auth-plugin.test.ts

@@ -517,6 +517,169 @@ describe('AuthPlugin', () => {
  });
  });
 
+ /**
+ * #14319 — auth email must speak the workspace's language.
+ *
+ * The reported symptom was a Chinese workspace receiving an English
+ * verification subject. Two halves make that up, and they live apart:
+ *
+ * - the TEMPLATE half — a `zh-CN` row exists for each auth template and
+ * reads naturally — is `plugin-email/src/auth-templates-locales.test.ts`;
+ * - the SEND half — every auth send names the bound locale — is
+ * `auth-email-locale.test.ts`, which drives all five callbacks.
+ *
+ * This block owns the third and previously missing one: which value the
+ * plugin binds. Before #14319 it was `II18nService.getDefaultLocale()`
+ * alone — the app artifact's BUILD-TIME `i18n.defaultLocale`, `en` unless
+ * the app declares otherwise — while auth SMS (#2815) and audit activity
+ * summaries (framework#3039) read the workspace's RUNTIME language,
+ * `localization.locale` (ADR-0053). A workspace switched to Chinese in
+ * Setup therefore got Chinese SMS and English mail from the same plugin,
+ * on the same `kernel:ready` pass, a dozen lines apart.
+ */
+ describe('Auth email locale binding (localization.locale) — #14319', () => {
+ let hookCapture: ReturnType<typeof createHookCapture>;
+ let setEmailLocaleSpy: ReturnType<typeof vi.spyOn>;
+ let setSmsLocaleSpy: ReturnType<typeof vi.spyOn>;
+
+ type Resolved = { value: unknown; source: string };
+
+ /**
+ * A settings double answering per `(namespace, key)`. `branding` resolves
+ * to its manifest default so the sibling brand binding is inert here, and
+ * `subscribe` records handlers so the live-rebind leg can fire one.
+ */
+ const makeSettings = (locale: Resolved | Error) => {
+ const handlers: Array<() => void> = [];
+ let current = locale;
+ return {
+ handlers,
+ set(next: Resolved) {
+ current = next;
+ },
+ get: vi.fn(async (namespace: string, key: string) => {
+ if (namespace === 'branding') return { value: 'ObjectStack', source: 'default' };
+ if (namespace === 'localization' && key === 'locale') {
+ if (current instanceof Error) throw current;
+ return current;
+ }
+ return undefined;
+ }),
+ subscribe: vi.fn((_namespace: string | undefined, handler: () => void) => {
+ handlers.push(handler);
+ return () => {};
+ }),
+ };
+ };
+
+ /**
+ * `i18n` is passed as `null` to mean "no such service" — `getService`
+ * THROWS for an unregistered service, which is the shape the plugin
+ * probes for, not a falsy return.
+ */
+ const boot = async (opts: { settings?: unknown; i18nDefault?: string | null }) => {
+ hookCapture = createHookCapture();
+ mockContext.hook = hookCapture.hookFn;
+ // `: any` on the RETURN, not a cast on the assignment: `getService` is
+ // generic (`<T>(name: string) => T`), so an inferred union return is a
+ // TS2322 — the exact debt `check:test-typecheck` ledgers for the older
+ // doubles in this file. That ledger only ratchets down, so this one
+ // states its shape instead of adding to it.
+ mockContext.getService = vi.fn((name: string): any => {
+ if (name === 'manifest') return { register: vi.fn() };
+ if (name === 'settings') {
+ if (opts.settings === undefined) throw new Error('Service not found: settings');
+ return opts.settings;
+ }
+ if (name === 'i18n') {
+ if (opts.i18nDefault === undefined) throw new Error('Service not found: i18n');
+ return { getDefaultLocale: () => opts.i18nDefault };
+ }
+ return undefined;
+ });
+ setEmailLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultEmailLocale');
+ setSmsLocaleSpy = vi.spyOn(AuthManager.prototype, 'setDefaultSmsLocale');
+ authPlugin = new AuthPlugin({
+ secret: 'test-secret-at-least-32-chars-long',
+ baseUrl: 'http://localhost:3000',
+ });
+ await authPlugin.init(mockContext);
+ await authPlugin.start(mockContext);
+ await hookCapture.trigger('kernel:ready');
+ };
+
+ afterEach(() => {
+ setEmailLocaleSpy?.mockRestore();
+ setSmsLocaleSpy?.mockRestore();
+ });
+
+ it('a zh-CN workspace binds zh-CN on the EMAIL channel, not just on SMS', async () => {
+ const settings = makeSettings({ value: 'zh-CN', source: 'tenant' });
+ await boot({ settings, i18nDefault: 'en' });
+
+ expect(settings.get).toHaveBeenCalledWith('localization', 'locale', {});
+ // The regression, stated as the two channels agreeing. Before #14319 the
+ // SMS assertion passed and the email one read 'en'.
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it.each(['ja-JP', 'es-ES'])('and the same for a %s workspace', async (locale) => {
+ await boot({ settings: makeSettings({ value: locale, source: 'global' }), i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(locale);
+ });
+
+ it('a workspace that never chose a language keeps the app build-time default', async () => {
+ // `get` answers the manifest default ('en-US') for an untouched
+ // workspace, so taking `value` unconditionally would demote every
+ // deployment that declared `i18n.defaultLocale` — the #8195 behaviour
+ // this change must not regress.
+ await boot({
+ settings: makeSettings({ value: 'en-US', source: 'default' }),
+ i18nDefault: 'zh-CN',
+ });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('names NO locale when neither producer speaks — the documented en-US fallback', async () => {
+ // The issue's second acceptance criterion: absent language ⇒ English.
+ // Spelled as an ABSENT locale rather than 'en-US', because that is what
+ // `EmailService`'s ladder contract ("no locale means the DOCUMENTED
+ // default") is written against.
+ await boot({ settings: makeSettings({ value: 'en-US', source: 'default' }) });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith(undefined);
+ });
+
+ it('binds the build-time default when there is no settings service at all', async () => {
+ await boot({ i18nDefault: 'ja-JP' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('ja-JP');
+ });
+
+ it('re-binds live when the workspace switches language', async () => {
+ const settings = makeSettings({ value: 'en-US', source: 'default' });
+ await boot({ settings, i18nDefault: 'en' });
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('en');
+
+ expect(settings.subscribe).toHaveBeenCalledWith('localization', expect.any(Function));
+ settings.set({ value: 'zh-CN', source: 'tenant' });
+ for (const handler of settings.handlers) handler();
+ // The subscribe handler is fire-and-forget (`void`); flush its promise.
+ await new Promise((resolve) => setImmediate(resolve));
+
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(setSmsLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ });
+
+ it('leaves the build-time default standing when the settings read fails', async () => {
+ const settings = makeSettings(new Error('boom'));
+ await expect(boot({ settings, i18nDefault: 'zh-CN' })).resolves.toBeUndefined();
+ expect(setEmailLocaleSpy).toHaveBeenLastCalledWith('zh-CN');
+ expect(mockContext.logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('failed to apply localization.locale'),
+ );
+ });
+ });
+
  describe('Auth settings binding (auth namespace)', () => {
  let hookCapture: ReturnType<typeof createHookCapture>;
  const previousGoogleClientId = process.env.GOOGLE_CLIENT_ID;