From ddc3ba163dac5509c1f5d17bef7929bb8d00ef46 Mon Sep 17 00:00:00 2001
From: swissky <30409887+swissky@users.noreply.github.com>
Date: Sat, 11 Jul 2026 12:10:02 +0200
Subject: [PATCH 1/4] fix(i18n): localize invite, magic-link, and recovery
 emails (#915)

---
 .changeset/localized-system-emails.md         |   7 ++
 .../admin/src/components/InviteAcceptPage.tsx |   2 +-
 packages/admin/src/locales/emails.ts          | 107 ++++++++++++++++++
 packages/admin/src/locales/index.ts           |   2 +
 packages/admin/tests/locales/emails.test.ts   |  50 ++++++++
 packages/auth/src/email-templates.test.ts     |  84 ++++++++++++++
 packages/auth/src/index.ts                    |   4 +
 packages/auth/src/invite.ts                   |  63 +++++++++--
 packages/auth/src/magic-link/index.ts         |  77 +++++++++++--
 packages/core/src/api/email-locale.ts         |  27 +++++
 .../api/admin/users/[id]/send-recovery.ts     |   7 ++
 .../src/astro/routes/api/auth/invite/index.ts |   9 ++
 .../astro/routes/api/auth/magic-link/send.ts  |   7 ++
 13 files changed, 425 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/localized-system-emails.md
 create mode 100644 packages/admin/src/locales/emails.ts
 create mode 100644 packages/admin/tests/locales/emails.test.ts
 create mode 100644 packages/auth/src/email-templates.test.ts
 create mode 100644 packages/core/src/api/email-locale.ts

diff --git a/.changeset/localized-system-emails.md b/.changeset/localized-system-emails.md
new file mode 100644
index 0000000000..f9ef8fe467
--- /dev/null
+++ b/.changeset/localized-system-emails.md
@@ -0,0 +1,7 @@
+---
+"emdash": minor
+"@emdash-cms/admin": minor
+"@emdash-cms/auth": minor
+---
+
+Localizes invite, magic-link, and account-recovery emails: they now follow the site locale (falling back to the requesting user's admin language) instead of always being sent in English.
diff --git a/packages/admin/src/components/InviteAcceptPage.tsx b/packages/admin/src/components/InviteAcceptPage.tsx
index 4ddd13b84d..21ecb1e946 100644
--- a/packages/admin/src/components/InviteAcceptPage.tsx
+++ b/packages/admin/src/components/InviteAcceptPage.tsx
@@ -65,7 +65,7 @@ function RegisterStep({ inviteData, token }: RegisterStepProps) {
 				type="text"
 				value={name}
 				onChange={(e) => setName(e.target.value)}
-				placeholder="Jane Doe"
+				placeholder={t`Jane Doe`}
 				autoComplete="name"
 				autoFocus
 			/>
diff --git a/packages/admin/src/locales/emails.ts b/packages/admin/src/locales/emails.ts
new file mode 100644
index 0000000000..4ffd47cd84
--- /dev/null
+++ b/packages/admin/src/locales/emails.ts
@@ -0,0 +1,107 @@
+/**
+ * Localized copy for system emails (invite, magic link / recovery).
+ *
+ * The email builders live in `@emdash-cms/auth`, which has no i18n
+ * machinery — they take final display strings and fall back to English
+ * (#915). This module resolves those strings from the admin's Lingui
+ * catalogs so the emails follow the site locale like the rest of the
+ * admin. It is server-side only (called from EmDash core API routes).
+ *
+ * The return shapes mirror `InviteEmailStrings` / `MagicLinkEmailStrings`
+ * in `@emdash-cms/auth` structurally; the types are duplicated here so
+ * the admin package doesn't need a dependency on the auth package.
+ */
+
+import { setupI18n, type I18n, type MessageDescriptor } from "@lingui/core";
+import { msg } from "@lingui/core/macro";
+
+import { loadMessages } from "./loadMessages.js";
+
+/** Mirrors `InviteEmailStrings` in `@emdash-cms/auth`. */
+export interface InviteEmailStrings {
+	subject: string;
+	textIntro: string;
+	textLinkInstruction: string;
+	htmlInstruction: string;
+	buttonLabel: string;
+	expiryNote: string;
+}
+
+/** Mirrors `MagicLinkEmailStrings` in `@emdash-cms/auth`. */
+export interface MagicLinkEmailStrings {
+	subject: string;
+	textLinkInstruction: string;
+	htmlInstruction: string;
+	buttonLabel: string;
+	expiryNote: string;
+	ignoreNote: string;
+}
+
+// Module-scope descriptors (msg) so Lingui extraction picks them up;
+// resolved per call with the requested locale's catalog. The {siteName}
+// placeholder is ICU MessageFormat, interpolated at resolve time.
+const INVITE: Record<keyof InviteEmailStrings, MessageDescriptor> = {
+	subject: msg({ message: "You've been invited to {siteName}" }),
+	textIntro: msg({ message: "You've been invited to join {siteName}." }),
+	textLinkInstruction: msg({ message: "Click this link to create your account:" }),
+	htmlInstruction: msg({ message: "Click the button below to create your account:" }),
+	buttonLabel: msg({ message: "Accept Invite" }),
+	expiryNote: msg({ message: "This link expires in 7 days." }),
+};
+
+const MAGIC_LINK: Record<keyof MagicLinkEmailStrings, MessageDescriptor> = {
+	subject: msg({ message: "Sign in to {siteName}" }),
+	textLinkInstruction: msg({ message: "Click this link to sign in to {siteName}:" }),
+	htmlInstruction: msg({ message: "Click the button below to sign in:" }),
+	buttonLabel: msg({ message: "Sign in" }),
+	expiryNote: msg({ message: "This link expires in 15 minutes." }),
+	ignoreNote: msg({ message: "If you didn't request this, you can safely ignore this email." }),
+};
+
+/**
+ * Build a standalone i18n instance for one resolution. Deliberately not
+ * the shared `i18n` singleton — these calls run server-side and must not
+ * race with (or reactivate) the admin SPA's active locale.
+ */
+async function i18nFor(locale: string): Promise<I18n> {
+	// loadMessages falls back to the default (English) catalog for
+	// unknown locales, so an unconfigured/garbage locale yields English.
+	const messages = await loadMessages(locale);
+	return setupI18n({ locale, messages: { [locale]: messages } });
+}
+
+function resolver(i18n: I18n, siteName: string) {
+	return (descriptor: MessageDescriptor): string => i18n._({ ...descriptor, values: { siteName } });
+}
+
+/** Localized copy for the invite email, in the given locale. */
+export async function getInviteEmailStrings(
+	locale: string,
+	siteName: string,
+): Promise<InviteEmailStrings> {
+	const resolve = resolver(await i18nFor(locale), siteName);
+	return {
+		subject: resolve(INVITE.subject),
+		textIntro: resolve(INVITE.textIntro),
+		textLinkInstruction: resolve(INVITE.textLinkInstruction),
+		htmlInstruction: resolve(INVITE.htmlInstruction),
+		buttonLabel: resolve(INVITE.buttonLabel),
+		expiryNote: resolve(INVITE.expiryNote),
+	};
+}
+
+/** Localized copy for the sign-in (magic link / recovery) email. */
+export async function getMagicLinkEmailStrings(
+	locale: string,
+	siteName: string,
+): Promise<MagicLinkEmailStrings> {
+	const resolve = resolver(await i18nFor(locale), siteName);
+	return {
+		subject: resolve(MAGIC_LINK.subject),
+		textLinkInstruction: resolve(MAGIC_LINK.textLinkInstruction),
+		htmlInstruction: resolve(MAGIC_LINK.htmlInstruction),
+		buttonLabel: resolve(MAGIC_LINK.buttonLabel),
+		expiryNote: resolve(MAGIC_LINK.expiryNote),
+		ignoreNote: resolve(MAGIC_LINK.ignoreNote),
+	};
+}
diff --git a/packages/admin/src/locales/index.ts b/packages/admin/src/locales/index.ts
index 4e0b6a7273..6b3fd78d95 100644
--- a/packages/admin/src/locales/index.ts
+++ b/packages/admin/src/locales/index.ts
@@ -1,6 +1,8 @@
 export { useLocale } from "./useLocale.js";
 export { LocaleDirectionProvider } from "./LocaleDirectionProvider.js";
 export { loadMessages } from "./loadMessages.js";
+export { getInviteEmailStrings, getMagicLinkEmailStrings } from "./emails.js";
+export type { InviteEmailStrings, MagicLinkEmailStrings } from "./emails.js";
 export {
 	SUPPORTED_LOCALES,
 	SUPPORTED_LOCALE_CODES,
diff --git a/packages/admin/tests/locales/emails.test.ts b/packages/admin/tests/locales/emails.test.ts
new file mode 100644
index 0000000000..f7c0313812
--- /dev/null
+++ b/packages/admin/tests/locales/emails.test.ts
@@ -0,0 +1,50 @@
+/**
+ * System email copy resolution tests (#915): the helpers resolve the
+ * module-scope descriptors through the Lingui catalog for the requested
+ * locale, interpolate the site name, and fall back to English for
+ * unknown locales. (Whether individual strings are translated depends
+ * on catalog coverage, so assertions stick to the English source and
+ * the fallback path.)
+ */
+
+import { describe, expect, test } from "vitest";
+
+import { getInviteEmailStrings, getMagicLinkEmailStrings } from "../../src/locales/emails.js";
+
+describe("getInviteEmailStrings", () => {
+	test("resolves English copy with the site name interpolated", async () => {
+		const strings = await getInviteEmailStrings("en", "Acme");
+
+		expect(strings.subject).toBe("You've been invited to Acme");
+		expect(strings.textIntro).toBe("You've been invited to join Acme.");
+		expect(strings.buttonLabel).toBe("Accept Invite");
+		expect(strings.expiryNote).toBe("This link expires in 7 days.");
+	});
+
+	test("falls back to English for an unknown locale", async () => {
+		const strings = await getInviteEmailStrings("xx-XX", "Acme");
+
+		expect(strings.subject).toBe("You've been invited to Acme");
+	});
+
+	test("resolves every field to a non-empty string for all enabled locales", async () => {
+		for (const locale of ["de", "ja", "ar", "pt-BR"]) {
+			const strings = await getInviteEmailStrings(locale, "Acme");
+			for (const value of Object.values(strings)) {
+				expect(value).toBeTruthy();
+			}
+		}
+	});
+});
+
+describe("getMagicLinkEmailStrings", () => {
+	test("resolves English copy with the site name interpolated", async () => {
+		const strings = await getMagicLinkEmailStrings("en", "Acme");
+
+		expect(strings.subject).toBe("Sign in to Acme");
+		expect(strings.textLinkInstruction).toBe("Click this link to sign in to Acme:");
+		expect(strings.ignoreNote).toBe(
+			"If you didn't request this, you can safely ignore this email.",
+		);
+	});
+});
diff --git a/packages/auth/src/email-templates.test.ts b/packages/auth/src/email-templates.test.ts
new file mode 100644
index 0000000000..edd950363b
--- /dev/null
+++ b/packages/auth/src/email-templates.test.ts
@@ -0,0 +1,84 @@
+/**
+ * System email builder tests (#915): the builders default to English
+ * and render injected localized copy verbatim (text) / escaped (HTML).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { buildInviteEmail, type InviteEmailStrings } from "./invite.js";
+import { buildMagicLinkEmail, type MagicLinkEmailStrings } from "./magic-link/index.js";
+
+const URL = "https://example.com/_emdash/admin/invite/accept?token=abc";
+
+describe("buildInviteEmail", () => {
+	it("defaults to English copy with the site name interpolated", () => {
+		const message = buildInviteEmail(URL, "new@example.com", "Acme");
+
+		expect(message.to).toBe("new@example.com");
+		expect(message.subject).toBe("You've been invited to Acme");
+		expect(message.text).toContain("You've been invited to join Acme.");
+		expect(message.text).toContain(URL);
+		expect(message.html).toContain("Accept Invite");
+	});
+
+	it("renders injected localized copy", () => {
+		const strings: InviteEmailStrings = {
+			subject: "Du wurdest zu Acme eingeladen",
+			textIntro: "Du wurdest eingeladen, Acme beizutreten.",
+			textLinkInstruction: "Klicke auf diesen Link, um dein Konto zu erstellen:",
+			htmlInstruction: "Klicke auf den Button unten, um dein Konto zu erstellen:",
+			buttonLabel: "Einladung annehmen",
+			expiryNote: "Dieser Link läuft in 7 Tagen ab.",
+		};
+
+		const message = buildInviteEmail(URL, "new@example.com", "Acme", strings);
+
+		expect(message.subject).toBe("Du wurdest zu Acme eingeladen");
+		expect(message.text).toContain("Du wurdest eingeladen, Acme beizutreten.");
+		expect(message.text).toContain(URL);
+		expect(message.html).toContain("Einladung annehmen");
+		expect(message.html).not.toContain("Accept Invite");
+	});
+
+	it("HTML-escapes localized strings (site names and translations are untrusted)", () => {
+		const message = buildInviteEmail(URL, "new@example.com", `<b>"Acme"</b>`);
+
+		expect(message.html).toContain("&lt;b&gt;&quot;Acme&quot;&lt;/b&gt;");
+		expect(message.html).not.toContain(`<b>"Acme"</b>`);
+	});
+});
+
+describe("buildMagicLinkEmail", () => {
+	it("defaults to English copy with the site name interpolated", () => {
+		const message = buildMagicLinkEmail(URL, "user@example.com", "Acme");
+
+		expect(message.subject).toBe("Sign in to Acme");
+		expect(message.text).toContain("Click this link to sign in to Acme:");
+		expect(message.text).toContain(URL);
+		expect(message.html).toContain("Sign in");
+	});
+
+	it("renders injected localized copy", () => {
+		const strings: MagicLinkEmailStrings = {
+			subject: "Bei Acme anmelden",
+			textLinkInstruction: "Klicke auf diesen Link, um dich bei Acme anzumelden:",
+			htmlInstruction: "Klicke auf den Button unten, um dich anzumelden:",
+			buttonLabel: "Anmelden",
+			expiryNote: "Dieser Link läuft in 15 Minuten ab.",
+			ignoreNote: "Wenn du das nicht angefordert hast, kannst du diese E-Mail ignorieren.",
+		};
+
+		const message = buildMagicLinkEmail(URL, "user@example.com", "Acme", strings);
+
+		expect(message.subject).toBe("Bei Acme anmelden");
+		expect(message.text).toContain(URL);
+		expect(message.html).toContain("Anmelden");
+		expect(message.html).not.toContain("Sign in to Acme");
+	});
+
+	it("HTML-escapes localized strings", () => {
+		const message = buildMagicLinkEmail(URL, "user@example.com", `<script>Acme</script>`);
+
+		expect(message.html).not.toContain("<script>");
+	});
+});
diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts
index 58cb856ac9..a3b6c2ae61 100644
--- a/packages/auth/src/index.ts
+++ b/packages/auth/src/index.ts
@@ -79,7 +79,9 @@ export {
 	sendMagicLink,
 	verifyMagicLink,
 	MagicLinkError,
+	buildMagicLinkEmail,
 	type MagicLinkConfig,
+	type MagicLinkEmailStrings,
 } from "./magic-link/index.js";
 
 // Invite
@@ -88,10 +90,12 @@ export {
 	createInviteToken,
 	validateInvite,
 	completeInvite,
+	buildInviteEmail,
 	InviteError,
 	escapeHtml,
 	type InviteConfig,
 	type InviteTokenResult,
+	type InviteEmailStrings,
 	type EmailSendFn,
 } from "./invite.js";
 
diff --git a/packages/auth/src/invite.ts b/packages/auth/src/invite.ts
index a887b76569..b6b77410a6 100644
--- a/packages/auth/src/invite.ts
+++ b/packages/auth/src/invite.ts
@@ -19,11 +19,36 @@ const TOKEN_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 /** Function that sends an email (matches the EmailPipeline.send signature) */
 export type EmailSendFn = (message: EmailMessage) => Promise<void>;
 
+/**
+ * Localized copy for the invite email (#915).
+ *
+ * All fields are final display strings — interpolation (site name) happens
+ * in the caller, which owns the locale catalogs. When omitted, the builder
+ * falls back to English. This package deliberately stays free of any i18n
+ * machinery; EmDash core passes strings resolved from the admin catalogs.
+ */
+export interface InviteEmailStrings {
+	/** Subject line, e.g. `You've been invited to Acme` */
+	subject: string;
+	/** First line of the plain-text body, e.g. `You've been invited to join Acme.` */
+	textIntro: string;
+	/** Plain-text instruction above the raw link */
+	textLinkInstruction: string;
+	/** HTML instruction above the button */
+	htmlInstruction: string;
+	/** Button label */
+	buttonLabel: string;
+	/** Expiry note, e.g. `This link expires in 7 days.` */
+	expiryNote: string;
+}
+
 export interface InviteConfig {
 	baseUrl: string;
 	siteName: string;
 	/** Optional email sender. When omitted, invite URL is returned without sending. */
 	email?: EmailSendFn;
+	/** Optional localized email copy. English when omitted. */
+	emailStrings?: InviteEmailStrings;
 }
 
 /** Result of creating an invite token (without sending email) */
@@ -74,15 +99,35 @@ export async function createInviteToken(
 	return { url: url.toString(), email };
 }
 
+/** English fallback copy for the invite email. */
+function defaultInviteEmailStrings(siteName: string): InviteEmailStrings {
+	return {
+		subject: `You've been invited to ${siteName}`,
+		textIntro: `You've been invited to join ${siteName}.`,
+		textLinkInstruction: "Click this link to create your account:",
+		htmlInstruction: "Click the button below to create your account:",
+		buttonLabel: "Accept Invite",
+		expiryNote: "This link expires in 7 days.",
+	};
+}
+
 /**
  * Build the invite email message.
+ *
+ * Exported for tests and for callers that render the message without
+ * sending (localized copy is injected via `strings`, see #915).
  */
-function buildInviteEmail(inviteUrl: string, email: string, siteName: string): EmailMessage {
-	const safeName = escapeHtml(siteName);
+export function buildInviteEmail(
+	inviteUrl: string,
+	email: string,
+	siteName: string,
+	strings?: InviteEmailStrings,
+): EmailMessage {
+	const s = strings ?? defaultInviteEmailStrings(siteName);
 	return {
 		to: email,
-		subject: `You've been invited to ${siteName}`,
-		text: `You've been invited to join ${siteName}.\n\nClick this link to create your account:\n${inviteUrl}\n\nThis link expires in 7 days.`,
+		subject: s.subject,
+		text: `${s.textIntro}\n\n${s.textLinkInstruction}\n${inviteUrl}\n\n${s.expiryNote}`,
 		html: `
 <!DOCTYPE html>
 <html>
@@ -91,12 +136,12 @@ function buildInviteEmail(inviteUrl: string, email: string, siteName: string): E
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 </head>
 <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.5; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
-  <h1 style="font-size: 24px; margin-bottom: 20px;">You've been invited to ${safeName}</h1>
-  <p>Click the button below to create your account:</p>
+  <h1 style="font-size: 24px; margin-bottom: 20px;">${escapeHtml(s.subject)}</h1>
+  <p>${escapeHtml(s.htmlInstruction)}</p>
   <p style="margin: 30px 0;">
-    <a href="${inviteUrl}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">Accept Invite</a>
+    <a href="${inviteUrl}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">${escapeHtml(s.buttonLabel)}</a>
   </p>
-  <p style="color: #666; font-size: 14px;">This link expires in 7 days.</p>
+  <p style="color: #666; font-size: 14px;">${escapeHtml(s.expiryNote)}</p>
 </body>
 </html>`,
 	};
@@ -120,7 +165,7 @@ export async function createInvite(
 
 	// Send email if a sender is configured
 	if (config.email) {
-		const message = buildInviteEmail(result.url, email, config.siteName);
+		const message = buildInviteEmail(result.url, email, config.siteName, config.emailStrings);
 		await config.email(message);
 	}
 
diff --git a/packages/auth/src/magic-link/index.ts b/packages/auth/src/magic-link/index.ts
index f618ad7a9d..610bc9ae3a 100644
--- a/packages/auth/src/magic-link/index.ts
+++ b/packages/auth/src/magic-link/index.ts
@@ -11,11 +11,34 @@ const TOKEN_EXPIRY_MS = 15 * 60 * 1000; // 15 minutes
 /** Function that sends an email (matches the EmailPipeline.send signature) */
 export type EmailSendFn = (message: EmailMessage) => Promise<void>;
 
+/**
+ * Localized copy for the sign-in (magic link / recovery) email (#915).
+ *
+ * Final display strings, interpolated by the caller — same contract as
+ * `InviteEmailStrings` in invite.ts. English fallback when omitted.
+ */
+export interface MagicLinkEmailStrings {
+	/** Subject line, e.g. `Sign in to Acme` */
+	subject: string;
+	/** Plain-text instruction above the raw link, e.g. `Click this link to sign in to Acme:` */
+	textLinkInstruction: string;
+	/** HTML instruction above the button */
+	htmlInstruction: string;
+	/** Button label */
+	buttonLabel: string;
+	/** Expiry note, e.g. `This link expires in 15 minutes.` */
+	expiryNote: string;
+	/** Unsolicited-email note, e.g. `If you didn't request this, you can safely ignore this email.` */
+	ignoreNote: string;
+}
+
 export interface MagicLinkConfig {
 	baseUrl: string;
 	siteName: string;
 	/** Optional email sender. When omitted, magic links cannot be sent. */
 	email?: EmailSendFn;
+	/** Optional localized email copy. English when omitted. */
+	emailStrings?: MagicLinkEmailStrings;
 }
 
 /**
@@ -67,11 +90,43 @@ export async function sendMagicLink(
 	url.searchParams.set("token", token);
 
 	// Send email
-	const safeName = escapeHtml(config.siteName);
-	await config.email({
-		to: user.email,
-		subject: `Sign in to ${config.siteName}`,
-		text: `Click this link to sign in to ${config.siteName}:\n\n${url.toString()}\n\nThis link expires in 15 minutes.\n\nIf you didn't request this, you can safely ignore this email.`,
+	const message = buildMagicLinkEmail(
+		url.toString(),
+		user.email,
+		config.siteName,
+		config.emailStrings,
+	);
+	await config.email(message);
+}
+
+/** English fallback copy for the sign-in email. */
+function defaultMagicLinkEmailStrings(siteName: string): MagicLinkEmailStrings {
+	return {
+		subject: `Sign in to ${siteName}`,
+		textLinkInstruction: `Click this link to sign in to ${siteName}:`,
+		htmlInstruction: "Click the button below to sign in:",
+		buttonLabel: "Sign in",
+		expiryNote: "This link expires in 15 minutes.",
+		ignoreNote: "If you didn't request this, you can safely ignore this email.",
+	};
+}
+
+/**
+ * Build the sign-in (magic link / recovery) email message.
+ *
+ * Exported for tests; localized copy is injected via `strings` (#915).
+ */
+export function buildMagicLinkEmail(
+	linkUrl: string,
+	email: string,
+	siteName: string,
+	strings?: MagicLinkEmailStrings,
+): EmailMessage {
+	const s = strings ?? defaultMagicLinkEmailStrings(siteName);
+	return {
+		to: email,
+		subject: s.subject,
+		text: `${s.textLinkInstruction}\n\n${linkUrl}\n\n${s.expiryNote}\n\n${s.ignoreNote}`,
 		html: `
 <!DOCTYPE html>
 <html>
@@ -80,16 +135,16 @@ export async function sendMagicLink(
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 </head>
 <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.5; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
-  <h1 style="font-size: 24px; margin-bottom: 20px;">Sign in to ${safeName}</h1>
-  <p>Click the button below to sign in:</p>
+  <h1 style="font-size: 24px; margin-bottom: 20px;">${escapeHtml(s.subject)}</h1>
+  <p>${escapeHtml(s.htmlInstruction)}</p>
   <p style="margin: 30px 0;">
-    <a href="${url.toString()}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">Sign in</a>
+    <a href="${linkUrl}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">${escapeHtml(s.buttonLabel)}</a>
   </p>
-  <p style="color: #666; font-size: 14px;">This link expires in 15 minutes.</p>
-  <p style="color: #666; font-size: 14px;">If you didn't request this, you can safely ignore this email.</p>
+  <p style="color: #666; font-size: 14px;">${escapeHtml(s.expiryNote)}</p>
+  <p style="color: #666; font-size: 14px;">${escapeHtml(s.ignoreNote)}</p>
 </body>
 </html>`,
-	});
+	};
 }
 
 /**
diff --git a/packages/core/src/api/email-locale.ts b/packages/core/src/api/email-locale.ts
new file mode 100644
index 0000000000..885bd53cd4
--- /dev/null
+++ b/packages/core/src/api/email-locale.ts
@@ -0,0 +1,27 @@
+/**
+ * Resolve the locale for outbound system emails (invite, magic link,
+ * recovery), and load the matching localized copy from the admin
+ * catalogs (#915).
+ *
+ * Priority: the site-wide `emdash:locale` option (explicit site
+ * language) -> the requesting user's admin locale (cookie /
+ * Accept-Language, i.e. the language the inviter works in) -> English.
+ * The recipient's language is unknowable server-side, so the site's
+ * language is the best available signal — same trade-off WordPress
+ * makes for its system mails.
+ */
+
+import { resolveLocale } from "@emdash-cms/admin/locales";
+import type { Kysely } from "kysely";
+
+import { OptionsRepository } from "../database/repositories/options.js";
+import type { Database } from "../database/types.js";
+
+export async function getEmailLocale(db: Kysely<Database>, request: Request): Promise<string> {
+	const options = new OptionsRepository(db);
+	const siteLocale = await options.get<string>("emdash:locale");
+	// loadMessages falls back to English for unsupported codes, so a
+	// free-form option value degrades safely.
+	if (typeof siteLocale === "string" && siteLocale) return siteLocale;
+	return resolveLocale(request);
+}
diff --git a/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts b/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts
index 61bee6ffe9..d1441f5fa3 100644
--- a/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts
+++ b/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts
@@ -6,10 +6,12 @@
  * Admin-initiated account recovery — sends a recovery magic link to the user's email.
  */
 
+import { getMagicLinkEmailStrings } from "@emdash-cms/admin/locales";
 import { Role, sendMagicLink, type MagicLinkConfig } from "@emdash-cms/auth";
 import { createKyselyAdapter } from "@emdash-cms/auth/adapters/kysely";
 import type { APIRoute } from "astro";
 
+import { getEmailLocale } from "#api/email-locale.js";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
 import { getSiteBaseUrl } from "#api/site-url.js";
 import { OptionsRepository } from "#db/repositories/options.js";
@@ -60,6 +62,11 @@ export const POST: APIRoute = async ({ request, params, locals }) => {
 			baseUrl,
 			siteName,
 			email: (message) => emdash.email!.send(message, "system"),
+			// Localized copy following the site locale (#915)
+			emailStrings: await getMagicLinkEmailStrings(
+				await getEmailLocale(emdash.db, request),
+				siteName,
+			),
 		};
 
 		// Send recovery link
diff --git a/packages/core/src/astro/routes/api/auth/invite/index.ts b/packages/core/src/astro/routes/api/auth/invite/index.ts
index 3547a79a44..3085f1d5ce 100644
--- a/packages/core/src/astro/routes/api/auth/invite/index.ts
+++ b/packages/core/src/astro/routes/api/auth/invite/index.ts
@@ -13,9 +13,11 @@ import type { APIRoute } from "astro";
 
 export const prerender = false;
 
+import { getInviteEmailStrings } from "@emdash-cms/admin/locales";
 import { createInvite, InviteError, Role } from "@emdash-cms/auth";
 import { createKyselyAdapter } from "@emdash-cms/auth/adapters/kysely";
 
+import { getEmailLocale } from "#api/email-locale.js";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
 import { isParseError, parseBody } from "#api/parse.js";
 import { inviteCreateBody } from "#api/schemas.js";
@@ -55,11 +57,18 @@ export const POST: APIRoute = async ({ request, locals }) => {
 					emdash.email!.send(message, "system")
 			: undefined;
 
+		// Localize the invite email copy (#915). Only resolved when an
+		// email will actually be sent — the copy-link fallback has no copy.
+		const emailStrings = emailSend
+			? await getInviteEmailStrings(await getEmailLocale(emdash.db, request), siteName)
+			: undefined;
+
 		const result = await createInvite(
 			{
 				baseUrl,
 				siteName,
 				email: emailSend,
+				emailStrings,
 			},
 			adapter,
 			body.email,
diff --git a/packages/core/src/astro/routes/api/auth/magic-link/send.ts b/packages/core/src/astro/routes/api/auth/magic-link/send.ts
index e80da04177..3808ce9f5c 100644
--- a/packages/core/src/astro/routes/api/auth/magic-link/send.ts
+++ b/packages/core/src/astro/routes/api/auth/magic-link/send.ts
@@ -11,9 +11,11 @@ import type { APIRoute } from "astro";
 
 export const prerender = false;
 
+import { getMagicLinkEmailStrings } from "@emdash-cms/admin/locales";
 import { sendMagicLink, type MagicLinkConfig } from "@emdash-cms/auth";
 import { createKyselyAdapter } from "@emdash-cms/auth/adapters/kysely";
 
+import { getEmailLocale } from "#api/email-locale.js";
 import { apiError, apiSuccess } from "#api/error.js";
 import { isParseError, parseBody } from "#api/parse.js";
 import { magicLinkSendBody } from "#api/schemas.js";
@@ -66,6 +68,11 @@ export const POST: APIRoute = async ({ request, locals }) => {
 			baseUrl,
 			siteName,
 			email: (message) => emdash.email!.send(message, "system"),
+			// Localized copy following the site locale (#915)
+			emailStrings: await getMagicLinkEmailStrings(
+				await getEmailLocale(emdash.db, request),
+				siteName,
+			),
 		};
 
 		// Send magic link (silently fails if user doesn't exist)

From 8f009d612056e88cfa3106407dcafab95c8e2f3d Mon Sep 17 00:00:00 2001
From: swissky <30409887+swissky@users.noreply.github.com>
Date: Sat, 11 Jul 2026 17:10:14 +0200
Subject: [PATCH 2/4] test: cover getEmailLocale priority chain

Review follow-up: unit-tests the site-locale -> cookie ->
Accept-Language -> English fallback against a real test database.
---
 .../core/tests/unit/api/email-locale.test.ts  | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 packages/core/tests/unit/api/email-locale.test.ts

diff --git a/packages/core/tests/unit/api/email-locale.test.ts b/packages/core/tests/unit/api/email-locale.test.ts
new file mode 100644
index 0000000000..c027ab16bf
--- /dev/null
+++ b/packages/core/tests/unit/api/email-locale.test.ts
@@ -0,0 +1,71 @@
+/**
+ * getEmailLocale: locale priority for outbound system emails (#915).
+ *
+ * Priority: site-wide `emdash:locale` option -> requester's admin
+ * locale (emdash-locale cookie, then Accept-Language) -> English.
+ */
+
+import type { Kysely } from "kysely";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { getEmailLocale } from "../../../src/api/email-locale.js";
+import { OptionsRepository } from "../../../src/database/repositories/options.js";
+import type { Database } from "../../../src/database/types.js";
+import { setupTestDatabase, teardownTestDatabase } from "../../utils/test-db.js";
+
+function request(headers: Record<string, string> = {}): Request {
+	return new Request("http://test.local/_emdash/api/auth/invite", { headers });
+}
+
+describe("getEmailLocale (#915)", () => {
+	let db: Kysely<Database>;
+
+	beforeEach(async () => {
+		db = await setupTestDatabase();
+	});
+
+	afterEach(async () => {
+		await teardownTestDatabase(db);
+	});
+
+	it("prefers the site-wide emdash:locale option over request headers", async () => {
+		await new OptionsRepository(db).set("emdash:locale", "de");
+
+		const locale = await getEmailLocale(
+			db,
+			request({ cookie: "emdash-locale=fr", "accept-language": "es" }),
+		);
+
+		expect(locale).toBe("de");
+	});
+
+	it("falls back to the requester's cookie locale when no site locale is set", async () => {
+		const locale = await getEmailLocale(
+			db,
+			request({ cookie: "emdash-locale=fr", "accept-language": "es" }),
+		);
+
+		expect(locale).toBe("fr");
+	});
+
+	it("falls back to Accept-Language when neither site locale nor cookie exist", async () => {
+		const locale = await getEmailLocale(db, request({ "accept-language": "es-ES,es;q=0.9" }));
+
+		expect(locale).toBe("es-ES");
+	});
+
+	it("defaults to English with no signals at all", async () => {
+		const locale = await getEmailLocale(db, request());
+
+		expect(locale).toBe("en");
+	});
+
+	it("ignores an unsupported cookie locale and keeps resolving", async () => {
+		const locale = await getEmailLocale(
+			db,
+			request({ cookie: "emdash-locale=xx", "accept-language": "ja" }),
+		);
+
+		expect(locale).toBe("ja");
+	});
+});

From fe4a774371ec7ddbfb3b1d8a4c58780bddb99df0 Mon Sep 17 00:00:00 2001
From: swissky <30409887+swissky@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:09:57 +0200
Subject: [PATCH 3/4] fix(auth): set lang/dir on localized system emails for
 RTL

Localized invite/magic-link/recovery copy may be RTL (Arabic, Farsi,
etc.), but the email HTML root had no lang/dir, so RTL text rendered
LTR. Thread the resolved locale through to the builders and set
lang + dir on the <html> element (localeDir derived from the BCP 47
primary subtag, keeping @emdash-cms/auth free of the admin dep).
---
 packages/auth/src/email-templates.test.ts     | 29 ++++++++++++++++++-
 packages/auth/src/invite.ts                   | 28 ++++++++++++++++--
 packages/auth/src/magic-link/index.ts         | 11 +++++--
 .../api/admin/users/[id]/send-recovery.ts     | 10 +++----
 .../src/astro/routes/api/auth/invite/index.ts |  6 ++--
 .../astro/routes/api/auth/magic-link/send.ts  | 10 +++----
 6 files changed, 77 insertions(+), 17 deletions(-)

diff --git a/packages/auth/src/email-templates.test.ts b/packages/auth/src/email-templates.test.ts
index edd950363b..4b1953d982 100644
--- a/packages/auth/src/email-templates.test.ts
+++ b/packages/auth/src/email-templates.test.ts
@@ -5,11 +5,25 @@
 
 import { describe, expect, it } from "vitest";
 
-import { buildInviteEmail, type InviteEmailStrings } from "./invite.js";
+import { buildInviteEmail, localeDir, type InviteEmailStrings } from "./invite.js";
 import { buildMagicLinkEmail, type MagicLinkEmailStrings } from "./magic-link/index.js";
 
 const URL = "https://example.com/_emdash/admin/invite/accept?token=abc";
 
+describe("localeDir", () => {
+	it("flags RTL primary subtags as rtl", () => {
+		expect(localeDir("ar")).toBe("rtl");
+		expect(localeDir("fa-IR")).toBe("rtl");
+		expect(localeDir("he")).toBe("rtl");
+	});
+
+	it("treats LTR and empty locales as ltr", () => {
+		expect(localeDir("en")).toBe("ltr");
+		expect(localeDir("de-CH")).toBe("ltr");
+		expect(localeDir("")).toBe("ltr");
+	});
+});
+
 describe("buildInviteEmail", () => {
 	it("defaults to English copy with the site name interpolated", () => {
 		const message = buildInviteEmail(URL, "new@example.com", "Acme");
@@ -46,6 +60,19 @@ describe("buildInviteEmail", () => {
 		expect(message.html).toContain("&lt;b&gt;&quot;Acme&quot;&lt;/b&gt;");
 		expect(message.html).not.toContain(`<b>"Acme"</b>`);
 	});
+
+	it("sets lang/dir on the root element when a locale is provided (RTL)", () => {
+		const message = buildInviteEmail(URL, "new@example.com", "Acme", undefined, "ar");
+
+		expect(message.html).toContain('<html lang="ar" dir="rtl">');
+	});
+
+	it("omits lang/dir when no locale is provided (defaults to ltr)", () => {
+		const message = buildInviteEmail(URL, "new@example.com", "Acme");
+
+		expect(message.html).toContain("<html>");
+		expect(message.html).not.toContain("dir=");
+	});
 });
 
 describe("buildMagicLinkEmail", () => {
diff --git a/packages/auth/src/invite.ts b/packages/auth/src/invite.ts
index b6b77410a6..4535fc2791 100644
--- a/packages/auth/src/invite.ts
+++ b/packages/auth/src/invite.ts
@@ -14,6 +14,18 @@ export function escapeHtml(s: string): string {
 		.replaceAll('"', "&quot;");
 }
 
+/**
+ * RTL primary language subtags (BCP 47). Mirrors the admin's
+ * `getLocaleDir` without @emdash-cms/auth depending on the admin package.
+ */
+const RTL_SUBTAGS = new Set(["ar", "fa", "he", "ur", "ps", "sd", "ug", "yi", "ckb", "dv"]);
+
+/** Text direction for a BCP 47 locale code ("ltr" unless the primary subtag is RTL). */
+export function localeDir(locale: string): "ltr" | "rtl" {
+	const primary = locale.toLowerCase().split(/[-_]/)[0] ?? "";
+	return RTL_SUBTAGS.has(primary) ? "rtl" : "ltr";
+}
+
 const TOKEN_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 /** Function that sends an email (matches the EmailPipeline.send signature) */
@@ -49,6 +61,8 @@ export interface InviteConfig {
 	email?: EmailSendFn;
 	/** Optional localized email copy. English when omitted. */
 	emailStrings?: InviteEmailStrings;
+	/** Optional BCP 47 locale of the copy; sets lang/dir on the email HTML for RTL. */
+	emailLocale?: string;
 }
 
 /** Result of creating an invite token (without sending email) */
@@ -122,15 +136,19 @@ export function buildInviteEmail(
 	email: string,
 	siteName: string,
 	strings?: InviteEmailStrings,
+	locale?: string,
 ): EmailMessage {
 	const s = strings ?? defaultInviteEmailStrings(siteName);
+	// Localized copy may be RTL — set lang/dir on the root so RTL text renders
+	// correctly. Defaults to ltr when no locale is threaded through (#915).
+	const langAttr = locale ? ` lang="${escapeHtml(locale)}" dir="${localeDir(locale)}"` : "";
 	return {
 		to: email,
 		subject: s.subject,
 		text: `${s.textIntro}\n\n${s.textLinkInstruction}\n${inviteUrl}\n\n${s.expiryNote}`,
 		html: `
 <!DOCTYPE html>
-<html>
+<html${langAttr}>
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -165,7 +183,13 @@ export async function createInvite(
 
 	// Send email if a sender is configured
 	if (config.email) {
-		const message = buildInviteEmail(result.url, email, config.siteName, config.emailStrings);
+		const message = buildInviteEmail(
+			result.url,
+			email,
+			config.siteName,
+			config.emailStrings,
+			config.emailLocale,
+		);
 		await config.email(message);
 	}
 
diff --git a/packages/auth/src/magic-link/index.ts b/packages/auth/src/magic-link/index.ts
index 610bc9ae3a..c4a93f07a5 100644
--- a/packages/auth/src/magic-link/index.ts
+++ b/packages/auth/src/magic-link/index.ts
@@ -2,7 +2,7 @@
  * Magic link authentication
  */
 
-import { escapeHtml } from "../invite.js";
+import { escapeHtml, localeDir } from "../invite.js";
 import { generateTokenWithHash, hashToken } from "../tokens.js";
 import type { AuthAdapter, User, EmailMessage } from "../types.js";
 
@@ -39,6 +39,8 @@ export interface MagicLinkConfig {
 	email?: EmailSendFn;
 	/** Optional localized email copy. English when omitted. */
 	emailStrings?: MagicLinkEmailStrings;
+	/** Optional BCP 47 locale of the copy; sets lang/dir on the email HTML for RTL. */
+	emailLocale?: string;
 }
 
 /**
@@ -95,6 +97,7 @@ export async function sendMagicLink(
 		user.email,
 		config.siteName,
 		config.emailStrings,
+		config.emailLocale,
 	);
 	await config.email(message);
 }
@@ -121,15 +124,19 @@ export function buildMagicLinkEmail(
 	email: string,
 	siteName: string,
 	strings?: MagicLinkEmailStrings,
+	locale?: string,
 ): EmailMessage {
 	const s = strings ?? defaultMagicLinkEmailStrings(siteName);
+	// Localized copy may be RTL — set lang/dir on the root so RTL text renders
+	// correctly. Defaults to ltr when no locale is threaded through (#915).
+	const langAttr = locale ? ` lang="${escapeHtml(locale)}" dir="${localeDir(locale)}"` : "";
 	return {
 		to: email,
 		subject: s.subject,
 		text: `${s.textLinkInstruction}\n\n${linkUrl}\n\n${s.expiryNote}\n\n${s.ignoreNote}`,
 		html: `
 <!DOCTYPE html>
-<html>
+<html${langAttr}>
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
diff --git a/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts b/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts
index d1441f5fa3..6846e47fed 100644
--- a/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts
+++ b/packages/core/src/astro/routes/api/admin/users/[id]/send-recovery.ts
@@ -58,15 +58,15 @@ export const POST: APIRoute = async ({ request, params, locals }) => {
 		const baseUrl = await getSiteBaseUrl(emdash.db, request);
 		const siteName = (await options.get<string>("emdash:site_title")) ?? "EmDash";
 
+		// Localized copy following the site locale (#915); the locale also
+		// drives lang/dir on the email HTML so RTL copy renders correctly.
+		const emailLocale = await getEmailLocale(emdash.db, request);
 		const config: MagicLinkConfig = {
 			baseUrl,
 			siteName,
 			email: (message) => emdash.email!.send(message, "system"),
-			// Localized copy following the site locale (#915)
-			emailStrings: await getMagicLinkEmailStrings(
-				await getEmailLocale(emdash.db, request),
-				siteName,
-			),
+			emailStrings: await getMagicLinkEmailStrings(emailLocale, siteName),
+			emailLocale,
 		};
 
 		// Send recovery link
diff --git a/packages/core/src/astro/routes/api/auth/invite/index.ts b/packages/core/src/astro/routes/api/auth/invite/index.ts
index 3085f1d5ce..4949b682a6 100644
--- a/packages/core/src/astro/routes/api/auth/invite/index.ts
+++ b/packages/core/src/astro/routes/api/auth/invite/index.ts
@@ -59,8 +59,9 @@ export const POST: APIRoute = async ({ request, locals }) => {
 
 		// Localize the invite email copy (#915). Only resolved when an
 		// email will actually be sent — the copy-link fallback has no copy.
-		const emailStrings = emailSend
-			? await getInviteEmailStrings(await getEmailLocale(emdash.db, request), siteName)
+		const emailLocale = emailSend ? await getEmailLocale(emdash.db, request) : undefined;
+		const emailStrings = emailLocale
+			? await getInviteEmailStrings(emailLocale, siteName)
 			: undefined;
 
 		const result = await createInvite(
@@ -69,6 +70,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 				siteName,
 				email: emailSend,
 				emailStrings,
+				emailLocale,
 			},
 			adapter,
 			body.email,
diff --git a/packages/core/src/astro/routes/api/auth/magic-link/send.ts b/packages/core/src/astro/routes/api/auth/magic-link/send.ts
index 3808ce9f5c..f35c157934 100644
--- a/packages/core/src/astro/routes/api/auth/magic-link/send.ts
+++ b/packages/core/src/astro/routes/api/auth/magic-link/send.ts
@@ -64,15 +64,15 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		const baseUrl = await getSiteBaseUrl(emdash.db, request);
 		const siteName = (await options.get<string>("emdash:site_title")) ?? "EmDash";
 
+		// Localized copy following the site locale (#915); the locale also
+		// drives lang/dir on the email HTML so RTL copy renders correctly.
+		const emailLocale = await getEmailLocale(emdash.db, request);
 		const config: MagicLinkConfig = {
 			baseUrl,
 			siteName,
 			email: (message) => emdash.email!.send(message, "system"),
-			// Localized copy following the site locale (#915)
-			emailStrings: await getMagicLinkEmailStrings(
-				await getEmailLocale(emdash.db, request),
-				siteName,
-			),
+			emailStrings: await getMagicLinkEmailStrings(emailLocale, siteName),
+			emailLocale,
 		};
 
 		// Send magic link (silently fails if user doesn't exist)

From bb84501424adaf232e70a4dc72f129b8da9afb18 Mon Sep 17 00:00:00 2001
From: swissky <30409887+swissky@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:11:46 +0200
Subject: [PATCH 4/4] refactor(auth): hoist locale split regex to module scope
 (lint)

---
 packages/auth/src/invite.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/auth/src/invite.ts b/packages/auth/src/invite.ts
index 4535fc2791..eb11cf62ff 100644
--- a/packages/auth/src/invite.ts
+++ b/packages/auth/src/invite.ts
@@ -20,9 +20,11 @@ export function escapeHtml(s: string): string {
  */
 const RTL_SUBTAGS = new Set(["ar", "fa", "he", "ur", "ps", "sd", "ug", "yi", "ckb", "dv"]);
 
+const SUBTAG_SPLIT_RE = /[-_]/;
+
 /** Text direction for a BCP 47 locale code ("ltr" unless the primary subtag is RTL). */
 export function localeDir(locale: string): "ltr" | "rtl" {
-	const primary = locale.toLowerCase().split(/[-_]/)[0] ?? "";
+	const primary = locale.toLowerCase().split(SUBTAG_SPLIT_RE)[0] ?? "";
 	return RTL_SUBTAGS.has(primary) ? "rtl" : "ltr";
 }