Internationalization & Localization Research¶

// Add to the User model
model User {
  // ... existing fields ...

  // i18n preferences (null = inherit from tenant)
  locale            String?   // BCP 47 language tag: "en", "nl", "fr", "de"
  timezone          String?   // IANA timezone: "Europe/Brussels", "America/New_York"
  dateFormat        String?   // "DD/MM/YYYY", "MM/DD/YYYY", "YYYY-MM-DD"
  timeFormat        String?   // "24h", "12h"
  measurementSystem String?   // "metric", "imperial"
  firstDayOfWeek    Int?      // 0 = Sunday, 1 = Monday
}

// Add to the Tenant model
model Tenant {
  // ... existing fields ...

  // i18n defaults for all users in this tenant
  defaultLocale            String  @default("en")
  defaultTimezone          String  @default("UTC")
  defaultDateFormat        String  @default("DD/MM/YYYY")
  defaultTimeFormat        String  @default("24h")
  defaultMeasurementSystem String  @default("metric")
  defaultFirstDayOfWeek    Int     @default(1)  // Monday for EU
}

User preference (if set)
  └── Tenant default (if set)
        └── System default (English, UTC, metric, DD/MM/YYYY, 24h, Monday)

// GET /api/v1/users/me/preferences
interface UserPreferences {
  locale: string;            // resolved value
  timezone: string;          // resolved value
  dateFormat: string;        // resolved value
  timeFormat: string;        // resolved value
  measurementSystem: string; // resolved value
  firstDayOfWeek: number;    // resolved value
  source: {
    locale: 'user' | 'tenant' | 'system';
    timezone: 'user' | 'tenant' | 'system';
    dateFormat: 'user' | 'tenant' | 'system';
    timeFormat: 'user' | 'tenant' | 'system';
    measurementSystem: 'user' | 'tenant' | 'system';
    firstDayOfWeek: 'user' | 'tenant' | 'system';
  };
}

// PATCH /api/v1/users/me/preferences
interface UpdateUserPreferences {
  locale?: string | null;            // null = reset to tenant default
  timezone?: string | null;
  dateFormat?: string | null;
  timeFormat?: string | null;
  measurementSystem?: string | null;
  firstDayOfWeek?: number | null;
}

// PATCH /api/v1/tenants/:id/defaults (admin only)
interface UpdateTenantDefaults {
  defaultLocale?: string;
  defaultTimezone?: string;
  defaultDateFormat?: string;
  defaultTimeFormat?: string;
  defaultMeasurementSystem?: string;
  defaultFirstDayOfWeek?: number;
}

apps/web/
├── src/
│   ├── i18n/
│   │   ├── index.ts              # i18next initialization
│   │   ├── locales/
│   │   │   ├── en/
│   │   │   │   ├── common.json   # shared strings (buttons, labels, nav)
│   │   │   │   ├── dashboard.json
│   │   │   │   ├── orders.json
│   │   │   │   ├── settings.json
│   │   │   │   ├── errors.json
│   │   │   │   └── ...
│   │   │   ├── nl/
│   │   │   │   ├── common.json
│   │   │   │   ├── dashboard.json
│   │   │   │   └── ...
│   │   │   └── fr/
│   │   │       └── ...
│   │   └── types.ts              # typed translation keys
│   ├── contexts/
│   │   └── locale-context.tsx    # locale state + preference resolution
│   └── hooks/
│       ├── use-locale.ts         # access resolved locale preferences
│       ├── use-format-date.ts    # locale-aware date formatting
│       ├── use-format-number.ts  # locale-aware number formatting
│       └── use-measurement.ts    # metric/imperial conversion

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'nl', 'fr', 'de'],
    ns: ['common', 'dashboard', 'orders', 'settings', 'errors'],
    defaultNS: 'common',
    detection: {
      order: ['localStorage', 'navigator'],
      lookupLocalStorage: 'forma3d-locale',
    },
    interpolation: {
      escapeValue: false,
    },
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
    },
    react: {
      useSuspense: true,
    },
  });

// Before (hardcoded)
<h1>Orders</h1>
<p>No orders found</p>
<button>Create Order</button>

// After (i18n)
import { useTranslation } from 'react-i18next';

function OrdersPage() {
  const { t } = useTranslation('orders');

  return (
    <>
      <h1>{t('title')}</h1>
      <p>{t('empty_state')}</p>
      <button>{t('create_button')}</button>
    </>
  );
}

{
  "order_count": "{count, plural, =0 {No orders} one {# order} other {# orders}}"
}

<p>{t('order_count', { count: orders.length })}</p>

// use-format-date.ts
import { useLocale } from './use-locale';

export function useFormatDate() {
  const { timezone, dateFormat, timeFormat, locale } = useLocale();

  const formatDate = (date: string | Date): string => {
    const d = typeof date === 'string' ? new Date(date) : date;
    return new Intl.DateTimeFormat(locale, {
      timeZone: timezone,
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
    }).format(d);
  };

  const formatDateTime = (date: string | Date): string => {
    const d = typeof date === 'string' ? new Date(date) : date;
    return new Intl.DateTimeFormat(locale, {
      timeZone: timezone,
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
      hour: '2-digit',
      minute: '2-digit',
      hour12: timeFormat === '12h',
    }).format(d);
  };

  const formatRelativeTime = (date: string | Date): string => {
    const d = typeof date === 'string' ? new Date(date) : date;
    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
    const diffMs = d.getTime() - Date.now();
    const diffMinutes = Math.round(diffMs / 60000);
    const diffHours = Math.round(diffMs / 3600000);
    const diffDays = Math.round(diffMs / 86400000);

    if (Math.abs(diffMinutes) < 60) return rtf.format(diffMinutes, 'minute');
    if (Math.abs(diffHours) < 24) return rtf.format(diffHours, 'hour');
    return rtf.format(diffDays, 'day');
  };

  return { formatDate, formatDateTime, formatRelativeTime };
}

// use-measurement.ts
import { useLocale } from './use-locale';

const MM_PER_INCH = 25.4;
const CM_PER_INCH = 2.54;

export function useMeasurement() {
  const { measurementSystem } = useLocale();
  const isMetric = measurementSystem === 'metric';

  const formatLength = (valueMm: number): string => {
    if (isMetric) {
      return valueMm >= 10
        ? `${(valueMm / 10).toFixed(1)} cm`
        : `${valueMm.toFixed(1)} mm`;
    }
    return `${(valueMm / MM_PER_INCH).toFixed(2)} in`;
  };

  const formatWeight = (valueGrams: number): string => {
    if (isMetric) {
      return valueGrams >= 1000
        ? `${(valueGrams / 1000).toFixed(2)} kg`
        : `${valueGrams.toFixed(0)} g`;
    }
    return `${(valueGrams / 28.3495).toFixed(2)} oz`;
  };

  const toMm = (value: number, unit: 'mm' | 'cm' | 'in'): number => {
    switch (unit) {
      case 'cm': return value * 10;
      case 'in': return value * MM_PER_INCH;
      default: return value;
    }
  };

  return { formatLength, formatWeight, toMm, isMetric };
}

interface LocaleContextValue {
  locale: string;
  timezone: string;
  dateFormat: string;
  timeFormat: string;
  measurementSystem: 'metric' | 'imperial';
  firstDayOfWeek: number;
  updatePreference: (key: string, value: string | number | null) => Promise<void>;
}

// Backend returns structured errors with i18n keys
{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "errors.order.invalid_quantity",
  "params": { "min": 1, "max": 999 }
}

// Frontend resolves:
// errors.json: { "order": { "invalid_quantity": "Quantity must be between {min} and {max}" } }
// errors.json (nl): { "order": { "invalid_quantity": "Aantal moet tussen {min} en {max} zijn" } }

apps/api/src/
├── i18n/
│   ├── locales/
│   │   ├── en.json
│   │   ├── nl.json
│   │   └── fr.json
│   └── i18n.service.ts
├── email/
│   ├── templates/
│   │   ├── order-confirmation/
│   │   │   ├── en.hbs
│   │   │   ├── nl.hbs
│   │   │   └── fr.hbs
│   │   └── shipping-notification/
│   │       ├── en.hbs
│   │       ├── nl.hbs
│   │       └── fr.hbs
│   └── email.service.ts

@Injectable()
export class LocaleMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    // Priority: 1) User DB preference, 2) Accept-Language header, 3) Tenant default, 4) 'en'
    const userLocale = req.user?.locale;
    const tenantLocale = req.tenant?.defaultLocale;
    const headerLocale = req.headers['accept-language']?.split(',')[0]?.split('-')[0];

    req.resolvedLocale = userLocale ?? headerLocale ?? tenantLocale ?? 'en';
    req.resolvedTimezone = req.user?.timezone ?? req.tenant?.defaultTimezone ?? 'UTC';
    next();
  }
}

{namespace}.{feature}.{element}_{qualifier}

Examples:
  common.button.save             → "Save"
  common.button.cancel           → "Cancel"
  orders.list.title              → "Orders"
  orders.list.empty_state        → "No orders yet"
  orders.detail.status_label     → "Status"
  orders.detail.items_count      → "{count, plural, one {# item} other {# items}}"
  settings.locale.timezone_label → "Timezone"
  errors.validation.required     → "This field is required"
  errors.order.not_found         → "Order not found"

Recipient's user.locale preference
  └── Tenant's defaultLocale
        └── "en" (system fallback)

// Resolve push notification text in user's language
const title = i18nService.t('notifications.order_received.title', {
  lng: user.locale ?? tenant.defaultLocale ?? 'en',
  orderNumber: order.shopifyOrderNumber,
});

{
  "order": {
    "createdAt": "2026-03-10T14:30:00.000Z",
    "total": 149.99,
    "currency": "EUR",
    "items": [
      {
        "name": "Custom Drawer Organizer",
        "widthMm": 200,
        "depthMm": 150,
        "heightMm": 50,
        "weightG": 120
      }
    ]
  }
}