@byline/host-tanstack-start 2.5.2 → 2.6.0

package/src/admin-shell/collections/resolve-preview-url.test.node.ts

@@ -0,0 +1,167 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Tests for the preview-URL resolver's three-level cascade:
+ *
+ *   1. `adminConfig.preview.url`       — wins outright
+ *   2. `definition.buildDocumentPath`  — schema-side fallback
+ *   3. Generic `/${collectionPath}/${path}` — last-resort compose
+ *
+ * Also covers the branch-A posture (hook throws → fall through) and the
+ * "missing path means hide affordance" contract.
+ */
+
+import {
+  type CollectionAdminConfig,
+  type CollectionDefinition,
+  defineServerConfig,
+  type PreviewDocument,
+} from '@byline/core'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { resolvePreviewUrl } from './resolve-preview-url.js'
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+function clearConfig(): void {
+  ;(globalThis as any)[Symbol.for('__byline_server_config__')] = null
+  ;(globalThis as any)[Symbol.for('__byline_client_config__')] = null
+}
+
+function registerCollection(definition: Partial<CollectionDefinition> & { path: string }): void {
+  defineServerConfig({
+    collections: [
+      {
+        labels: { singular: 'Page', plural: 'Pages' },
+        fields: [{ name: 'title', type: 'text', label: 'Title' }],
+        useAsTitle: 'title',
+        ...definition,
+      } as CollectionDefinition,
+    ],
+  } as Parameters<typeof defineServerConfig>[0])
+}
+
+const doc: PreviewDocument = {
+  id: 'doc-1',
+  path: 'about',
+  status: 'published',
+  fields: { title: 'About' },
+}
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe('resolvePreviewUrl', () => {
+  beforeEach(clearConfig)
+  afterEach(clearConfig)
+
+  // -------------------------------------------------------------------------
+  // Tier 1 — adminConfig.preview.url
+  // -------------------------------------------------------------------------
+
+  describe('adminConfig.preview.url', () => {
+    it('takes precedence over the schema hook', () => {
+      registerCollection({
+        path: 'pages',
+        buildDocumentPath: () => '/schema-path',
+      })
+      const adminConfig = {
+        preview: { url: () => '/from-admin' },
+      } as unknown as CollectionAdminConfig
+      expect(resolvePreviewUrl(doc, 'pages', adminConfig, undefined)).toBe('/from-admin')
+    })
+
+    it('forwards the locale to the configured url builder', () => {
+      const calls: Array<{ locale: string | undefined }> = []
+      const adminConfig = {
+        preview: {
+          url: (_d: PreviewDocument, ctx: { locale?: string }) => {
+            calls.push({ locale: ctx.locale })
+            return '/anything'
+          },
+        },
+      } as unknown as CollectionAdminConfig
+      resolvePreviewUrl(doc, 'pages', adminConfig, 'fr')
+      expect(calls).toEqual([{ locale: 'fr' }])
+    })
+
+    it('returns null when the configured url builder returns null', () => {
+      const adminConfig = {
+        preview: { url: () => null },
+      } as unknown as CollectionAdminConfig
+      expect(resolvePreviewUrl(doc, 'pages', adminConfig, undefined)).toBeNull()
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // Tier 2 — schema-side buildDocumentPath
+  // -------------------------------------------------------------------------
+
+  describe('buildDocumentPath fallback', () => {
+    it('uses the schema hook when no adminConfig.preview is set', () => {
+      registerCollection({
+        path: 'pages',
+        buildDocumentPath: (d) => `/marketing/${d.path}`,
+      })
+      expect(resolvePreviewUrl(doc, 'pages', undefined, undefined)).toBe('/marketing/about')
+    })
+
+    it('passes through null to hide the preview affordance', () => {
+      registerCollection({
+        path: 'pages',
+        buildDocumentPath: () => null,
+      })
+      expect(resolvePreviewUrl(doc, 'pages', undefined, undefined)).toBeNull()
+    })
+
+    it('falls through to generic compose when the hook throws (branch-A posture)', () => {
+      registerCollection({
+        path: 'pages',
+        buildDocumentPath: () => {
+          throw new Error('boom')
+        },
+      })
+      expect(resolvePreviewUrl(doc, 'pages', undefined, undefined)).toBe('/pages/about')
+    })
+
+    it('falls through to generic compose when the hook returns a non-string non-null', () => {
+      registerCollection({
+        path: 'pages',
+        // @ts-expect-error — exercising defensive handling of malformed return values
+        buildDocumentPath: () => 42,
+      })
+      expect(resolvePreviewUrl(doc, 'pages', undefined, undefined)).toBe('/pages/about')
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // Tier 3 — generic compose
+  // -------------------------------------------------------------------------
+
+  describe('generic compose', () => {
+    it('uses /${collectionPath}/${path} when no schema hook is defined', () => {
+      registerCollection({ path: 'pages' })
+      expect(resolvePreviewUrl(doc, 'pages', undefined, undefined)).toBe('/pages/about')
+    })
+
+    it('works without any registered collection (fully unconfigured host)', () => {
+      // No registerCollection — getCollectionDefinition returns null,
+      // the cascade falls straight through to the generic compose.
+      expect(resolvePreviewUrl(doc, 'pages', undefined, undefined)).toBe('/pages/about')
+    })
+
+    it('returns null when the doc has no path yet', () => {
+      registerCollection({ path: 'pages' })
+      expect(resolvePreviewUrl({ ...doc, path: '' }, 'pages', undefined, undefined)).toBeNull()
+    })
+  })
+})

package/src/admin-shell/collections/resolve-preview-url.ts

@@ -0,0 +1,67 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Pure (no React, no DOM) resolver for the admin Preview button's URL.
+ * Lives in its own module so it can be unit-tested without dragging the
+ * React UI graph of `preview-link.tsx` into a node-mode test run.
+ */
+
+import {
+  type CollectionAdminConfig,
+  getCollectionDefinition,
+  type PreviewDocument,
+} from '@byline/core'
+
+/**
+ * Resolve the preview URL for a doc against an admin config. Exported so
+ * other surfaces (list-row preview links in the future) can share the
+ * same fallback logic.
+ *
+ * Cascade:
+ *   1. `adminConfig.preview.url(doc, { locale })` — wins outright when
+ *      configured. The host can do anything (locale prefix, query
+ *      string, conditional return-null).
+ *   2. `CollectionDefinition.buildDocumentPath(doc, { collectionPath })`
+ *      — the schema-side hook the richtext embed walker also reads.
+ *      Locale-agnostic by contract; hosts that need a locale prefix
+ *      keep their own `preview.url`.
+ *   3. Generic compose `/${collectionPath}/${doc.path}` — last-resort
+ *      convention for collections with no schema-side hook.
+ *
+ * Returns:
+ *   - `string`  → URL to open
+ *   - `null`    → no preview URL meaningful for this doc; hide affordance
+ */
+export function resolvePreviewUrl(
+  doc: PreviewDocument,
+  collectionPath: string,
+  adminConfig: CollectionAdminConfig | undefined,
+  locale: string | undefined
+): string | null {
+  if (adminConfig?.preview) {
+    return adminConfig.preview.url(doc, { locale })
+  }
+  // Schema-side default — same hook the richtext embed walker reads, so
+  // the public path and the admin Preview button agree by construction.
+  const definition = getCollectionDefinition(collectionPath)
+  if (definition?.buildDocumentPath != null) {
+    try {
+      const built = definition.buildDocumentPath(doc, { collectionPath })
+      if (typeof built === 'string') return built
+      if (built === null) return null
+    } catch {
+      // Fall through to generic compose — matches the embed walker's
+      // branch-A posture (don't take the render path down with the hook).
+    }
+  }
+  // Generic compose: collection lives at `/${collectionPath}/${path}`.
+  // Returns null when the doc has no path yet (unsaved, awaiting slug).
+  if (!doc.path) return null
+  return `/${collectionPath}/${doc.path}`
+}

package/src/admin-shell/collections/restore-version-modal.tsx

@@ -20,6 +20,7 @@
 import { useState } from 'react'
 import { useRouter } from '@tanstack/react-router'
 
+import { useTranslation } from '@byline/i18n/react'
 import { Alert, Button, LoaderEllipsis, Modal } from '@byline/ui/react'
 import cx from 'classnames'
 
@@ -46,6 +47,7 @@ export function RestoreVersionModal({
 }: RestoreVersionModalProps) {
   const navigate = useNavigate()
   const router = useRouter()
+  const { t } = useTranslation('byline-admin')
   const [error, setError] = useState<string | null>(null)
   const [pending, setPending] = useState(false)
 
@@ -66,13 +68,13 @@ export function RestoreVersionModal({
     } catch (err) {
       const code = getErrorCode(err)
       if (code === 'ERR_INVALID_TRANSITION') {
-        setError('This version is already the current version of the document.')
+        setError(t('collections.restore.errors.alreadyCurrent'))
       } else if (code === 'ERR_NOT_FOUND') {
-        setError('The selected version could not be found. The history may be out of date.')
+        setError(t('collections.restore.errors.notFound'))
       } else if (code === 'ERR_FORBIDDEN' || code === 'ERR_UNAUTHENTICATED') {
-        setError('You do not have permission to restore versions for this collection.')
+        setError(t('collections.restore.errors.forbidden'))
       } else {
-        setError('Could not restore this version. Please try again.')
+        setError(t('collections.restore.errors.fallback'))
       }
       setPending(false)
     }
@@ -87,16 +89,13 @@ export function RestoreVersionModal({
           </Alert>
         ) : null}
         <p className={cx('byline-coll-restore-row', styles.row)}>
-          <span className="muted">Version:</span> {versionNumber}
+          <span className="muted">{t('collections.restore.versionLabel')}</span> {versionNumber}
         </p>
         <p className={cx('byline-coll-restore-row', styles.row)}>
-          <span className="muted">Created:</span> {versionLabel}
+          <span className="muted">{t('collections.restore.createdLabel')}</span> {versionLabel}
         </p>
         <p className={cx('byline-coll-restore-warning', styles.warning)}>
-          This will create a new draft version of this document with the content from version{' '}
-          {versionNumber}, and that draft will become the current version. The existing versions
-          (including any published version) are preserved in history. The restored draft will need
-          to be published through the normal workflow.
+          {t('collections.restore.warning', { version: versionNumber })}
         </p>
       </div>
       <div className={cx('byline-coll-restore-actions', styles.actions)}>
@@ -117,7 +116,7 @@ export function RestoreVersionModal({
           disabled={pending}
           className={cx('byline-coll-restore-button', styles.button)}
         >
-          Cancel
+          {t('common.actions.cancel')}
         </Button>
         <Button
           size="sm"
@@ -127,7 +126,7 @@ export function RestoreVersionModal({
           disabled={pending}
           className={cx('byline-coll-restore-button', styles.button)}
         >
-          {pending === true ? <LoaderEllipsis size={42} /> : 'Restore as Draft'}
+          {pending === true ? <LoaderEllipsis size={42} /> : t('collections.restore.confirmButton')}
         </Button>
       </div>
     </Modal.Content>

package/src/admin-shell/collections/tanstack-navigation-guard.ts

@@ -16,7 +16,7 @@
 import { useCallback } from 'react'
 import { useBlocker } from '@tanstack/react-router'
 
-import type { NavigationGuardResult, UseNavigationGuard } from '@byline/ui/react'
+import type { NavigationGuardResult, UseNavigationGuard } from '@byline/admin/react'
 
 /**
  * Navigation guard backed by TanStack Router's `useBlocker`.

package/src/admin-shell/collections/view-menu.tsx

@@ -9,6 +9,7 @@
 import { useEffect } from 'react'
 
 import type { CollectionAdminConfig, PreviewDocument } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
 import { Button, HistoryIcon, IconButton, Label, Select } from '@byline/ui/react'
 import cx from 'classnames'
 
@@ -78,6 +79,7 @@ export const ViewMenu = ({
   doc?: PreviewDocument
 }) => {
   const navigate = useNavigate()
+  const { t } = useTranslation('byline-admin')
 
   // Edit view must never use 'all' locale — strip it from the URL and fall
   // back to the default locale if it somehow arrives via navigation.
@@ -142,7 +144,7 @@ export const ViewMenu = ({
         className={cx('muted byline-view-menu-label', styles.label)}
         id="contentLocaleLabel"
         htmlFor="contentLocale"
-        label="Content Locale:"
+        label={t('collections.viewMenu.contentLocaleLabel')}
       />
       <Select<string>
         name="contentLocale"
@@ -152,7 +154,9 @@ export const ViewMenu = ({
         variant="outlined"
         value={locale ?? defaultContentLocale}
         items={[
-          ...(activeView !== 'edit' ? [{ value: 'all', label: 'All' }] : []),
+          ...(activeView !== 'edit'
+            ? [{ value: 'all', label: t('collections.viewMenu.localeAll') }]
+            : []),
           ...contentLocales.map((loc) => ({ value: loc.code, label: loc.label })),
         ]}
         onValueChange={handleLocaleChange}
@@ -163,7 +167,7 @@ export const ViewMenu = ({
             className={cx('muted byline-view-menu-label', styles.label)}
             id="populateDepthLabel"
             htmlFor="populateDepth"
-            label="Depth:"
+            label={t('collections.viewMenu.depthLabel')}
           />
           <Select<string>
             name="populateDepth"
@@ -217,7 +221,7 @@ export const ViewMenu = ({
           })
         }
       >
-        Edit
+        {t('common.actions.edit')}
       </Button>
       <Button
         size="xs"
@@ -231,7 +235,7 @@ export const ViewMenu = ({
           })
         }
       >
-        API
+        {t('collections.viewMenu.apiButton')}
       </Button>
     </div>
   )

package/src/i18n/index.ts

@@ -0,0 +1,26 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `@byline/host-tanstack-start/i18n` — host-side glue between the
+ * admin interface translation registry and TanStack Start's request
+ * model. Cookie helpers, the per-request locale resolver, and the
+ * server-side `resolveServerTranslator` companion to the client
+ * `useTranslation` hook.
+ */
+
+export {
+  ADMIN_LOCALE_COOKIE,
+  clearAdminLocaleCookie,
+  readAdminLocaleCookie,
+  setAdminLocaleCookie,
+} from './locale-cookie.js'
+export { buildLocaleDefinitions } from './locale-definitions.js'
+export { resolveRequestLocale } from './resolve-locale.js'
+export { resolveServerTranslator } from './server-translator.js'
+export type { ServerTranslator } from './server-translator.js'

package/src/i18n/locale-cookie.ts

@@ -0,0 +1,68 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Cookie helpers for the admin interface locale preference.
+ *
+ * The cookie name is `byline_admin_lng` — follows the `byline_*` prefix
+ * convention shared with the other admin cookies (`byline_access_token`,
+ * `byline_refresh_token`, `byline_preview`). Deliberately distinct from
+ * any host-side front-end-site i18n cookie (the example webapp uses
+ * `lng` for its public-site switcher). The two systems are independent:
+ * an editor in a Spanish-language admin chrome routinely edits English /
+ * French / German content, and the host's public site may carry its own
+ * locale switcher in its own cookie. Sharing one cookie across both
+ * would cause cross-talk.
+ *
+ * Cookie attributes:
+ *   - `httpOnly: false` — the client-side `<LanguageMenu>` reads the
+ *     cookie to render the active row indicator; setting it httpOnly
+ *     would force a server roundtrip on every page load just to know
+ *     which locale the user chose.
+ *   - `sameSite: 'lax'`
+ *   - `secure: true` in production — https-only.
+ *   - `path: '/'`
+ *   - `maxAge: 365 days` — language preference is a long-lived choice.
+ */
+
+import { getCookie, setCookie } from '@tanstack/react-start/server'
+
+export const ADMIN_LOCALE_COOKIE = 'byline_admin_lng'
+const ADMIN_LOCALE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365 // 365 days
+
+const IS_PROD = process.env.NODE_ENV === 'production'
+
+/** Read the current admin locale cookie, if any. */
+export function readAdminLocaleCookie(): string | null {
+  return getCookie(ADMIN_LOCALE_COOKIE) ?? null
+}
+
+/**
+ * Write the admin locale cookie. Caller is expected to have validated
+ * `locale` against the permitted `i18n.interface.locales` set first.
+ */
+export function setAdminLocaleCookie(locale: string): void {
+  setCookie(ADMIN_LOCALE_COOKIE, locale, {
+    httpOnly: false,
+    sameSite: 'lax',
+    secure: IS_PROD,
+    path: '/',
+    maxAge: ADMIN_LOCALE_MAX_AGE_SECONDS,
+  })
+}
+
+/** Clear the cookie — used when a user opts back into browser-default detection. */
+export function clearAdminLocaleCookie(): void {
+  setCookie(ADMIN_LOCALE_COOKIE, '', {
+    httpOnly: false,
+    sameSite: 'lax',
+    secure: IS_PROD,
+    path: '/',
+    maxAge: 0,
+  })
+}

package/src/i18n/locale-definitions.ts

@@ -0,0 +1,48 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { LocaleDefinition } from '@byline/i18n'
+
+/**
+ * Build a `LocaleDefinition[]` for the language switcher. Per-code
+ * resolution order:
+ *
+ *   1. An entry from the host's `i18n.interface.localeDefinitions`
+ *      (matched by code). Wins outright — this is the path that lets a
+ *      host author write `Français` instead of the lowercase
+ *      `français` that CLDR's `Intl.DisplayNames` returns for romance
+ *      languages.
+ *   2. `Intl.DisplayNames(code).of(code)` — produces a display name in
+ *      each locale's own language using CLDR's data.
+ *   3. The raw code, as a last-resort fallback for exotic tags or
+ *      runtimes that lack `Intl.DisplayNames`.
+ *
+ * Used by both the admin layout (post-auth) and the sign-in page
+ * (pre-auth) — anywhere `<LanguageMenu>` mounts.
+ */
+export function buildLocaleDefinitions(
+  codes: readonly string[],
+  configured: ReadonlyArray<{ code: string; nativeName: string }> | undefined
+): LocaleDefinition[] {
+  const explicit = new Map((configured ?? []).map((d) => [d.code, d.nativeName]))
+  return codes.map((code) => {
+    const explicitName = explicit.get(code)
+    if (explicitName != null) {
+      return { code, nativeName: explicitName }
+    }
+    let nativeName = code
+    try {
+      const dn = new Intl.DisplayNames([code], { type: 'language' })
+      nativeName = dn.of(code) ?? code
+    } catch {
+      // Intl.DisplayNames is available in Node 18+ and every modern
+      // browser. Defensive catch covers exotic codes or sandbox quirks.
+    }
+    return { code, nativeName }
+  })
+}

package/src/i18n/resolve-locale.ts

@@ -0,0 +1,96 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Server-side locale resolution for the admin interface.
+ *
+ * Combines `@byline/i18n`'s pure `resolveInterfaceLocale` cascade with
+ * the host's request-scoped signals — the `byline_admin_lng` cookie, the
+ * `Accept-Language` header, and (when an admin session is present)
+ * `admin_users.preferred_locale` on the authenticated actor.
+ *
+ * Idempotent: calling this twice in one request produces the same
+ * answer. SSR and the hydrated client therefore resolve to the same
+ * locale by construction — no "locale flicker" between server render
+ * and client takeover.
+ */
+
+import { getRequestHeader } from '@tanstack/react-start/server'
+
+import { AuthError, AuthErrorCodes } from '@byline/auth'
+import type { LocaleCode } from '@byline/i18n'
+import { resolveInterfaceLocale } from '@byline/i18n'
+
+import { getAdminRequestContext } from '../auth/auth-context.js'
+import { bylineCore } from '../integrations/byline-core.js'
+import { readAdminLocaleCookie } from './locale-cookie.js'
+
+/**
+ * Resolve the locale for the current request. Skips the
+ * `admin_users.preferred_locale` tier when no admin session is present —
+ * this is the right behaviour for pre-auth surfaces (sign-in page).
+ *
+ * Bypasses the auth resolver when `skipActorLookup` is true. Useful for
+ * very early-boot surfaces where the actor lookup itself is expensive
+ * or unwanted (rare; default to letting the cascade do its work).
+ */
+export async function resolveRequestLocale(options?: {
+  skipActorLookup?: boolean
+}): Promise<LocaleCode> {
+  const core = bylineCore()
+  const { interface: ifaceConfig } = core.config.i18n
+
+  let preferred: string | null = null
+  if (!options?.skipActorLookup) {
+    preferred = await readPreferredLocaleFromActor()
+  }
+
+  return resolveInterfaceLocale({
+    locales: ifaceConfig.locales,
+    defaultLocale: ifaceConfig.defaultLocale,
+    preferred,
+    cookie: readAdminLocaleCookie(),
+    acceptLanguage: readAcceptLanguage(),
+  })
+}
+
+async function readPreferredLocaleFromActor(): Promise<string | null> {
+  try {
+    const context = await getAdminRequestContext()
+    // The actor type isn't structurally typed for `preferred_locale`
+    // here — read it through the admin store to keep the resolver
+    // resilient to actor-shape evolution.
+    const adminStore = bylineCore().adminStore
+    if (adminStore == null) return null
+    const actor = context.actor
+    // Best-effort: the AdminAuth actor carries `id`. Reading the row
+    // directly from the repo costs one query per request that resolves
+    // a locale, which is fine for SSR; high-traffic paths can opt out
+    // via `skipActorLookup`.
+    if (actor == null || typeof actor !== 'object' || !('id' in actor)) return null
+    const id = (actor as { id: unknown }).id
+    if (typeof id !== 'string') return null
+    const row = await adminStore.adminUsers.getById(id)
+    return row?.preferred_locale ?? null
+  } catch (err) {
+    if (err instanceof AuthError && err.code === AuthErrorCodes.UNAUTHENTICATED) {
+      return null
+    }
+    // Any other failure (transport, refresh) → fall through to the
+    // cookie / Accept-Language tiers rather than crashing the SSR.
+    return null
+  }
+}
+
+function readAcceptLanguage(): string | null {
+  try {
+    return getRequestHeader('accept-language') ?? null
+  } catch {
+    return null
+  }
+}

package/src/i18n/server-translator.ts

@@ -0,0 +1,60 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `resolveServerTranslator(namespace)` — server-side companion to the
+ * client `useTranslation(namespace)` hook.
+ *
+ * Resolves the request locale via the same cascade the client hydrates
+ * against (preferred → cookie → Accept-Language → default), constructs
+ * a formatter bound to the registered translation bundle, and returns
+ * a `{ t, locale }` for the requested namespace. The shape mirrors
+ * `useTranslation` so callers can swap surfaces (loader vs component)
+ * without rethinking the API.
+ *
+ * Typical use:
+ *
+ *   import { resolveServerTranslator } from '@byline/host-tanstack-start/i18n'
+ *
+ *   export const sendInviteFn = createServerFn(...).handler(async () => {
+ *     const { t } = await resolveServerTranslator('byline-admin')
+ *     return { subject: t('email.invite.subject') }
+ *   })
+ */
+
+import { createFormatter, type LocaleCode } from '@byline/i18n'
+
+import { bylineCore } from '../integrations/byline-core.js'
+import { resolveRequestLocale } from './resolve-locale.js'
+
+export interface ServerTranslator {
+  t: (key: string, values?: Record<string, string | number | boolean | Date | null>) => string
+  locale: LocaleCode
+}
+
+export async function resolveServerTranslator(namespace: string): Promise<ServerTranslator> {
+  const core = bylineCore()
+  const { interface: ifaceConfig, translations: bundle } = core.config.i18n
+  if (bundle == null) {
+    throw new Error(
+      '[resolveServerTranslator] no translation bundle is registered. ' +
+        'Pass `translations: adminTranslations({ en: true })` (or a merged bundle) ' +
+        'on `i18n` in your config.'
+    )
+  }
+  const activeLocale = await resolveRequestLocale()
+  const formatter = createFormatter({
+    bundle,
+    activeLocale,
+    defaultLocale: ifaceConfig.defaultLocale,
+  })
+  return {
+    t: (key, values) => formatter.t(namespace, key, values),
+    locale: activeLocale,
+  }
+}