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

apps/api/src/controllers/Contacts.ts

@@ -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',
     });
   }
 

apps/api/src/services/ContactService.ts

@@ -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
    */

apps/api/src/services/EmailService.ts

@@ -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
+                  ${unsubscribeText}
-                  <a href="${DASHBOARD_URI}/unsubscribe/${contact.id}">update your preferences</a>.
+                  <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)

apps/web/src/pages/manage/[id].tsx

@@ -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'
+                        ? translator.t('pages.manage.subscribedStatus')
-                        : 'You are currently unsubscribed from emails'}
+                        : 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>
+                <p>{translator.t('pages.manage.disclaimer')}</p>
-                  This page allows you to manage your email preferences. Your subscription status is updated in
-                  real-time.
-                </p>
               </div>
             </div>
           </CardContent>

apps/web/src/pages/settings/index.tsx

@@ -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'}

apps/web/src/pages/subscribe/[id].tsx

@@ -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>
+                <h1 className="text-2xl font-bold text-neutral-900">{translator.t('pages.subscribe.successTitle')}</h1>
-                <p className="text-neutral-500">{contact?.email} is now subscribed to receive emails from us.</p>
+                <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>

apps/web/src/pages/unsubscribe/[id].tsx

@@ -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>{' '}
+                  {translator.t('pages.unsubscribe.description', {email: contact?.email || ''})}
-                  from receiving emails?
                 </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>

packages/db/prisma/migrations/20251221114634_add_language_to_project/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "projects" ADD COLUMN     "language" TEXT NOT NULL DEFAULT 'en';

packages/db/prisma/schema.prisma

@@ -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[]

packages/shared/src/i18n/index.ts

@@ -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: "[email protected]" })
+   */
+  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);
+}

packages/shared/src/i18n/languages.ts

@@ -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);
+}

packages/shared/src/i18n/locales/en.json

@@ -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"
+    }
+  }
+}

packages/shared/src/i18n/locales/nl.json

@@ -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"
+    }
+  }
+}

packages/shared/src/index.ts

@@ -1,3 +1,4 @@
 export * from './schemas/index.js';
 export * from './operators.js';
 export * from './template.js';
+export * from './i18n/index.js';

packages/shared/src/schemas/index.ts

@@ -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;