feat: Add project-scoped language for unsubscribe footer and contact-facing pages

2025-12-21 13:09:21 +01:00
parent 8a136dde55
commit e1f826357d
15 changed files with 499 additions and 41 deletions
@@ -211,10 +211,14 @@ export class Contacts {

    const contact = await ContactService.getById(contactId);

+    // Fetch project to get language preference
+    const project = await ContactService.getProjectByContactId(contactId);
+
    return res.status(200).json({
      id: contact.id,
      email: contact.email,
      subscribed: contact.subscribed,
+      language: project?.language || 'en',
    });
  }

@@ -339,6 +339,25 @@ export class ContactService {
    return contact;
  }

+  /**
+   * Get project by contact ID
+   * Used to fetch project settings for public endpoints
+   */
+  public static async getProjectByContactId(contactId: string): Promise<{language: string} | null> {
+    const contact = await prisma.contact.findUnique({
+      where: {id: contactId},
+      select: {
+        project: {
+          select: {
+            language: true,
+          },
+        },
+      },
+    });
+
+    return contact?.project || null;
+  }
+
  /**
   * PUBLIC: Subscribe a contact
   */
@@ -5,7 +5,7 @@ import signale from 'signale';
 import {DASHBOARD_URI, LANDING_URI, STRIPE_ENABLED} from '../app/constants.js';
 import {prisma} from '../database/prisma.js';
 import {HttpException} from '../exceptions/index.js';
-import {renderTemplate} from '@plunk/shared';
+import {renderTemplate, createTranslatorSync} from '@plunk/shared';

 import {BillingLimitService} from './BillingLimitService.js';
 import {DomainService} from './DomainService.js';
@@ -603,19 +603,28 @@ export class EmailService {
    let html = content;

    const unsubscribeHtml = includeUnsubscribe
-      ? `<table align="center" width="100%" style="max-width: 480px; width: 100%; margin-left: auto; margin-right: auto; font-family: Inter, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'; border: 0; cellpadding: 0; cellspacing: 0;" role="presentation">
+      ? (() => {
+          // Get translator for project's language
+          const translator = createTranslatorSync(project.language || 'en');
+          const unsubscribeText = translator.t('email.footer.unsubscribeText', {
+            projectName: project.name,
+          });
+          const updatePreferencesText = translator.t('email.footer.updatePreferences');
+
+          return `<table align="center" width="100%" style="max-width: 480px; width: 100%; margin-left: auto; margin-right: auto; font-family: Inter, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'; border: 0; cellpadding: 0; cellspacing: 0;" role="presentation">
          <tbody>
            <tr>
              <td>
                <hr style="border: none; border-top: 1px solid #eaeaea; width: 100%; margin-top: 12px; margin-bottom: 12px;">
                <p style="font-size: 12px; line-height: 24px; margin: 16px 0; text-align: center; color: rgb(64, 64, 64);">
-                  You received this email because you agreed to receive emails from ${project.name}. If you no longer wish to receive emails like this, please
-                  <a href="${DASHBOARD_URI}/unsubscribe/${contact.id}">update your preferences</a>.
+                  ${unsubscribeText}
+                  <a href="${DASHBOARD_URI}/unsubscribe/${contact.id}">${updatePreferencesText}</a>.
                </p>
              </td>
            </tr>
          </tbody>
-        </table>`
+        </table>`;
+        })()
      : '';

    // Add Plunk badge if billing is enabled and project has no subscription (free tier)
@@ -1,4 +1,5 @@
 import {Button, Card, CardContent} from '@plunk/ui';
+import {createTranslator, type Translator} from '@plunk/shared';
 import {AnimatePresence, motion} from 'framer-motion';
 import {useRouter} from 'next/router';
 import React, {useEffect, useState} from 'react';
@@ -9,6 +10,7 @@ interface ContactInfo {
  id: string;
  email: string;
  subscribed: boolean;
+  language: string;
 }

 export default function Manage() {
@@ -16,6 +18,7 @@ export default function Manage() {
  const {id} = router.query;

  const [contact, setContact] = useState<ContactInfo | null>(null);
+  const [translator, setTranslator] = useState<Translator | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [updating, setUpdating] = useState(false);
@@ -29,6 +32,11 @@ export default function Manage() {
        setLoading(true);
        const data = await network.fetch<ContactInfo>('GET', `/contacts/public/${id}`);
        setContact(data);
+
+        // Load translations for the project's language
+        const t = await createTranslator(data.language || 'en');
+        setTranslator(t);
+
        setError(null);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to load contact information');
@@ -41,7 +49,7 @@ export default function Manage() {
  }, [id]);

  const handleToggleSubscription = async () => {
-    if (!id || typeof id !== 'string' || !contact) return;
+    if (!id || typeof id !== 'string' || !contact || !translator) return;

    try {
      setUpdating(true);
@@ -51,7 +59,11 @@ export default function Manage() {

      const data = await network.fetch<ContactInfo>('POST', endpoint);
      setContact(data);
-      setSaveMessage(data.subscribed ? 'Subscribed successfully!' : 'Unsubscribed successfully!');
+      setSaveMessage(
+        data.subscribed
+          ? translator.t('pages.manage.subscribedSuccess')
+          : translator.t('pages.manage.unsubscribedSuccess'),
+      );
      setError(null);

      // Clear success message after 3 seconds
@@ -63,7 +75,8 @@ export default function Manage() {
    }
  };

-  if (loading) {
+  // Don't render until translations are loaded
+  if (!translator) {
    return (
      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
        <div className={'flex flex-col gap-6 max-w-2xl w-full px-4'}>
@@ -92,6 +105,35 @@ export default function Manage() {
    );
  }

+  if (loading) {
+    return (
+      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
+        <div className={'flex flex-col gap-6 max-w-2xl w-full px-4'}>
+          <Card>
+            <CardContent className="p-8">
+              <div className="flex flex-col items-center gap-4">
+                <svg
+                  className="h-8 w-8 animate-spin text-neutral-500"
+                  xmlns="http://www.w3.org/2000/svg"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                >
+                  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                  <path
+                    className="opacity-75"
+                    fill="currentColor"
+                    d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                  />
+                </svg>
+                <p className="text-sm text-neutral-500">{translator.t('pages.common.loading')}</p>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      </div>
+    );
+  }
+
  if (error && !contact) {
    return (
      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
@@ -112,7 +154,7 @@ export default function Manage() {
                    <path d="M6 18L18 6M6 6l12 12" />
                  </svg>
                </div>
-                <h1 className="text-2xl font-bold text-neutral-900">Error</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.common.error')}</h1>
                <p className="text-neutral-500">{error}</p>
              </div>
            </CardContent>
@@ -129,20 +171,20 @@ export default function Manage() {
          <CardContent className="p-8">
            <div className="flex flex-col gap-6">
              <div className="flex flex-col items-center text-center gap-2">
-                <h1 className="text-2xl font-bold text-neutral-900">Manage Preferences</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.manage.title')}</h1>
                <p className="text-neutral-500">
-                  Manage email preferences for <strong>{contact?.email}</strong>
+                  {translator.t('pages.manage.description', {email: contact?.email || ''})}
                </p>
              </div>

              <div className="border rounded-lg p-6 bg-white">
                <div className="flex items-center justify-between">
                  <div className="flex-1">
-                    <h3 className="font-medium text-neutral-900">Email Subscription</h3>
+                    <h3 className="font-medium text-neutral-900">{translator.t('pages.manage.subscriptionLabel')}</h3>
                    <p className="text-sm text-neutral-500 mt-1">
                      {contact?.subscribed
-                        ? 'You are currently subscribed to receive emails'
-                        : 'You are currently unsubscribed from emails'}
+                        ? translator.t('pages.manage.subscribedStatus')
+                        : translator.t('pages.manage.unsubscribedStatus')}
                    </p>
                  </div>
                  <button
@@ -194,7 +236,7 @@ export default function Manage() {
                    className="w-full"
                    onClick={() => router.push(`/unsubscribe/${id as string}`)}
                  >
-                    Unsubscribe completely
+                    {translator.t('pages.manage.unsubscribeCompletely')}
                  </Button>
                ) : (
                  <Button
@@ -202,16 +244,13 @@ export default function Manage() {
                    className="w-full"
                    onClick={() => router.push(`/subscribe/${id as string}`)}
                  >
-                    Subscribe to emails
+                    {translator.t('pages.manage.subscribeToEmails')}
                  </Button>
                )}
              </div>

              <div className="text-center text-xs text-neutral-400 mt-2">
-                <p>
-                  This page allows you to manage your email preferences. Your subscription status is updated in
-                  real-time.
-                </p>
+                <p>{translator.t('pages.manage.disclaimer')}</p>
              </div>
            </div>
          </CardContent>
@@ -1,7 +1,7 @@
 import {useEffect, useState} from 'react';
 import {useForm} from 'react-hook-form';
 import {zodResolver} from '@hookform/resolvers/zod';
-import {ProjectSchemas} from '@plunk/shared';
+import {ProjectSchemas, SUPPORTED_LANGUAGES} from '@plunk/shared';
 import {TrackingMode} from '@plunk/db';
 import {
  Alert,
@@ -181,6 +181,7 @@ export default function Settings() {
    defaultValues: {
      name: activeProject?.name || '',
      tracking: activeProject?.tracking ?? TrackingMode.ENABLED,
+      language: activeProject?.language || 'en',
    },
  });

@@ -190,6 +191,7 @@ export default function Settings() {
      form.reset({
        name: activeProject.name,
        tracking: activeProject.tracking ?? TrackingMode.ENABLED,
+        language: activeProject.language || 'en',
      });
    }
  }, [activeProject, form]);
@@ -464,6 +466,39 @@ export default function Settings() {
                        />
                      )}

+                      {/* Language Selection */}
+                      <FormField
+                        control={form.control}
+                        name="language"
+                        render={({field}) => (
+                          <FormItem>
+                            <FormLabel>Customer Language</FormLabel>
+                            <Select onValueChange={field.onChange} defaultValue={field.value || 'en'}>
+                              <FormControl>
+                                <SelectTrigger>
+                                  <SelectValue placeholder="Select language" />
+                                </SelectTrigger>
+                              </FormControl>
+                              <SelectContent>
+                                {SUPPORTED_LANGUAGES.map((lang) => (
+                                  <SelectItem key={lang.code} value={lang.code}>
+                                    <div className="flex items-center gap-2">
+                                      <span>{lang.flag}</span>
+                                      <span>{lang.nativeName}</span>
+                                      <span className="text-neutral-500 text-xs">({lang.name})</span>
+                                    </div>
+                                  </SelectItem>
+                                ))}
+                              </SelectContent>
+                            </Select>
+                            <FormDescription>
+                              Language for customer-facing pages (unsubscribe, preferences) and email footers.
+                            </FormDescription>
+                            <FormMessage />
+                          </FormItem>
+                        )}
+                      />
+
                      <div className="flex justify-end">
                        <Button type="submit" disabled={form.formState.isSubmitting}>
                          {form.formState.isSubmitting ? 'Saving...' : 'Save Changes'}
@@ -1,4 +1,5 @@
 import {Button, Card, CardContent} from '@plunk/ui';
+import {createTranslator, type Translator} from '@plunk/shared';
 import {AnimatePresence, motion} from 'framer-motion';
 import {useRouter} from 'next/router';
 import React, {useEffect, useState} from 'react';
@@ -9,6 +10,7 @@ interface ContactInfo {
  id: string;
  email: string;
  subscribed: boolean;
+  language: string;
 }

 export default function Subscribe() {
@@ -16,6 +18,7 @@ export default function Subscribe() {
  const {id} = router.query;

  const [contact, setContact] = useState<ContactInfo | null>(null);
+  const [translator, setTranslator] = useState<Translator | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [subscribing, setSubscribing] = useState(false);
@@ -29,6 +32,11 @@ export default function Subscribe() {
        setLoading(true);
        const data = await network.fetch<ContactInfo>('GET', `/contacts/public/${id}`);
        setContact(data);
+
+        // Load translations for the project's language
+        const t = await createTranslator(data.language || 'en');
+        setTranslator(t);
+
        setError(null);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to load contact information');
@@ -56,7 +64,8 @@ export default function Subscribe() {
    }
  };

-  if (loading) {
+  // Don't render until translations are loaded
+  if (!translator) {
    return (
      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
        <div className={'flex flex-col gap-6 max-w-2xl w-full px-4'}>
@@ -85,6 +94,35 @@ export default function Subscribe() {
    );
  }

+  if (loading) {
+    return (
+      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
+        <div className={'flex flex-col gap-6 max-w-2xl w-full px-4'}>
+          <Card>
+            <CardContent className="p-8">
+              <div className="flex flex-col items-center gap-4">
+                <svg
+                  className="h-8 w-8 animate-spin text-neutral-500"
+                  xmlns="http://www.w3.org/2000/svg"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                >
+                  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                  <path
+                    className="opacity-75"
+                    fill="currentColor"
+                    d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                  />
+                </svg>
+                <p className="text-sm text-neutral-500">{translator.t('pages.common.loading')}</p>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      </div>
+    );
+  }
+
  if (error && !contact) {
    return (
      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
@@ -105,7 +143,7 @@ export default function Subscribe() {
                    <path d="M6 18L18 6M6 6l12 12" />
                  </svg>
                </div>
-                <h1 className="text-2xl font-bold text-neutral-900">Error</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.common.error')}</h1>
                <p className="text-neutral-500">{error}</p>
              </div>
            </CardContent>
@@ -140,8 +178,10 @@ export default function Subscribe() {
                    <path d="M5 13l4 4L19 7" />
                  </svg>
                </motion.div>
-                <h1 className="text-2xl font-bold text-neutral-900">You&apos;re subscribed!</h1>
-                <p className="text-neutral-500">{contact?.email} is now subscribed to receive emails from us.</p>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.subscribe.successTitle')}</h1>
+                <p className="text-neutral-500">
+                  {translator.t('pages.subscribe.successDescription', {email: contact?.email || ''})}
+                </p>
              </div>
            </CardContent>
          </Card>
@@ -157,9 +197,9 @@ export default function Subscribe() {
          <CardContent className="p-8">
            <div className="flex flex-col gap-6">
              <div className="flex flex-col items-center text-center gap-2">
-                <h1 className="text-2xl font-bold text-neutral-900">Subscribe to updates</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.subscribe.title')}</h1>
                <p className="text-neutral-500">
-                  Would you like to subscribe <strong>{contact?.email}</strong> to receive emails?
+                  {translator.t('pages.subscribe.description', {email: contact?.email || ''})}
                </p>
              </div>

@@ -192,10 +232,10 @@ export default function Subscribe() {
                        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
                      />
                    </svg>
-                    <span>Subscribing...</span>
+                    <span>{translator.t('pages.subscribe.buttonLoading')}</span>
                  </div>
                ) : (
-                  'Subscribe'
+                  translator.t('pages.subscribe.button')
                )}
              </Button>
            </div>
@@ -1,4 +1,5 @@
 import {Button, Card, CardContent} from '@plunk/ui';
+import {createTranslator, type Translator} from '@plunk/shared';
 import {AnimatePresence, motion} from 'framer-motion';
 import {useRouter} from 'next/router';
 import React, {useEffect, useState} from 'react';
@@ -9,6 +10,7 @@ interface ContactInfo {
  id: string;
  email: string;
  subscribed: boolean;
+  language: string;
 }

 export default function Unsubscribe() {
@@ -16,6 +18,7 @@ export default function Unsubscribe() {
  const {id} = router.query;

  const [contact, setContact] = useState<ContactInfo | null>(null);
+  const [translator, setTranslator] = useState<Translator | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [unsubscribing, setUnsubscribing] = useState(false);
@@ -29,6 +32,11 @@ export default function Unsubscribe() {
        setLoading(true);
        const data = await network.fetch<ContactInfo>('GET', `/contacts/public/${id}`);
        setContact(data);
+
+        // Load translations for the project's language
+        const t = await createTranslator(data.language || 'en');
+        setTranslator(t);
+
        setError(null);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Failed to load contact information');
@@ -56,7 +64,8 @@ export default function Unsubscribe() {
    }
  };

-  if (loading) {
+  // Don't render until translations are loaded
+  if (!translator) {
    return (
      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
        <div className={'flex flex-col gap-6 max-w-2xl w-full px-4'}>
@@ -85,6 +94,35 @@ export default function Unsubscribe() {
    );
  }

+  if (loading) {
+    return (
+      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
+        <div className={'flex flex-col gap-6 max-w-2xl w-full px-4'}>
+          <Card>
+            <CardContent className="p-8">
+              <div className="flex flex-col items-center gap-4">
+                <svg
+                  className="h-8 w-8 animate-spin text-neutral-500"
+                  xmlns="http://www.w3.org/2000/svg"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                >
+                  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                  <path
+                    className="opacity-75"
+                    fill="currentColor"
+                    d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                  />
+                </svg>
+                <p className="text-sm text-neutral-500">{translator.t('pages.common.loading')}</p>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      </div>
+    );
+  }
+
  if (error && !contact) {
    return (
      <div className={'h-screen flex items-center justify-center bg-neutral-50'}>
@@ -105,7 +143,7 @@ export default function Unsubscribe() {
                    <path d="M6 18L18 6M6 6l12 12" />
                  </svg>
                </div>
-                <h1 className="text-2xl font-bold text-neutral-900">Error</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.common.error')}</h1>
                <p className="text-neutral-500">{error}</p>
              </div>
            </CardContent>
@@ -140,17 +178,17 @@ export default function Unsubscribe() {
                    <path d="M5 13l4 4L19 7" />
                  </svg>
                </motion.div>
-                <h1 className="text-2xl font-bold text-neutral-900">You&apos;re unsubscribed</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.unsubscribe.successTitle')}</h1>
                <p className="text-neutral-500">
-                  {contact?.email} has been unsubscribed. You won&apos;t receive any more emails from us.
+                  {translator.t('pages.unsubscribe.successDescription', {email: contact?.email || ''})}
                </p>
                <p className="text-sm text-neutral-400 mt-2">
-                  Changed your mind?{' '}
+                  {translator.t('pages.unsubscribe.changedMind')}{' '}
                  <button
                    onClick={() => router.push(`/subscribe/${id as string}`)}
                    className="underline hover:text-neutral-600"
                  >
-                    Subscribe again
+                    {translator.t('pages.unsubscribe.subscribeAgain')}
                  </button>
                </p>
              </div>
@@ -168,10 +206,9 @@ export default function Unsubscribe() {
          <CardContent className="p-8">
            <div className="flex flex-col gap-6">
              <div className="flex flex-col items-center text-center gap-2">
-                <h1 className="text-2xl font-bold text-neutral-900">Unsubscribe</h1>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.unsubscribe.title')}</h1>
                <p className="text-neutral-500">
-                  We&apos;re sorry to see you go. Are you sure you want to unsubscribe <strong>{contact?.email}</strong>{' '}
-                  from receiving emails?
+                  {translator.t('pages.unsubscribe.description', {email: contact?.email || ''})}
                </p>
              </div>

@@ -210,14 +247,14 @@ export default function Unsubscribe() {
                          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
                        />
                      </svg>
-                      <span>Unsubscribing...</span>
+                      <span>{translator.t('pages.unsubscribe.buttonLoading')}</span>
                    </div>
                  ) : (
-                    'Unsubscribe'
+                    translator.t('pages.unsubscribe.button')
                  )}
                </Button>
                <Button variant="outline" className="w-full" onClick={() => router.push(`/manage/${id as string}`)}>
-                  Manage preferences instead
+                  {translator.t('pages.unsubscribe.managePreferences')}
                </Button>
              </div>
            </div>
@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "projects" ADD COLUMN     "language" TEXT NOT NULL DEFAULT 'en';
@@ -57,6 +57,9 @@ model Project {
  // Email Tracking
  tracking TrackingMode @default(ENABLED) // Open and click tracking mode

+  // Localization
+  language String @default("en") // Language code for customer-facing content (ISO 639-1)
+
  // Relations
  members     Membership[]
  contacts    Contact[]
@@ -0,0 +1,157 @@
+import type {Language} from './languages.js';
+// Static imports for all translation files
+import enTranslations from './locales/en.json' with {type: 'json'};
+import nlTranslations from './locales/nl.json' with {type: 'json'};
+
+export {
+  SUPPORTED_LANGUAGES,
+  DEFAULT_LANGUAGE,
+  isValidLanguageCode,
+  getLanguageByCode,
+  type Language,
+} from './languages.js';
+
+export type TranslationKey = string;
+
+export interface Translations {
+  pages: {
+    unsubscribe: Record<string, string>;
+    subscribe: Record<string, string>;
+    manage: Record<string, string>;
+    common: Record<string, string>;
+  };
+  email: {
+    footer: Record<string, string>;
+  };
+}
+
+// Static mapping of language codes to translations
+const translationsMap: Record<string, Translations> = {
+  en: enTranslations,
+  nl: nlTranslations,
+};
+
+// In-memory cache for loaded translations
+const translationCache = new Map<string, Translations>();
+
+/**
+ * Load translations for a given language code (async)
+ * Uses static imports for reliable resolution
+ */
+export async function loadTranslations(languageCode: string): Promise<Translations> {
+  // Check cache first
+  if (translationCache.has(languageCode)) {
+    return translationCache.get(languageCode)!;
+  }
+
+  // Get translations from static map
+  const translations = translationsMap[languageCode];
+
+  if (translations) {
+    translationCache.set(languageCode, translations);
+    return translations;
+  }
+
+  // Fallback to English if language not found
+  console.warn(`Translation file not found for ${languageCode}, falling back to English`);
+  if (languageCode !== 'en') {
+    return loadTranslations('en');
+  }
+
+  throw new Error(`Failed to load translations for ${languageCode}`);
+}
+
+/**
+ * Synchronous translation loader (requires pre-built translations)
+ * For API server use (compiled at build time)
+ */
+export function loadTranslationsSync(languageCode: string): Translations {
+  if (translationCache.has(languageCode)) {
+    return translationCache.get(languageCode)!;
+  }
+
+  // Get translations from static map
+  const translations = translationsMap[languageCode];
+
+  if (translations) {
+    translationCache.set(languageCode, translations);
+    return translations;
+  }
+
+  // Fallback to English if language not found
+  if (languageCode !== 'en') {
+    return loadTranslationsSync('en');
+  }
+
+  throw new Error(`Failed to load translations for ${languageCode}`);
+}
+
+/**
+ * Simple template string replacement
+ * Example: interpolate("Hello {name}", { name: "World" }) => "Hello World"
+ */
+export function interpolate(template: string, values: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (_, key) => values[key] || `{${key}}`);
+}
+
+/**
+ * Get nested translation value by dot notation path
+ * Example: getTranslation(translations, "pages.unsubscribe.title")
+ */
+export function getTranslation(translations: Translations, path: string): string {
+  const keys = path.split('.');
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let value: any = translations;
+
+  for (const key of keys) {
+    value = value?.[key];
+    if (value === undefined) {
+      console.warn(`Translation key not found: ${path}`);
+      return path; // Return the key itself as fallback
+    }
+  }
+
+  return typeof value === 'string' ? value : path;
+}
+
+/**
+ * Translation helper class for easier use
+ */
+export class Translator {
+  private translations: Translations;
+  private languageCode: string;
+
+  constructor(translations: Translations, languageCode: string) {
+    this.translations = translations;
+    this.languageCode = languageCode;
+  }
+
+  /**
+   * Translate a key with optional interpolation
+   * Example: t("pages.unsubscribe.description", { email: "user@example.com" })
+   */
+  t(key: string, values?: Record<string, string>): string {
+    const translation = getTranslation(this.translations, key);
+    return values ? interpolate(translation, values) : translation;
+  }
+
+  getLanguageCode(): string {
+    return this.languageCode;
+  }
+}
+
+/**
+ * Create a translator instance for a given language (async)
+ */
+export async function createTranslator(languageCode: string): Promise<Translator> {
+  const translations = await loadTranslations(languageCode);
+  return new Translator(translations, languageCode);
+}
+
+/**
+ * Create a translator instance for a given language (sync)
+ */
+export function createTranslatorSync(languageCode: string): Translator {
+  const translations = loadTranslationsSync(languageCode);
+  return new Translator(translations, languageCode);
+}
@@ -0,0 +1,21 @@
+export interface Language {
+  code: string;
+  name: string;
+  nativeName: string;
+  flag: string;
+}
+
+export const SUPPORTED_LANGUAGES: Language[] = [
+  {code: 'en', name: 'English', nativeName: 'English', flag: '🇺🇸'},
+  {code: 'nl', name: 'Dutch', nativeName: 'Nederlands', flag: '🇳🇱'},
+];
+
+export const DEFAULT_LANGUAGE = 'en';
+
+export function isValidLanguageCode(code: string): boolean {
+  return SUPPORTED_LANGUAGES.some(lang => lang.code === code);
+}
+
+export function getLanguageByCode(code: string): Language | undefined {
+  return SUPPORTED_LANGUAGES.find(lang => lang.code === code);
+}
@@ -0,0 +1,45 @@
+{
+  "pages": {
+    "unsubscribe": {
+      "title": "Unsubscribe",
+      "description": "We're sorry to see you go. Are you sure you want to unsubscribe {email} from receiving emails?",
+      "button": "Unsubscribe",
+      "buttonLoading": "Unsubscribing...",
+      "managePreferences": "Manage preferences instead",
+      "successTitle": "You're unsubscribed",
+      "successDescription": "{email} has been unsubscribed. You won't receive any more emails from us.",
+      "changedMind": "Changed your mind?",
+      "subscribeAgain": "Subscribe again"
+    },
+    "subscribe": {
+      "title": "Subscribe to updates",
+      "description": "Would you like to subscribe {email} to receive emails?",
+      "button": "Subscribe",
+      "buttonLoading": "Subscribing...",
+      "successTitle": "You're subscribed!",
+      "successDescription": "{email} is now subscribed to receive emails from us."
+    },
+    "manage": {
+      "title": "Manage Preferences",
+      "description": "Manage email preferences for {email}",
+      "subscriptionLabel": "Email Subscription",
+      "subscribedStatus": "You are currently subscribed to receive emails",
+      "unsubscribedStatus": "You are currently unsubscribed from emails",
+      "subscribedSuccess": "Subscribed successfully!",
+      "unsubscribedSuccess": "Unsubscribed successfully!",
+      "unsubscribeCompletely": "Unsubscribe completely",
+      "subscribeToEmails": "Subscribe to emails",
+      "disclaimer": "This page allows you to manage your email preferences. Your subscription status is updated in real-time."
+    },
+    "common": {
+      "loading": "Loading...",
+      "error": "Error"
+    }
+  },
+  "email": {
+    "footer": {
+      "unsubscribeText": "You received this email because you agreed to receive emails from {projectName}. If you no longer wish to receive emails like this, please",
+      "updatePreferences": "update your preferences"
+    }
+  }
+}
@@ -0,0 +1,45 @@
+{
+  "pages": {
+    "unsubscribe": {
+      "title": "Afmelden",
+      "description": "Het spijt ons dat je vertrekt. Weet je zeker dat je {email} wilt afmelden voor het ontvangen van e-mails?",
+      "button": "Afmelden",
+      "buttonLoading": "Bezig met afmelden...",
+      "managePreferences": "Beheer in plaats daarvan voorkeuren",
+      "successTitle": "Je bent afgemeld",
+      "successDescription": "{email} is afgemeld. Je ontvangt geen e-mails meer van ons.",
+      "changedMind": "Van gedachten veranderd?",
+      "subscribeAgain": "Opnieuw aanmelden"
+    },
+    "subscribe": {
+      "title": "Aanmelden voor updates",
+      "description": "Wil je {email} aanmelden om e-mails te ontvangen?",
+      "button": "Aanmelden",
+      "buttonLoading": "Bezig met aanmelden...",
+      "successTitle": "Je bent aangemeld!",
+      "successDescription": "{email} is nu aangemeld om e-mails van ons te ontvangen."
+    },
+    "manage": {
+      "title": "Voorkeuren beheren",
+      "description": "Beheer e-mailvoorkeuren voor {email}",
+      "subscriptionLabel": "E-mailabonnement",
+      "subscribedStatus": "Je bent momenteel aangemeld om e-mails te ontvangen",
+      "unsubscribedStatus": "Je bent momenteel afgemeld voor e-mails",
+      "subscribedSuccess": "Succesvol aangemeld!",
+      "unsubscribedSuccess": "Succesvol afgemeld!",
+      "unsubscribeCompletely": "Volledig afmelden",
+      "subscribeToEmails": "Aanmelden voor e-mails",
+      "disclaimer": "Op deze pagina kun je je e-mailvoorkeuren beheren. Je abonnementsstatus wordt in realtime bijgewerkt."
+    },
+    "common": {
+      "loading": "Bezig met laden...",
+      "error": "Fout"
+    }
+  },
+  "email": {
+    "footer": {
+      "unsubscribeText": "Je ontvangt deze e-mail omdat je hebt ingestemd met het ontvangen van e-mails van {projectName}. Als je deze e-mails niet meer wilt ontvangen,",
+      "updatePreferences": "werk je voorkeuren bij"
+    }
+  }
+}
@@ -1,3 +1,4 @@
 export * from './schemas/index.js';
 export * from './operators.js';
 export * from './template.js';
+export * from './i18n/index.js';
@@ -67,6 +67,7 @@ export const ProjectSchemas = {
  update: z.object({
    name: z.string().min(1).max(100).optional(),
    tracking: z.nativeEnum(TrackingMode).optional(),
+    language: z.string().length(2).regex(/^[a-z]{2}$/).optional(),
  }),
 } as const;