@learncard/email-templates 1.0.4 → 1.0.5

package/src/__tests__/i18n.test.ts

@@ -0,0 +1,329 @@
+/**
+ * i18n tests for @learncard/email-templates (LC-1902, workstream C1).
+ *
+ * Asserts:
+ *   1. Every template renders for every locale (en/es/fr/ar) without throwing.
+ *   2. A sampled es/fr/ar subject + body differs from the EN output.
+ *   3. EN output is unchanged: rendering with `locale === 'en'` or `locale === undefined`
+ *      is byte-identical (the correctness gate — no behavior change for EN).
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { renderEmail } from '../render';
+import { renderSms } from '../sms';
+import { DEFAULT_BRANDING } from '../branding';
+import { resolveCatalogLocale, htmlDir } from '../i18n';
+import type { NotificationLocale } from '../i18n';
+import type { TemplateId, TemplateDataMap } from '../render';
+
+const LOCALES: NotificationLocale[] = ['en', 'es', 'fr', 'ar'];
+
+// Minimal valid data for every template ID.
+const FIXTURES: { [K in TemplateId]: TemplateDataMap[K] } = {
+    'embed-email-verification': {
+        verificationCode: '123456',
+        verificationEmail: 'test@example.com',
+    },
+    'contact-method-verification': { verificationToken: 'f47ac10b-58cc-4372-a567-0e02b2c3d479' },
+    'login-verification-code': { verificationCode: '654321' },
+    'contact-method-verification-1': { verificationCode: '111222' },
+    'recovery-email-code': { verificationCode: '999888', verificationEmail: 'recover@example.com' },
+    'recovery-email-verification': { verificationCode: '777666' },
+    'inbox-claim': {
+        claimUrl: 'https://learncard.app/claim/abc123',
+        credential: { name: 'Test Badge', type: 'badge' },
+        issuer: { name: 'Acme Corp' },
+        recipient: { name: 'Jane Doe' },
+    },
+    'universal-inbox-claim': {
+        claimUrl: 'https://learncard.app/claim/abc123',
+        credential: { name: 'Test Badge', type: 'badge' },
+        issuer: { name: 'Acme Corp' },
+    },
+    'guardian-approval': {
+        approvalUrl: 'https://learncard.app/approve?token=abc',
+        approvalToken: 'abc',
+        requester: { displayName: 'Alex Student', profileId: 'p1' },
+        guardian: { email: 'parent@example.com' },
+    },
+    'account-approved': { user: { displayName: 'New User' } },
+    'account-approved-email': { user: { displayName: 'New User' } },
+    'recovery-key': { recoveryKey: 'mango-delta-fox-echo-bravo-seven-lima-niner' },
+    'recovery-key-backup': { recoveryKey: 'mango-delta-fox-echo-bravo-seven-lima-niner' },
+    'endorsement-request': {
+        shareLink: 'https://learncard.app/share/xyz',
+        recipient: { name: 'Dr. Emily Chen' },
+        issuer: { name: 'John Doe' },
+        credential: { name: 'Teaching Certificate' },
+        message: 'Please endorse my skills!',
+    },
+    'universal-inbox-claim-1': {
+        shareLink: 'https://learncard.app/share/xyz',
+        recipient: { name: 'Dr. Emily Chen' },
+        issuer: { name: 'John Doe' },
+    },
+    'credential-awaiting-guardian': {
+        issuer: { name: 'Springfield School District' },
+        credential: { name: 'Perfect Attendance Award' },
+        recipient: { email: 'student@example.com' },
+    },
+    'guardian-approved-claim': {
+        issuer: { name: 'Springfield School District' },
+        credential: { name: 'Perfect Attendance Award' },
+    },
+    'guardian-credential-approval': {
+        approvalUrl: 'https://learncard.app/guardian/approve?token=abc',
+        approvalToken: 'abc',
+        issuer: { name: 'Springfield School District' },
+        credential: { name: 'Perfect Attendance Award' },
+        recipient: { email: 'student@example.com' },
+    },
+    'guardian-email-otp': { verificationCode: '445566' },
+    'guardian-rejected-credential': {
+        issuer: { name: 'Springfield School District' },
+        credential: { name: 'Perfect Attendance Award' },
+        recipient: { email: 'student@example.com' },
+    },
+};
+
+const ALL_TEMPLATE_IDS = Object.keys(FIXTURES) as TemplateId[];
+
+// ---------------------------------------------------------------------------
+// 1. Every template renders for every locale without throwing
+// ---------------------------------------------------------------------------
+
+describe('i18n — every template renders in every locale', () => {
+    for (const templateId of ALL_TEMPLATE_IDS) {
+        for (const locale of LOCALES) {
+            it(`${templateId} (${locale}) renders`, async () => {
+                const result = await renderEmail(
+                    templateId,
+                    DEFAULT_BRANDING,
+                    FIXTURES[templateId],
+                    locale
+                );
+
+                expect(result.html).toContain('<!DOCTYPE');
+                expect(result.text.length).toBeGreaterThan(0);
+                expect(result.subject.length).toBeGreaterThan(0);
+            });
+        }
+    }
+});
+
+// ---------------------------------------------------------------------------
+// 2. es/fr/ar subject + body differ from en
+// ---------------------------------------------------------------------------
+
+describe('i18n — non-EN locales localize content', () => {
+    // Use a spread of representative templates; subjects are the cleanest signal.
+    const SAMPLES: TemplateId[] = [
+        'inbox-claim',
+        'account-approved',
+        'recovery-key',
+        'guardian-credential-approval',
+        'guardian-email-otp',
+        'credential-awaiting-guardian',
+    ];
+
+    for (const templateId of SAMPLES) {
+        it(`${templateId} subject + body differ per locale`, async () => {
+            const en = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId], 'en');
+            const subjects = new Set<string>([en.subject]);
+
+            for (const locale of ['es', 'fr', 'ar'] as NotificationLocale[]) {
+                const localized = await renderEmail(
+                    templateId,
+                    DEFAULT_BRANDING,
+                    FIXTURES[templateId],
+                    locale
+                );
+
+                // Subject should differ from EN (localized).
+                expect(localized.subject).not.toBe(en.subject);
+                // Body should differ from EN (the passport/sign-off copy localizes).
+                expect(localized.html).not.toBe(en.html);
+                // …but still render the same brand name.
+                expect(localized.html).toContain(DEFAULT_BRANDING.brandName);
+                // Subjects are unique across locales (no accidental aliasing).
+                expect(subjects.has(localized.subject)).toBe(false);
+                subjects.add(localized.subject);
+            }
+        });
+    }
+
+    it('renders localized footer disclaimer per locale (shared chrome)', async () => {
+        const en = await renderEmail(
+            'inbox-claim',
+            DEFAULT_BRANDING,
+            FIXTURES['inbox-claim'],
+            'en'
+        );
+        const es = await renderEmail(
+            'inbox-claim',
+            DEFAULT_BRANDING,
+            FIXTURES['inbox-claim'],
+            'es'
+        );
+
+        // EN chrome present in EN, absent in ES.
+        expect(en.text).toContain('You received this email because');
+        expect(es.text).not.toContain('You received this email because');
+    });
+
+    it('localizes the "The {brand} Team" sign-off across all templates', async () => {
+        for (const templateId of ALL_TEMPLATE_IDS) {
+            const en = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId], 'en');
+            const es = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId], 'es');
+
+            expect(en.text).toContain(`The ${DEFAULT_BRANDING.brandName} Team`);
+            expect(es.text).toContain(`El equipo de ${DEFAULT_BRANDING.brandName}`);
+            expect(es.text).not.toContain(`The ${DEFAULT_BRANDING.brandName} Team`);
+        }
+    });
+
+    it('localizes the verification-code preview sub-title (not just the subject)', async () => {
+        const en = await renderEmail(
+            'login-verification-code',
+            DEFAULT_BRANDING,
+            FIXTURES['login-verification-code'],
+            'en'
+        );
+        const es = await renderEmail(
+            'login-verification-code',
+            DEFAULT_BRANDING,
+            FIXTURES['login-verification-code'],
+            'es'
+        );
+
+        // Preview text renders into the hidden <Preview> block in the HTML.
+        expect(en.html).toContain('Your code:');
+        expect(es.html).toContain('Tu código:');
+        expect(es.html).not.toContain('Your code:');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 3. EN output is unchanged (correctness gate)
+// ---------------------------------------------------------------------------
+
+describe('i18n — EN is unchanged', () => {
+    it('locale undefined === locale "en" (byte-identical html/text/subject)', async () => {
+        for (const templateId of ALL_TEMPLATE_IDS) {
+            const noLocale = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId]);
+            const explicitEn = await renderEmail(
+                templateId,
+                DEFAULT_BRANDING,
+                FIXTURES[templateId],
+                'en'
+            );
+
+            expect(noLocale.subject).toBe(explicitEn.subject);
+            expect(noLocale.html).toBe(explicitEn.html);
+            expect(noLocale.text).toBe(explicitEn.text);
+        }
+    });
+
+    it('unknown locale falls back to EN (no throw, EN subject)', async () => {
+        const templateId: TemplateId = 'inbox-claim';
+        const en = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId], 'en');
+        const unknown = await renderEmail(
+            templateId,
+            DEFAULT_BRANDING,
+            FIXTURES[templateId],
+            'xx-XX'
+        );
+
+        expect(unknown.subject).toBe(en.subject);
+        expect(unknown.html).toBe(en.html);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// resolveCatalogLocale
+// ---------------------------------------------------------------------------
+
+describe('resolveCatalogLocale', () => {
+    it('returns the supported base locale for BCP-47 input', () => {
+        expect(resolveCatalogLocale('en')).toBe('en');
+        expect(resolveCatalogLocale('en-US')).toBe('en');
+        expect(resolveCatalogLocale('es-MX')).toBe('es');
+        expect(resolveCatalogLocale('fr-CA')).toBe('fr');
+        expect(resolveCatalogLocale('ar')).toBe('ar');
+    });
+
+    it('falls back to en for unsupported / missing input (never throws)', () => {
+        expect(resolveCatalogLocale('de')).toBe('en');
+        expect(resolveCatalogLocale('zh-CN')).toBe('en');
+        expect(resolveCatalogLocale(undefined)).toBe('en');
+        expect(resolveCatalogLocale(null)).toBe('en');
+        expect(resolveCatalogLocale('')).toBe('en');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// RTL direction
+// ---------------------------------------------------------------------------
+
+describe('htmlDir', () => {
+    it('returns rtl for Arabic (incl. BCP-47), ltr otherwise', () => {
+        expect(htmlDir('ar')).toBe('rtl');
+        expect(htmlDir('ar-EG')).toBe('rtl');
+        expect(htmlDir('en')).toBe('ltr');
+        expect(htmlDir('es')).toBe('ltr');
+        expect(htmlDir('fr')).toBe('ltr');
+        expect(htmlDir(undefined)).toBe('ltr');
+        expect(htmlDir('xx-XX')).toBe('ltr');
+    });
+});
+
+describe('i18n — rendered <Html dir> reflects locale', () => {
+    it.each(ALL_TEMPLATE_IDS)('%s renders dir="rtl" for Arabic', async templateId => {
+        const ar = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId], 'ar');
+        expect(ar.html).toContain('dir="rtl"');
+    });
+
+    it.each(ALL_TEMPLATE_IDS)('%s renders dir="ltr" (not rtl) for English', async templateId => {
+        const en = await renderEmail(templateId, DEFAULT_BRANDING, FIXTURES[templateId], 'en');
+        expect(en.html).toContain('dir="ltr"');
+        expect(en.html).not.toContain('dir="rtl"');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// SMS i18n
+// ---------------------------------------------------------------------------
+
+describe('i18n — renderSms localizes', () => {
+    const inboxData = {
+        claimUrl: 'https://learncard.app/claim/abc',
+        recipient: { name: 'Jane' },
+        issuer: { name: 'Acme' },
+        credential: { name: 'Test Badge', type: 'badge' },
+    };
+
+    it('inbox-claim SMS differs per locale and brand name is interpolated', () => {
+        const en = renderSms('inbox-claim', DEFAULT_BRANDING, inboxData, 'en');
+        const es = renderSms('inbox-claim', DEFAULT_BRANDING, inboxData, 'es');
+
+        expect(en).toContain('Claim it here');
+        expect(es).toContain('Reclámalo aquí');
+        expect(es).not.toBe(en);
+        // Both carry the dynamic claim URL.
+        expect(en).toContain('https://learncard.app/claim/abc');
+        expect(es).toContain('https://learncard.app/claim/abc');
+    });
+
+    it('verification SMS localizes and is unchanged for EN vs undefined', () => {
+        const data = { verificationToken: '999222' };
+        const en = renderSms('contact-method-verification', DEFAULT_BRANDING, data, 'en');
+        const undefinedLocale = renderSms('contact-method-verification', DEFAULT_BRANDING, data);
+        const es = renderSms('contact-method-verification', DEFAULT_BRANDING, data, 'es');
+
+        expect(en).toBe(undefinedLocale);
+        expect(en).toContain('Your LearnCard verification code is:');
+        expect(es).toContain('Tu código de verificación de LearnCard es:');
+        expect(en).toContain('999222');
+    });
+});

package/src/components/Layout.tsx

@@ -19,6 +19,7 @@ import {
 import * as React from 'react';
 
 import type { TenantBranding } from '../branding';
+import { SHARED, htmlLang, htmlDir, interpolate, resolveCatalogLocale } from '../i18n';
 
 interface LayoutProps {
     branding: TenantBranding;
@@ -27,69 +28,77 @@ interface LayoutProps {
     /** Show the brand icon at the top of the card. Defaults to true.
      *  Set to false when the template already has an IssuerLogo. */
     showHeaderLogo?: boolean;
+    /** Recipient locale (BCP-47). Defaults to English. */
+    locale?: string;
 }
 
-export const Layout: React.FC<LayoutProps> = ({ branding, preview, children, showHeaderLogo = true }) => (
-    <Html lang="en">
-        <Head />
-
-        <Preview>{preview}</Preview>
-
-        <Body style={body}>
-            {/* Top spacer — Gmail strips <body> padding, so use an inline div */}
-            <div style={topSpacer}>&nbsp;</div>
-
-            {/* Wordmark — sits above the white card like the Postmark layout */}
-            <Container style={wordmarkContainer}>
-                <Text style={wordmark}>
-                    <Link href={branding.websiteUrl} style={wordmarkLink}>
-                        {branding.brandName.toUpperCase()}
-                    </Link>
-                </Text>
-            </Container>
-
-            <Container style={container}>
-                {/* Optional brand icon */}
-                {showHeaderLogo && (
-                    <Section style={headerLogo}>
-                        <Img
-                            src={branding.logoUrl}
-                            alt={branding.logoAlt}
-                            width={80}
-                            height={80}
-                            style={logoImg}
-                        />
+export const Layout: React.FC<LayoutProps> = ({
+    branding,
+    preview,
+    children,
+    showHeaderLogo = true,
+    locale,
+}) => {
+    const chrome = SHARED[resolveCatalogLocale(locale)];
+    const disclaimerText = interpolate(chrome.footerDisclaimer, { brandName: branding.brandName });
+
+    return (
+        <Html lang={htmlLang(locale)} dir={htmlDir(locale)}>
+            <Head />
+
+            <Preview>{preview}</Preview>
+
+            <Body style={body}>
+                {/* Top spacer — Gmail strips <body> padding, so use an inline div */}
+                <div style={topSpacer}>&nbsp;</div>
+
+                {/* Wordmark — sits above the white card like the Postmark layout */}
+                <Container style={wordmarkContainer}>
+                    <Text style={wordmark}>
+                        <Link href={branding.websiteUrl} style={wordmarkLink}>
+                            {branding.brandName.toUpperCase()}
+                        </Link>
+                    </Text>
+                </Container>
+
+                <Container style={container}>
+                    {/* Optional brand icon */}
+                    {showHeaderLogo && (
+                        <Section style={headerLogo}>
+                            <Img
+                                src={branding.logoUrl}
+                                alt={branding.logoAlt}
+                                width={80}
+                                height={80}
+                                style={logoImg}
+                            />
+                        </Section>
+                    )}
+
+                    {/* Content */}
+                    <Section style={showHeaderLogo ? contentAfterLogo : content}>
+                        {children}
                     </Section>
-                )}
-
-                {/* Content */}
-                <Section style={showHeaderLogo ? contentAfterLogo : content}>
-                    {children}
-                </Section>
-            </Container>
-
-            {/* Footer — sits below the white card in the gray area */}
-            <Container style={footerContainer}>
-                <Text style={footerDisclaimer}>
-                    You received this email because someone requested to add this email
-                    to their {branding.brandName} account. Please ignore this email if
-                    this was not you.
-                </Text>
-
-                <Text style={footerCopyright}>
-                    {branding.copyrightHolder} &copy; {new Date().getFullYear()}
-                </Text>
-
-                <Text style={footerLinks}>
-                    <Link href={`mailto:${branding.supportEmail}`} style={footerLink}>
-                        Contact Support
-                    </Link>
-                </Text>
-            </Container>
-        </Body>
-    </Html>
-);
-
+                </Container>
+
+                {/* Footer — sits below the white card in the gray area */}
+                <Container style={footerContainer}>
+                    <Text style={footerDisclaimer}>{disclaimerText}</Text>
+
+                    <Text style={footerCopyright}>
+                        {branding.copyrightHolder} &copy; {new Date().getFullYear()}
+                    </Text>
+
+                    <Text style={footerLinks}>
+                        <Link href={`mailto:${branding.supportEmail}`} style={footerLink}>
+                            {chrome.contactSupport}
+                        </Link>
+                    </Text>
+                </Container>
+            </Body>
+        </Html>
+    );
+};
 // ---------------------------------------------------------------------------
 // Styles (inline for email compatibility)
 // ---------------------------------------------------------------------------

package/src/components/LinkFallback.tsx

@@ -7,23 +7,31 @@
 import { Text, Link, Hr } from '@react-email/components';
 import * as React from 'react';
 
+import { SHARED, resolveCatalogLocale } from '../i18n';
+
 interface LinkFallbackProps {
     href: string;
+    /** Recipient locale (BCP-47). Defaults to English. */
+    locale?: string;
 }
 
-export const LinkFallback: React.FC<LinkFallbackProps> = ({ href }) => (
-    <>
-        <Hr style={divider} />
+export const LinkFallback: React.FC<LinkFallbackProps> = ({ href, locale }) => {
+    const chrome = SHARED[resolveCatalogLocale(locale)];
+
+    return (
+        <>
+            <Hr style={divider} />
 
-        <Text style={hint}>
-            If you have trouble with the button above, copy and paste this link into your browser:
-        </Text>
+            <Text style={hint}>{chrome.linkFallbackHint}</Text>
 
-        <Text style={linkText}>
-            <Link href={href} style={link}>{href}</Link>
-        </Text>
-    </>
-);
+            <Text style={linkText}>
+                <Link href={href} style={link}>
+                    {href}
+                </Link>
+            </Text>
+        </>
+    );
+};
 
 const divider: React.CSSProperties = {
     borderColor: '#e5e7eb',

package/src/i18n.ts

@@ -0,0 +1,110 @@
+/**
+ * i18n foundation for @learncard/email-templates (LC-1902, workstream C1).
+ *
+ * Mirrors the dependency-free per-locale dictionary pattern used by the C2
+ * notification catalog (`brain-service/src/helpers/notificationMessages.ts`).
+ *
+ * This module owns:
+ *   - `NotificationLocale` — the union of supported locales (en/es/fr/ar).
+ *   - `resolveCatalogLocale()` — narrow a runtime BCP-47 string to a supported
+ *     locale, falling back to `'en'`. Never throws.
+ *   - `SHARED` — strings shared across templates via the `Layout` /
+ *     `LinkFallback` chrome (footer disclaimer, "Contact Support", the
+ *     link-fallback hint). Keeps the shared chrome DRY.
+ *
+ * Brand values (`brandName`, `appUrl`, `copyrightHolder`, …) are intentionally
+ * NOT in this catalog — they stay interpolated from `TenantBranding`.
+ */
+
+/** Locales supported by the email/SMS catalogs. */
+export type NotificationLocale = 'en' | 'es' | 'fr' | 'ar';
+
+const DEFAULT_LOCALE: NotificationLocale = 'en';
+
+const SUPPORTED_LOCALES = new Set<NotificationLocale>(['en', 'es', 'fr', 'ar']);
+
+/**
+ * Narrow an arbitrary runtime locale string (BCP-47, e.g. `es`, `es-MX`) down
+ * to one of the supported catalog locales. Falls back to `'en'`.
+ *
+ * Accepts `string | undefined` so callers can pass through optional values
+ * (e.g. a missing recipient locale) without a guard.
+ */
+export const resolveCatalogLocale = (locale?: string | null): NotificationLocale => {
+    if (typeof locale !== 'string' || locale.length === 0) return DEFAULT_LOCALE;
+    const base = locale.toLowerCase().split('-')[0] as NotificationLocale;
+    return SUPPORTED_LOCALES.has(base) ? base : DEFAULT_LOCALE;
+};
+
+/**
+ * Map a supported locale to the value for the top-level `<Html lang>`
+ * attribute. BCP-47 base tag is sufficient for email clients / RTL handling.
+ */
+export const htmlLang = (locale?: string | null): string => resolveCatalogLocale(locale);
+
+/** Locales that render right-to-left. */
+const RTL_LOCALES = new Set<NotificationLocale>(['ar']);
+
+/**
+ * Text direction for the top-level `<Html dir>` attribute. Arabic renders
+ * right-to-left; everything else left-to-right. Email clients need an explicit
+ * `dir="rtl"` to flip alignment, punctuation, and layout for RTL languages.
+ */
+export const htmlDir = (locale?: string | null): 'ltr' | 'rtl' =>
+    RTL_LOCALES.has(resolveCatalogLocale(locale)) ? 'rtl' : 'ltr';
+
+// ---------------------------------------------------------------------------
+// Shared chrome strings (Layout footer, LinkFallback hint)
+// ---------------------------------------------------------------------------
+
+export interface SharedChromeStrings {
+    /** Footer disclaimer shown on every email (uses {brandName}). */
+    footerDisclaimer: string;
+    /** "Contact Support" link text in the footer. */
+    contactSupport: string;
+    /** Hint above the copy/paste link fallback. */
+    linkFallbackHint: string;
+    /** Sign-off line at the end of every email body (uses {brandName}). */
+    teamSignature: string;
+}
+
+export const SHARED: Record<NotificationLocale, SharedChromeStrings> = {
+    en: {
+        footerDisclaimer:
+            'You received this email because someone requested to add this email to their {brandName} account. Please ignore this email if this was not you.',
+        contactSupport: 'Contact Support',
+        linkFallbackHint:
+            'If you have trouble with the button above, copy and paste this link into your browser:',
+        teamSignature: 'The {brandName} Team',
+    },
+    es: {
+        footerDisclaimer:
+            'Recibiste este correo porque alguien solicitó añadir este correo a su cuenta de {brandName}. Ignora este mensaje si no fuiste tú.',
+        contactSupport: 'Contactar con soporte',
+        linkFallbackHint:
+            'Si tienes problemas con el botón anterior, copia y pega este enlace en tu navegador:',
+        teamSignature: 'El equipo de {brandName}',
+    },
+    fr: {
+        footerDisclaimer:
+            'Vous avez reçu cet e-mail car quelqu\u2019un a demandé à ajouter cette adresse e-mail à son compte {brandName}. Veuillez ignorer cet e-mail si vous n\u2019êtes pas à l\u2019origine de cette demande.',
+        contactSupport: 'Contacter le support',
+        linkFallbackHint:
+            'Si le bouton ci-dessus ne fonctionne pas, copiez et collez ce lien dans votre navigateur :',
+        teamSignature: 'L’équipe {brandName}',
+    },
+    ar: {
+        footerDisclaimer:
+            'لقد تلقيت هذه الرسالة لأن أحدهم طلب إضافة هذا البريد إلى حسابه في {brandName}. يرجى تجاهل هذه الرسالة إذا لم تكن أنت.',
+        contactSupport: 'تواصل مع الدعم',
+        linkFallbackHint: 'إذا واجهت مشكلة مع الزر أعلاه، انسخ هذا الرابط والصقه في متصفحك:',
+        teamSignature: 'فريق {brandName}',
+    },
+};
+
+/** Replace `{var}` placeholders in `template` with values from `params`. */
+export const interpolate = (template: string, params: Record<string, string | undefined>): string =>
+    template.replace(/\{(\w+)\}/g, (match, key: string) => {
+        const value = params[key];
+        return value === undefined ? match : value;
+    });

package/src/index.ts

@@ -17,6 +17,10 @@
 export { resolveBranding, DEFAULT_BRANDING } from './branding';
 export type { TenantBranding } from './branding';
 
+// i18n (LC-1902)
+export { resolveCatalogLocale } from './i18n';
+export type { NotificationLocale } from './i18n';
+
 // Email rendering
 export { renderEmail } from './render';
 export type { RenderedEmail, TemplateId, TemplateDataMap } from './render';
@@ -37,10 +41,19 @@ export type {
 
 // SMS rendering
 export { renderSms } from './sms';
-export type { SmsTemplateId, SmsTemplateDataMap, SmsInboxClaimData, SmsVerificationData } from './sms';
+export type {
+    SmsTemplateId,
+    SmsTemplateDataMap,
+    SmsInboxClaimData,
+    SmsVerificationData,
+} from './sms';
 
 // Server-side tenant resolution
-export { resolveTenantFromRequest, registerOriginMapping, registerTenantBranding } from './tenant-registry';
+export {
+    resolveTenantFromRequest,
+    registerOriginMapping,
+    registerTenantBranding,
+} from './tenant-registry';
 export type { ResolvedTenant, RequestHeaders } from './tenant-registry';
 
 // Template components are intentionally NOT re-exported from the barrel.