add server export

Author: alexcarpenter

packages/i18n/src/create-i18n/index.ts

@@ -160,7 +160,13 @@ export function createI18n($locale: ReadableStore<string>, options: CreateI18nOp
   ): Messages<B> {
     const out: Record<string, unknown> = {};
     for (const key in base) {
-      out[key] = buildEntry(locale, base[key], overridesForNamespace?.[key]);
+      const baseVal = base[key];
+      const override = overridesForNamespace?.[key];
+      if (typeof baseVal === 'object' && baseVal !== null && !asMarker(baseVal)) {
+        out[key] = buildMessages(locale, baseVal as Record<string, unknown>, override as Overrides | undefined);
+      } else {
+        out[key] = buildEntry(locale, baseVal, override);
+      }
     }
     return out as Messages<B>;
   }

packages/ui/src/mosaic/__tests__/i18n-server.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { getLocalization } from '../i18n/server';
+
+describe('getLocalization', () => {
+  it('returns the default locale with no messages when acceptLanguage is null', async () => {
+    const result = await getLocalization(null);
+    expect(result).toEqual({ locale: 'en', initialMessages: {} });
+  });
+
+  it('matches the default locale via base tag (en-US → en)', async () => {
+    const result = await getLocalization('en-US');
+    expect(result).toEqual({ locale: 'en', initialMessages: {} });
+  });
+
+  it('picks the highest-priority match (en-US,fr → en, not fr)', async () => {
+    const result = await getLocalization('en-US,fr;q=0.9');
+    expect(result.locale).toBe('en');
+  });
+
+  it('loads french messages when locale is fr', async () => {
+    const result = await getLocalization('fr');
+    expect(result.locale).toBe('fr');
+    expect(result.initialMessages).toHaveProperty('fr');
+    expect(result.initialMessages.fr).toBeTruthy();
+  });
+
+  it('matches a supported locale via base tag (fr-FR → fr)', async () => {
+    const result = await getLocalization('fr-FR');
+    expect(result.locale).toBe('fr');
+  });
+
+  it('falls back to the default locale for an unsupported language', async () => {
+    const result = await getLocalization('de');
+    expect(result).toEqual({ locale: 'en', initialMessages: {} });
+  });
+});

packages/ui/src/mosaic/__tests__/localization-provider.test.tsx

@@ -0,0 +1,31 @@
+import { renderHook } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import frMessages from '../locales/fr.json';
+import { MosaicProvider } from '../providers/mosaic-provider';
+import { useMessages } from '../providers/localization-provider';
+
+const base = { title: 'Organization Profile', tab: { general: 'General', members: 'Members' } };
+
+describe('LocalizationProvider overrides', () => {
+  it('override wins over French translation when both locale and overrides are set', () => {
+    const { result } = renderHook(() => useMessages('organizationProfile', base), {
+      wrapper: ({ children }) =>
+        React.createElement(
+          MosaicProvider,
+          {
+            localization: {
+              locale: 'fr',
+              initialMessages: { fr: frMessages },
+              overrides: { 'organizationProfile.title': 'test' },
+            },
+          },
+          children,
+        ),
+    });
+    expect(result.current.title).toBe('test');
+    // Non-overridden key still resolves from the French bundle
+    expect((result.current.tab as Record<string, unknown>).general).toBe('Général');
+  });
+});

packages/ui/src/mosaic/i18n/server.ts

@@ -0,0 +1,40 @@
+// Locale bundles shipped by @clerk/ui. Add an entry here as each locale lands.
+const LOADERS: Record<string, () => Promise<{ default: Record<string, Record<string, unknown>> }>> = {
+  fr: () => import('../locales/fr.json'),
+};
+
+const DEFAULT_LOCALE = 'en';
+
+function negotiate(acceptLanguage: string | null): string {
+  if (!acceptLanguage) return DEFAULT_LOCALE;
+  const available = new Set([...Object.keys(LOADERS), DEFAULT_LOCALE]);
+  for (const entry of acceptLanguage.split(',')) {
+    const lang = entry.split(';')[0].trim();
+    for (const candidate of [lang, lang.split('-')[0]]) {
+      if (available.has(candidate)) return candidate;
+    }
+  }
+  return DEFAULT_LOCALE;
+}
+
+export type Localization = {
+  locale: string;
+  initialMessages: Record<string, Record<string, Record<string, unknown>>>;
+};
+
+/**
+ * Resolve a locale and pre-load its message bundle from the Accept-Language header.
+ * Drop the result straight into <MosaicProvider localization={...} />.
+ *
+ * Works in any server environment — pass whatever string your framework exposes:
+ *   Next.js:  getLocalization((await headers()).get('accept-language'))
+ *   Remix:    getLocalization(request.headers.get('accept-language'))
+ *   Express:  getLocalization(req.get('accept-language') ?? null)
+ */
+export async function getLocalization(acceptLanguage: string | null): Promise<Localization> {
+  const locale = negotiate(acceptLanguage);
+  const loader = LOADERS[locale];
+  if (!loader) return { locale, initialMessages: {} };
+  const messages = (await loader()).default;
+  return { locale, initialMessages: { [locale]: messages } };
+}

packages/ui/src/mosaic/locales/fr.json

@@ -0,0 +1,10 @@
+{
+  "organizationProfile": {
+    "title": "Profil de l'organisation",
+    "tab": {
+      "general": "Général",
+      "members": "Membres"
+    },
+    "membersContent": "Contenu des membres"
+  }
+}

packages/ui/src/mosaic/providers/localization-provider.tsx

@@ -1,13 +1,14 @@
 import { atom, browser, createI18n, defineLocalization, localeFrom } from '@clerk/i18n';
 import { useStore } from '@clerk/i18n/react';
 import { createContextAndHook } from '@clerk/shared/react';
-import React, { useMemo } from 'react';
+import React, { useMemo, useRef } from 'react';
 
 import type { FlatOverrides, I18n, NestedOverrides, Registry, ResolvedOverrides, WritableStore } from '@clerk/i18n';
 
 interface LocalizationValue {
   i18n: I18n;
   $locale: WritableStore<string | null>;
+  $overrides: WritableStore<ResolvedOverrides>;
 }
 
 const [LocalizationCtx, useLocalization] = createContextAndHook<LocalizationValue>('LocalizationContext');
@@ -38,16 +39,34 @@ export function LocalizationProvider<R extends Registry = Registry>({
   // Seed $explicit so the first render is correct; no useEffect needed.
   const value = useMemo(() => {
     const $explicit = atom<string | null>(locale ?? null);
+    const $overrides = atom<ResolvedOverrides>(
+      overrides ? defineLocalization(overrides as NestedOverrides<Registry>) : {},
+    );
     const $locale = localeFrom($explicit, browser({ available: locales, fallback: defaultLocale }));
     const i18n = createI18n($locale, {
       get: () => Promise.resolve({}),
-      overrides: atom<ResolvedOverrides>(overrides ? defineLocalization(overrides as NestedOverrides<Registry>) : {}),
+      overrides: $overrides,
       cache: initialMessages,
     });
-    return { i18n, $locale: $explicit };
+    return { i18n, $locale: $explicit, $overrides };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Sync controlled props → atoms during render (derived-state pattern, no effect needed).
+  // locale: primitive comparison against atom's current value is sufficient.
+  const nextLocale = locale ?? null;
+  if (value.$locale.get() !== nextLocale) {
+    value.$locale.set(nextLocale);
+  }
+
+  // overrides: defineLocalization() returns a new object every call, so compare
+  // the prop reference — not the resolved value — to avoid spurious updates.
+  const prevOverridesRef = useRef(overrides);
+  if (prevOverridesRef.current !== overrides) {
+    prevOverridesRef.current = overrides;
+    value.$overrides.set(overrides ? defineLocalization(overrides as NestedOverrides<Registry>) : {});
+  }
+
   return <LocalizationCtx.Provider value={{ value }}>{children}</LocalizationCtx.Provider>;
 }