npm - @terpjs/react-core - Versions diffs - 0.11.0 → 0.13.0 - Mend

@terpjs/react-core 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md CHANGED Viewed

@@ -31,9 +31,10 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
   focus ring, a checkbox's `accent-color`. One token cannot do both: in a dark theme the
   surface use needs a value dark enough to hold a white label and the ink use needs one light
   enough to read on a dark canvas, and there is no value satisfying both.
-- **User-facing text is `UiText`** — every text prop accepts a plain string or an
-  `{id, message}` descriptor, so apps can localize via `UiTextProvider` without
-  react-core taking an i18n dependency.
+- **Static user-facing text is cataloged** — use an `{id, message}` `UiText`
+  descriptor for text props and `<Trans id message />` for JSX bodies. Plain strings are
+  reserved for dynamic business data, identifiers and product names. The boundary lint
+  refuses bare static copy and checks every id against every target in `frontend/i18n.json`.
 - **Dependency-free UI** — react-core ships no icon/toast/i18n libraries. Glyphs are
   inline SVG; transient feedback goes through `ToastProvider` / `useToast`.
 - **Security defaults** — `dangerouslySetInnerHTML` and the DOM HTML-injection sinks
@@ -54,7 +55,7 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
 | `useSso`, `parseSsoCallback`, `fetchSsoAuthorizationUrl`, `completeSsoCallback` | The SSO login seam (ADR 0058): `useSso().begin(provider)` opens an OIDC flow; `TerpProvider` completes the `/auth/callback/{provider}` redirect landing into a normal session on boot. `renderTerpApp({ ssoProviders })` wires the buttons in one line. |
 | `RequireAuth` | Renders children only with a session; pairs with the router so the app mounts only when signed in. |
 | `ThemeProvider`, `ThemeToggle`, `useTheme` | Theming over the shipped palettes — `light`, `dark`, `midnight`, `twilight`, `contrast` — plus `system` to follow the OS preference. Applies `data-theme` on `<html>` (the token stylesheet carries every palette) and persists the choice. `defaultTheme` is how an app ships on a named theme — declare it in `layout-contract.json` so a tool can read and rewrite it, or pass the bootstrap option; both is refused. `renderTerpApp` mounts it for every app; the shell header uses an icon-only, token-themed `variant="inline"` menu. |
-| `LocaleProvider`, `LanguageSwitcher`, `useLocale`, `LOCALE_EN`, `LOCALE_NL` | The language seam over `UiTextProvider`: per-locale string catalogs, a persisted active locale, and an icon-only, token-themed menu in the shell header once an app declares a second locale. English and Dutch catalogs ship complete; `renderTerpApp({ locales })` wires them. |
+| `LocaleProvider`, `defineAppLocales`, `LanguageSwitcher`, `useLocale`, `LOCALE_EN`, `LOCALE_NL` | The language seam over `UiTextProvider`: `defineAppLocales(i18n, frameworkCatalogs)` validates and merges checked-in app messages with framework chrome, the active locale persists, and the shell offers a picker. Pass `sourceLocale` with `locales`; missing/empty target messages, undocumented source copies, invalid locale selection and a non-English locale without a complete framework-string catalog throw rather than silently falling back. |
 | `UserMenu`, `userInitials` | The signed-in user's menu, pinned by `buildAppRouter` to the bottom of the sidebar: an initials avatar trigger opening the identity block, **Settings** (the built-in profile page) and sign-out. Collapses to the avatar in the icon rail. |
 | `ProfileView` | The built-in profile / settings page (`/profile`): the server-validated identity, theme + language preferences, and sign-out. |
@@ -266,7 +267,7 @@ single screen by claiming its path from an app module.
 | Export | Use |
 |---|---|
-| `UiTextProvider`, `useUiText`, `useStrings`, `resolveUiText`, `DEFAULT_STRINGS` | The `UiText` seam: override built-in strings and plug in a resolver (e.g. an i18n library) at the app root. `LocaleProvider` (above) is the batteries-included layer over it: per-locale catalogs + a persisted switcher. |
+| `UiTextProvider`, `Trans`, `useUiText`, `useStrings`, `resolveUiText`, `DEFAULT_STRINGS` | The `UiText` seam: descriptors for props, `Trans` for body copy, and framework strings through one resolver. `LocaleProvider` is the batteries-included catalog layer and refuses missing target-locale entries. |
 ## Testing components

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Terp React stack core — typed @terpjs/contract client provider, auth session, capability gates, TanStack Router adapter, app shell, page archetypes, DataView and token-styled UI primitives. First frontend stack; see README.md for the component catalog.",
   "exports": {
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.11.0"
+    "@terpjs/contract": "^0.13.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/AppShell.test.tsx CHANGED Viewed

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { NavItem } from "@terpjs/contract";
 import { AppShell, SIDEBAR_STORAGE_KEY } from "./AppShell";
+import { LOCALE_NL, LocaleProvider } from "./locale";
 afterEach(() => {
   cleanup();
@@ -360,6 +361,48 @@ describe("AppShell navigation groups", () => {
     { label: "Loose", to: "/loose" },
   ];
+  it("resolves localized item and group descriptors before rendering navigation", () => {
+    render(
+      <LocaleProvider
+        locales={{
+          en: {},
+          nl: {
+            ...LOCALE_NL,
+            messages: {
+              "nav.work": "Werkruimte",
+              "nav.notes": "Notities",
+            },
+          },
+        }}
+        defaultLocale="nl"
+        sourceLocale="en"
+      >
+        <AppShell
+          title="Terp"
+          nav={[
+            {
+              label: { id: "nav.notes", message: "Notes" },
+              to: "/notes",
+              group: "work",
+            },
+          ]}
+          navGroups={[
+            {
+              id: "work",
+              label: { id: "nav.work", message: "Workspace" },
+            },
+          ]}
+          renderLink={(item, children) => <a href={item.to}>{children}</a>}
+        >
+          <p>page content</p>
+        </AppShell>
+      </LocaleProvider>,
+    );
+    expect(screen.getByRole("list", { name: "Werkruimte" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Notities" })).toHaveAttribute("href", "/notes");
+  });
   it("labels each group's list with its own visible label", () => {
     render(
       <AppShell

package/src/AppShell.tsx CHANGED Viewed

@@ -477,11 +477,12 @@ export function AppShell({
       onClick={isMobile ? closeDrawer : undefined}
     >
       {groupNav(nav, navGroups).map((section, index) => {
+        const groupLabel = section.label === null ? null : resolve(section.label);
         // Only a labelled section needs an id, and only a DECLARED section can be labelled — the
         // default one has no declaration to carry a label. Keyed on the index rather than on
         // `section.id`: a group id is an app-supplied string, and whitespace in one would
         // silently break the IDREF rather than fail anywhere.
-        const labelId = section.label === null ? undefined : `${navGroupId}-${index}`;
+        const labelId = groupLabel === null ? undefined : `${navGroupId}-${index}`;
         return (
           // No heading element, and this is the decision rather than an oversight. `Heading`
           // refuses level 1 to reserve it for the routed view's title (see typography.tsx), and
@@ -504,22 +505,25 @@ export function AppShell({
           <div key={index} data-terp="appshell-nav-group">
             {labelId !== undefined && (
               <span id={labelId} data-terp="appshell-nav-group-label">
-                {section.label}
+                {groupLabel}
               </span>
             )}
             <ul data-terp="appshell-nav-list" aria-labelledby={labelId}>
-              {section.items.map((item) => (
-                <li key={item.to} title={railCollapsed ? item.label : undefined}>
-                  {renderLink(
-                    item,
-                    <>
-                      <NavIcon name={item.icon} label={item.label} />
-                      <span data-terp="appshell-nav-label">{item.label}</span>
-                    </>,
-                    { collapsed: railCollapsed, active: item.to === currentTo },
-                  )}
-                </li>
-              ))}
+              {section.items.map((item) => {
+                const label = resolve(item.label);
+                return (
+                  <li key={item.to} title={railCollapsed ? label : undefined}>
+                    {renderLink(
+                      item,
+                      <>
+                        <NavIcon name={item.icon} label={label} />
+                        <span data-terp="appshell-nav-label">{label}</span>
+                      </>,
+                      { collapsed: railCollapsed, active: item.to === currentTo },
+                    )}
+                  </li>
+                );
+              })}
             </ul>
           </div>
         );

package/src/ConfirmDialog.tsx CHANGED Viewed

@@ -3,8 +3,8 @@ import type { ReactNode } from "react";
 import { Button } from "./ui/Button";
 import { injectTerpStyles } from "./styles";
-import { useStrings, useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useStrings, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 injectTerpStyles();
@@ -18,7 +18,7 @@ export interface ConfirmDialogProps {
   /** Short question — what is about to happen. */
   title: UiText;
   /** Optional consequence explanation. */
-  description?: ReactNode;
+  description?: UiTextNode;
   /** Confirm-button label; defaults to the `confirm` string. */
   confirmLabel?: UiText;
   /** Cancel-button label; defaults to the `cancel` string. */
@@ -118,7 +118,7 @@ export function ConfirmDialog({
         </h2>
         {description !== undefined && (
           <div id={descriptionId} data-terp="dialog-description">
-            {description}
+            {resolveUiTextNode(description, resolve)}
           </div>
         )}
         <div data-terp="dialog-actions">

package/src/EmptyState.tsx CHANGED Viewed

@@ -2,8 +2,8 @@ import type { ReactNode } from "react";
 import { Icon } from "./icons";
 import { injectTerpStyles } from "./styles";
-import { useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 injectTerpStyles();
@@ -16,7 +16,7 @@ export interface EmptyStateProps {
   /** Short title — what is missing. */
   title: UiText;
   /** Optional explanation — why it's missing, or what to do next. */
-  description?: ReactNode;
+  description?: UiTextNode;
   /** Optional call to action (typically a `Button`). */
   action?: ReactNode;
   /**
@@ -58,9 +58,12 @@ export function EmptyState({
     <div data-terp="empty-state" data-size={compact ? "compact" : undefined}>
       {leading}
       <p data-terp="empty-state-title">{resolve(title)}</p>
-      {description !== undefined && <div data-terp="empty-state-description">{description}</div>}
+      {description !== undefined && (
+        <div data-terp="empty-state-description">
+          {resolveUiTextNode(description, resolve)}
+        </div>
+      )}
       {action}
     </div>
   );
 }

package/src/ErrorState.tsx CHANGED Viewed

@@ -3,8 +3,8 @@ import type { ReactNode } from "react";
 import { useErrorMessage } from "./errorMessages";
 import { Icon } from "./icons";
 import { injectTerpStyles } from "./styles";
-import { useStrings, useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useStrings, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 injectTerpStyles();
@@ -43,7 +43,7 @@ export interface ErrorStateProps {
    * copy for the error's stable `code` (see `useErrorMessage`), falling back to
    * {@link describeError}, so the platform error envelope surfaces consistently.
    */
-  description?: ReactNode;
+  description?: UiTextNode;
   /** The caught failure — used to derive `description` when none is given. */
   error?: unknown;
   /** Optional call to action (typically a retry `Button`). */
@@ -73,7 +73,11 @@ export function ErrorState({ icon, title, description, error, action }: ErrorSta
     <div role="alert" data-terp="error-state">
       {leading}
       <p data-terp="error-state-title">{resolve(title ?? strings.errorTitle)}</p>
-      {message !== null && message !== undefined && <div data-terp="error-state-description">{message}</div>}
+      {message !== null && message !== undefined && (
+        <div data-terp="error-state-description">
+          {resolveUiTextNode(message, resolve)}
+        </div>
+      )}
       {action}
     </div>
   );

package/src/Field.test.tsx CHANGED Viewed

@@ -3,6 +3,7 @@ import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 import { Field } from "./Field";
+import { UiTextProvider } from "./uiText";
 import { Input } from "./ui/Input";
 import { Select } from "./ui/Select";
 import { Textarea } from "./ui/Textarea";
@@ -10,6 +11,25 @@ import { Textarea } from "./ui/Textarea";
 afterEach(cleanup);
 describe("Field", () => {
+  it("resolves a descriptor used as helper text", () => {
+    render(
+      <UiTextProvider
+        resolveText={(text) =>
+          typeof text === "string" ? text : `translated:${text.id}`
+        }
+      >
+        <Field
+          label="Email"
+          hint={{ id: "account.email.hint", message: "We never share it" }}
+        >
+          <Input />
+        </Field>
+      </UiTextProvider>,
+    );
+    expect(screen.getByText("translated:account.email.hint")).toBeInTheDocument();
+  });
   it("labels its control (accessible association) and shows hint + error", () => {
     render(
       <Field label="Email" hint="we never share it" error="required">

package/src/Field.tsx CHANGED Viewed

@@ -15,7 +15,7 @@ export interface FieldProps {
   /** A field-level error (e.g. mapped from a 422), shown under the control. */
   error?: string | null;
   /** Optional helper text under the control. */
-  hint?: string;
+  hint?: UiText;
 }
 /**
@@ -90,7 +90,7 @@ export function Field({ label, children, error, hint }: FieldProps) {
       </label>
       {hint !== undefined && (
         <span id={hintId} data-terp="field-hint">
-          {hint}
+          {resolve(hint)}
         </span>
       )}
       {hasError && (

package/src/LoginView.tsx CHANGED Viewed

@@ -3,7 +3,7 @@ import type { FormEvent } from "react";
 import { TerpMark } from "./icons";
 import { useAuth, useSso } from "./TerpProvider";
-import { useStrings } from "./uiText";
+import { useStrings, useUiText } from "./uiText";
 import { Button } from "./ui/Button";
 import { Field } from "./Field";
 import { Input } from "./ui/Input";
@@ -53,6 +53,7 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
   const auth = useAuth();
   const sso = useSso();
   const strings = useStrings();
+  const resolve = useUiText();
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
   const [error, setError] = useState<string | null>(null);
@@ -158,7 +159,7 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
                   disabled={busy}
                   onClick={() => void onSso(provider)}
                 >
-                  {`${strings.continueWith} ${provider.label ?? provider.name}`}
+                  {`${strings.continueWith} ${resolve(provider.label ?? provider.name)}`}
                 </Button>
               ))}
             </div>

package/src/UserMenu.test.tsx CHANGED Viewed

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { TerpProvider, useAuth } from "./TerpProvider";
 import { UserMenu, userInitials } from "./UserMenu";
-import { LOCALE_EN, LocaleProvider } from "./locale";
+import { LOCALE_EN, LOCALE_NL, LocaleProvider } from "./locale";
 import { ThemeProvider } from "./theme";
 function jsonResponse(body: unknown): Response {
@@ -73,7 +73,7 @@ describe("UserMenu", () => {
     stubAuthFetch();
     render(
       <ThemeProvider>
-        <LocaleProvider locales={{ en: LOCALE_EN, nl: { label: "Nederlands" } }}>
+        <LocaleProvider locales={{ en: LOCALE_EN, nl: LOCALE_NL }}>
           <TerpProvider baseUrl="https://api.test">
             <LogInOnMount />
             <UserMenu />

package/src/bootstrap.tsx CHANGED Viewed

@@ -2,7 +2,7 @@ import { RouterProvider } from "@tanstack/react-router";
 import { StrictMode } from "react";
 import type { ComponentType, ReactNode } from "react";
 import { createRoot } from "react-dom/client";
-import type { ModuleManifest, NavGroup } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup, UiText } from "@terpjs/contract";
 import { LoginView } from "./LoginView";
 import type { DevCredentials } from "./LoginView";
@@ -95,7 +95,7 @@ export function collectModules(modules: Record<string, unknown>): {
 export interface RenderTerpAppOptions {
   /** App title shown in the shell's sidebar brand (and the default footer). */
-  title: string;
+  title: UiText;
   /** Discovered modules from an import.meta.glob over "./modules/<name>/module.tsx" (eager). */
   modules: Record<string, unknown>;
   /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
@@ -187,6 +187,8 @@ export interface RenderTerpAppOptions {
   locales?: Record<string, LocaleCatalog>;
   /** Starting locale when the user has not chosen one; default: the first `locales` key. */
   defaultLocale?: string;
+  /** Source locale for app-authored UiText descriptors; default: the first locale key. */
+  sourceLocale?: string;
   /**
    * Starting theme when the user has not chosen one; default `"system"` (OS preference).
    *
@@ -362,6 +364,7 @@ export function renderTerpApp(options: RenderTerpAppOptions): void {
         <LocaleProvider
           locales={options.locales ?? { en: {} }}
           defaultLocale={options.defaultLocale}
+          sourceLocale={options.sourceLocale}
         >
           <TerpProvider baseUrl={options.baseUrl ?? ""} ssoCallbackPath={options.ssoCallbackPath}>
             <ToastProvider>

package/src/format.test.tsx CHANGED Viewed

@@ -13,7 +13,7 @@ import {
   useFormatDate,
   useFormatNumber,
 } from "./format";
-import { LocaleProvider } from "./locale";
+import { LOCALE_EN, LOCALE_NL, LocaleProvider } from "./locale";
 afterEach(() => {
   cleanup();
@@ -27,8 +27,8 @@ afterEach(() => {
 // version asserted the literal digit 7 and would have failed in Kiritimati and nowhere else.
 const WHEN = "2026-07-07T12:00:00Z";
-const NL = { label: "Nederlands", strings: {} };
-const EN = { label: "English", strings: {} };
+const NL = LOCALE_NL;
+const EN = LOCALE_EN;
 describe("the locale-explicit formatters", () => {
   it("actually varies with the locale it is given", () => {

package/src/index.ts CHANGED Viewed

@@ -87,8 +87,23 @@ export type {
 } from "./SplitPage";
 export { HubPage, HubCard } from "./HubPage";
 export type { HubPageProps, HubCardProps, RenderHubCardLink } from "./HubPage";
-export { UiTextProvider, useStrings, useUiText, resolveUiText, DEFAULT_STRINGS } from "./uiText";
-export type { UiText, ResolveUiText, TerpStrings, UiTextProviderProps } from "./uiText";
+export {
+  UiTextProvider,
+  Trans,
+  useStrings,
+  useUiText,
+  resolveUiText,
+  resolveUiTextNode,
+  DEFAULT_STRINGS,
+} from "./uiText";
+export type {
+  UiText,
+  UiTextNode,
+  ResolveUiText,
+  TerpStrings,
+  TransProps,
+  UiTextProviderProps,
+} from "./uiText";
 export { EmptyState } from "./EmptyState";
 export type { EmptyStateProps } from "./EmptyState";
 export { ErrorState, describeError } from "./ErrorState";
@@ -216,13 +231,19 @@ export { ThemeProvider, ThemeToggle, useTheme, THEME_STORAGE_KEY } from "./theme
 export type { Theme, ThemeProviderProps, ThemeToggleProps } from "./theme";
 export {
   LocaleProvider,
+  defineAppLocales,
   LanguageSwitcher,
   useLocale,
   LOCALE_EN,
   LOCALE_NL,
   LOCALE_STORAGE_KEY,
 } from "./locale";
-export type { LocaleCatalog, LocaleProviderProps, LanguageSwitcherProps } from "./locale";
+export type {
+  AppI18nDeclaration,
+  LocaleCatalog,
+  LocaleProviderProps,
+  LanguageSwitcherProps,
+} from "./locale";
 export { UserMenu, userInitials } from "./UserMenu";
 export type { UserMenuProps } from "./UserMenu";

package/src/locale.test.tsx CHANGED Viewed

@@ -2,8 +2,15 @@
 import { cleanup, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
-import { LOCALE_EN, LOCALE_NL, LOCALE_STORAGE_KEY, LanguageSwitcher, LocaleProvider } from "./locale";
-import { DEFAULT_STRINGS, useStrings } from "./uiText";
+import {
+  LOCALE_EN,
+  LOCALE_NL,
+  LOCALE_STORAGE_KEY,
+  LanguageSwitcher,
+  LocaleProvider,
+  defineAppLocales,
+} from "./locale";
+import { DEFAULT_STRINGS, Trans, useStrings } from "./uiText";
 afterEach(() => {
   cleanup();
@@ -14,7 +21,7 @@ function SignOutLabel() {
   return <p>{useStrings().signOut}</p>;
 }
-const NL = { label: "Nederlands", strings: { signOut: "Uitloggen", language: "Taal" } };
+const NL = LOCALE_NL;
 describe("LocaleProvider + LanguageSwitcher", () => {
   it("feeds the active catalog's overrides through the UiText seam", () => {
@@ -84,6 +91,191 @@ describe("LocaleProvider + LanguageSwitcher", () => {
     // No visible label text in the inline variant.
     expect(screen.queryByText("Language")).not.toBeInTheDocument();
   });
+  it("resolves app descriptors through the active locale catalog", () => {
+    render(
+      <LocaleProvider
+        locales={{ en: LOCALE_EN, nl: { ...NL, messages: { greeting: "Hallo" } } }}
+        defaultLocale="nl"
+        sourceLocale="en"
+      >
+        <Trans id="greeting" message="Hello" />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Hallo")).toBeInTheDocument();
+  });
+  it("refuses a missing target translation instead of silently using source copy", () => {
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: LOCALE_EN, nl: NL }} defaultLocale="nl" sourceLocale="en">
+          <Trans id="greeting" message="Hello" />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/Missing translation "greeting" for locale "nl"/);
+  });
+  it("refuses a copied source translation unless allowIdentical documents it", () => {
+    expect(() =>
+      render(
+        <LocaleProvider
+          locales={{ en: {}, nl: { ...LOCALE_NL, messages: { greeting: "Hello" } } }}
+          defaultLocale="nl"
+          sourceLocale="en"
+        >
+          <Trans id="greeting" message="Hello" />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/copies its source text/);
+    render(
+      <LocaleProvider
+        locales={{
+          en: {},
+          nl: {
+            ...LOCALE_NL,
+            messages: { greeting: "Hello" },
+            allowIdentical: ["greeting"],
+          },
+        }}
+        defaultLocale="nl"
+        sourceLocale="en"
+      >
+        <Trans id="greeting" message="Hello" />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Hello")).toBeInTheDocument();
+  });
+  it("refuses malformed locale configuration and descriptors", () => {
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: {} }} sourceLocale="nl">
+          <span />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/Source locale "nl" is not present/);
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: {} }} defaultLocale="nl">
+          <span />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/Default locale "nl" is not present/);
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: {} }}>
+          <Trans id="" message="Hello" />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/non-empty id and message/);
+  });
+  it("merges checked-in app messages with framework catalogs", () => {
+    expect(
+      defineAppLocales(
+        { sourceLocale: "nl", locales: { nl: {}, en: { messages: { greeting: "Hello" } } } },
+        { en: LOCALE_EN, nl: LOCALE_NL },
+      ).en.messages,
+    ).toEqual({ greeting: "Hello" });
+  });
+  it("validates the checked-in declaration before merging it", () => {
+    expect(() =>
+      defineAppLocales({ sourceLocale: "nl", locales: { en: {} } }),
+    ).toThrow(/Source locale "nl" is not present/);
+    expect(() =>
+      defineAppLocales({
+        sourceLocale: "nl",
+        locales: { nl: {}, en: { messages: { greeting: "" } } },
+      }),
+    ).toThrow(/empty or invalid message entry/);
+    expect(() =>
+      defineAppLocales(
+        { sourceLocale: "en", locales: { en: {} } },
+        { en: { strings: [] as never } },
+      ),
+    ).toThrow(/framework strings must be an object/);
+    expect(() =>
+      defineAppLocales(
+        { sourceLocale: "en", locales: { en: {} } },
+        "invalid" as never,
+      ),
+    ).toThrow(/Framework locale catalogs must be an object/);
+  });
+  it("refuses incomplete framework catalogs through LocaleProvider itself", () => {
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: LOCALE_EN, de: { messages: { greeting: "Hallo" } } }}>
+          <span />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/missing .* framework string translation/);
+  });
+  it("refuses malformed labels and supplied framework strings", () => {
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: { label: "" } }}>
+          <span />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/label must be a non-empty string/);
+    expect(() =>
+      render(
+        <LocaleProvider
+          locales={{ en: { strings: { ...LOCALE_NL.strings, signOut: "" } } }}
+        >
+          <span />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/empty or invalid framework string "signOut"/);
+    expect(() =>
+      render(
+        <LocaleProvider locales={{ en: { strings: "invalid" as never } }}>
+          <span />
+        </LocaleProvider>,
+      ),
+    ).toThrow(/framework strings must be an object/);
+  });
+  it("refuses a target locale whose app copy is translated but framework chrome is not", () => {
+    expect(() =>
+      defineAppLocales(
+        {
+          sourceLocale: "en",
+          locales: { en: {}, de: { messages: { greeting: "Hallo" } } },
+        },
+        { en: LOCALE_EN },
+      ),
+    ).toThrow(/missing .* framework string translation/);
+    const germanStrings = Object.fromEntries(
+      Object.keys(DEFAULT_STRINGS).map((key) => [key, `de:${key}`]),
+    );
+    expect(
+      defineAppLocales(
+        {
+          sourceLocale: "en",
+          locales: { en: {}, de: { messages: { greeting: "Hallo" } } },
+        },
+        { en: LOCALE_EN, de: { strings: germanStrings } },
+      ).de.messages,
+    ).toEqual({ greeting: "Hallo" });
+  });
+  it("always renders the descriptor fallback in the source locale", () => {
+    render(
+      <LocaleProvider
+        locales={{ en: { messages: { greeting: "stale catalog value" } } }}
+        sourceLocale="en"
+      >
+        <Trans id="greeting" message="Hello" />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Hello")).toBeInTheDocument();
+  });
 });
 describe("LOCALE_NL", () => {

package/src/locale.tsx CHANGED Viewed

@@ -1,21 +1,153 @@
 import { createContext, useCallback, useContext, useMemo, useState } from "react";
 import type { ReactNode } from "react";
+import type { UiText } from "@terpjs/contract";
 import { Icon } from "./icons";
 import { Menu, MenuItem } from "./ui/Menu";
-import { UiTextProvider, useStrings } from "./uiText";
+import { DEFAULT_STRINGS, UiTextProvider, useStrings } from "./uiText";
 import type { TerpStrings } from "./uiText";
 /**
- * One locale's catalog: per-key overrides of the framework strings (missing keys fall
- * back to the bundled English defaults) plus an optional native display name for
- * language pickers. `{}` is a valid catalog — English needs no overrides.
+ * One locale's catalog: framework strings, app messages, and an optional native display
+ * name for language pickers. English locales may omit `strings` because react-core's
+ * bundled defaults are English; every declared non-English locale must supply the complete
+ * `TerpStrings` set so framework chrome cannot silently fall back to English.
  */
 export interface LocaleCatalog {
   /** Native display name shown by {@link LanguageSwitcher} (default: the locale code). */
   label?: string;
   /** Framework-string overrides for this locale. */
   strings?: Partial<TerpStrings>;
+  /** App-authored messages, keyed by the stable id carried by a `UiText` descriptor. */
+  messages?: Record<string, string>;
+  /** Message ids intentionally identical to their source copy (catalog-gate documentation). */
+  allowIdentical?: readonly string[];
+}
+/** Checked-in, JSON-compatible app declaration consumed by {@link defineAppLocales}. */
+export interface AppI18nDeclaration {
+  sourceLocale: string;
+  locales: Record<string, LocaleCatalog>;
+}
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertLocaleCatalogs(
+  locales: unknown,
+  sourceLocale?: string,
+): asserts locales is Record<string, LocaleCatalog> {
+  if (!isRecord(locales) || Object.keys(locales).length === 0) {
+    throw new Error("Locale catalogs must declare at least one locale.");
+  }
+  if (
+    sourceLocale !== undefined &&
+    (sourceLocale.trim() === "" || !Object.hasOwn(locales, sourceLocale))
+  ) {
+    throw new Error(`Source locale "${sourceLocale}" is not present in the locale catalogs.`);
+  }
+  for (const [code, value] of Object.entries(locales)) {
+    if (code.trim() === "" || !isRecord(value)) {
+      throw new Error("Locale entries must be non-empty codes mapped to catalog objects.");
+    }
+    if (
+      value.label !== undefined &&
+      (typeof value.label !== "string" || value.label.trim() === "")
+    ) {
+      throw new Error(`Locale "${code}" label must be a non-empty string.`);
+    }
+    if (value.strings !== undefined && !isRecord(value.strings)) {
+      throw new Error(`Locale "${code}" framework strings must be an object.`);
+    }
+    for (const [key, translated] of Object.entries(value.strings ?? {})) {
+      if (!Object.hasOwn(DEFAULT_STRINGS, key)) {
+        throw new Error(`Locale "${code}" has unknown framework string "${key}".`);
+      }
+      if (typeof translated !== "string" || translated.trim() === "") {
+        throw new Error(`Locale "${code}" has an empty or invalid framework string "${key}".`);
+      }
+    }
+    const messages = value.messages;
+    if (messages !== undefined && !isRecord(messages)) {
+      throw new Error(`Locale "${code}" messages must be an object.`);
+    }
+    for (const [id, translated] of Object.entries(messages ?? {})) {
+      if (id.trim() === "" || typeof translated !== "string" || translated.trim() === "") {
+        throw new Error(`Locale "${code}" has an empty or invalid message entry.`);
+      }
+    }
+    const allowed = value.allowIdentical;
+    if (
+      allowed !== undefined &&
+      (!Array.isArray(allowed) ||
+        allowed.some((id) => typeof id !== "string" || id.trim() === ""))
+    ) {
+      throw new Error(`Locale "${code}" allowIdentical must be an array of non-empty ids.`);
+    }
+    if (allowed !== undefined && new Set(allowed).size !== allowed.length) {
+      throw new Error(`Locale "${code}" allowIdentical contains duplicate ids.`);
+    }
+    const stale = allowed?.find((id) => typeof messages?.[id] !== "string");
+    if (stale !== undefined) {
+      throw new Error(`Locale "${code}" allowIdentical names missing message "${stale}".`);
+    }
+  }
+}
+function assertFrameworkStringsComplete(locales: Record<string, LocaleCatalog>): void {
+  for (const [code, catalog] of Object.entries(locales)) {
+    if (code.split("-")[0].toLowerCase() === "en") continue;
+    const missing = Object.keys(DEFAULT_STRINGS).filter(
+      (key) =>
+        typeof catalog.strings?.[key as keyof TerpStrings] !== "string" ||
+        catalog.strings[key as keyof TerpStrings]?.trim() === "",
+    );
+    if (missing.length > 0) {
+      throw new Error(
+        `Locale "${code}" is missing ${missing.length} framework string translation(s) ` +
+          `(for example: ${missing.slice(0, 3).join(", ")}). ` +
+          "Pass a complete framework catalog; app messages alone do not translate the shell.",
+      );
+    }
+  }
+}
+/**
+ * Merge app message catalogs with react-core's framework-string catalogs. This keeps one
+ * checked-in `i18n.json` authoritative for app copy without duplicating LOCALE_EN/LOCALE_NL.
+ */
+export function defineAppLocales(
+  declaration: AppI18nDeclaration,
+  frameworkLocales: Record<string, LocaleCatalog> = {},
+): Record<string, LocaleCatalog> {
+  if (!isRecord(declaration) || typeof declaration.sourceLocale !== "string") {
+    throw new Error("frontend/i18n.json must declare sourceLocale and a locales map.");
+  }
+  assertLocaleCatalogs(declaration.locales, declaration.sourceLocale);
+  if (!isRecord(frameworkLocales)) {
+    throw new Error("Framework locale catalogs must be an object.");
+  }
+  if (Object.keys(frameworkLocales).length > 0) {
+    assertLocaleCatalogs(frameworkLocales);
+  }
+  const merged = Object.fromEntries(
+    Object.entries(declaration.locales).map(([code, app]) => {
+      const framework = frameworkLocales[code] ?? {};
+      return [
+        code,
+        {
+          ...framework,
+          ...app,
+          strings: { ...framework.strings, ...app.strings },
+          messages: { ...framework.messages, ...app.messages },
+        },
+      ];
+    }),
+  );
+  assertLocaleCatalogs(merged, declaration.sourceLocale);
+  assertFrameworkStringsComplete(merged);
+  return merged;
 }
 /** The built-in English catalog — the bundled defaults, no overrides needed. */
@@ -151,6 +283,8 @@ export interface LocaleProviderProps {
   locales: Record<string, LocaleCatalog>;
   /** Starting locale when the user has not chosen one; default: the first key. */
   defaultLocale?: string;
+  /** Locale whose descriptor `message` is the authored fallback; default: the first key. */
+  sourceLocale?: string;
   children: ReactNode;
 }
@@ -160,11 +294,20 @@ export interface LocaleProviderProps {
  * `UiText` context — so every react-core component (and every `UiText` prop) follows the
  * switch with no per-component wiring. Adding a language to an app is one catalog entry.
  */
-export function LocaleProvider({ locales, defaultLocale, children }: LocaleProviderProps) {
+export function LocaleProvider({
+  locales,
+  defaultLocale,
+  sourceLocale,
+  children,
+}: LocaleProviderProps) {
+  assertLocaleCatalogs(locales, sourceLocale);
+  assertFrameworkStringsComplete(locales);
   const codes = Object.keys(locales);
-  const fallback = defaultLocale !== undefined && codes.includes(defaultLocale)
-    ? defaultLocale
-    : codes[0];
+  if (defaultLocale !== undefined && !codes.includes(defaultLocale)) {
+    throw new Error(`Default locale "${defaultLocale}" is not present in the locale catalogs.`);
+  }
+  const resolvedSourceLocale = sourceLocale ?? codes[0];
+  const fallback = defaultLocale ?? codes[0];
   const [locale, setLocaleState] = useState<string>(() => {
     try {
       const stored = window.localStorage.getItem(LOCALE_STORAGE_KEY);
@@ -173,6 +316,7 @@ export function LocaleProvider({ locales, defaultLocale, children }: LocaleProvi
       return fallback ?? "en";
     }
   });
+  const activeLocale = codes.includes(locale) ? locale : fallback;
   const setLocale = useCallback(
     (next: string) => {
@@ -191,17 +335,49 @@ export function LocaleProvider({ locales, defaultLocale, children }: LocaleProvi
   const value = useMemo<LocaleContextValue>(
     () => ({
-      locale,
+      locale: activeLocale,
       locales: codes,
       labelOf: (code) => locales[code]?.label ?? code,
       setLocale,
     }),
-    [locale, codes.join("\u0000"), setLocale, locales],
+    [activeLocale, codes.join("\u0000"), setLocale, locales],
+  );
+  const resolveText = useCallback(
+    (text: UiText): string => {
+      if (typeof text === "string") {
+        return text;
+      }
+      if (text.id.trim() === "" || text.message.trim() === "") {
+        throw new Error("UiText descriptors require non-empty id and message values.");
+      }
+      if (activeLocale === resolvedSourceLocale) {
+        return text.message;
+      }
+      const catalog = locales[activeLocale];
+      const translated = catalog?.messages?.[text.id];
+      if (typeof translated === "string" && translated.trim() !== "") {
+        if (translated === text.message && !catalog.allowIdentical?.includes(text.id)) {
+          throw new Error(
+            `Translation "${text.id}" for locale "${activeLocale}" copies its source text. ` +
+              "Translate it or document an intentional proper noun/acronym in allowIdentical.",
+          );
+        }
+        return translated;
+      }
+      throw new Error(
+        `Missing translation "${text.id}" for locale "${activeLocale}". ` +
+          "Add it to frontend/i18n.json and run the frontend lint gate.",
+      );
+    },
+    [activeLocale, locales, resolvedSourceLocale],
   );
   return (
     <LocaleContext.Provider value={value}>
-      <UiTextProvider strings={locales[locale]?.strings}>{children}</UiTextProvider>
+      <UiTextProvider strings={locales[activeLocale]?.strings} resolveText={resolveText}>
+        {children}
+      </UiTextProvider>
     </LocaleContext.Provider>
   );
 }

package/src/nav.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { ModuleManifest, NavGroup, NavItem } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup, NavItem, UiText } from "@terpjs/contract";
 /**
  * What a manifest's declared visibility is resolved against.
@@ -81,7 +81,7 @@ export interface NavSection {
   /** The declared group's id, or `null` for the default headerless group. */
   id: string | null;
   /** The label to render above the list, or `null` when the section renders none. */
-  label: string | null;
+  label: UiText | null;
   items: NavItem[];
 }

package/src/router.tsx CHANGED Viewed

@@ -14,7 +14,7 @@ import {
 } from "@tanstack/react-router";
 import type { ComponentType, ReactNode } from "react";
 import { useCallback, useEffect, useRef, useState } from "react";
-import type { ModuleManifest, NavGroup } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup, UiText } from "@terpjs/contract";
 import { AppShell } from "./AppShell";
 import { ProfileView } from "./ProfileView";
@@ -238,7 +238,7 @@ export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;
   /** App title shown in the shell's sidebar brand. */
-  title: string;
+  title: UiText;
   /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
   logo?: ReactNode;
   /**

package/src/sso.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { TerpClient, TerpClientFor } from "@terpjs/contract";
+import type { TerpClient, TerpClientFor, UiText } from "@terpjs/contract";
 import { unwrap } from "./unwrap";
@@ -61,7 +61,7 @@ export interface SsoProvider {
   /** Provider name as mounted on the backend (the `{provider}` path segment). */
   name: string;
   /** Display label for the provider button (defaults to the name). */
-  label?: string;
+  label?: UiText;
 }
 /** Default SPA path prefix the IdP redirects back to: `/auth/callback/{provider}`. */

package/src/styles.test.ts CHANGED Viewed

@@ -63,6 +63,38 @@ afterEach(() => {
 });
 describe("injectTerpStyles", () => {
+  it("adopts a constructable stylesheet when the document supports one", () => {
+    // jsdom exposes the CSSStyleSheet constructor but not document.adoptedStyleSheets,
+    // so the property is defined here to reach the branch a real browser takes. That
+    // branch is the whole point of the injector: an adopted sheet is not governed by
+    // CSP's style-src, so a generated app needs no 'unsafe-inline' — measured in
+    // Chromium, where a <style> element is reported as style-src-elem and dropped.
+    const sheets: CSSStyleSheet[] = [];
+    Object.defineProperty(document, "adoptedStyleSheets", {
+      configurable: true,
+      get: () => sheets,
+      set: (next: CSSStyleSheet[]) => {
+        sheets.length = 0;
+        sheets.push(...next);
+      },
+    });
+    try {
+      injectTerpStyles();
+      expect(sheets.length).toBe(1);
+      // No element: taking the adopted route must not also append a <style>, or the
+      // page would carry the rules twice and still need the CSP keyword.
+      expect(document.getElementById(TERP_STYLES_ID)).toBeNull();
+      expect(sheets[0]?.cssRules.length ?? 0).toBeGreaterThan(0);
+      // Idempotent by the sheet's own mark rather than by an element id.
+      injectTerpStyles();
+      injectTerpStyles();
+      expect(sheets.length).toBe(1);
+    } finally {
+      delete (document as unknown as { adoptedStyleSheets?: unknown }).adoptedStyleSheets;
+    }
+  });
   it("appends the stylesheet once and is idempotent on re-invocation", () => {
     injectTerpStyles();
     injectTerpStyles();

package/src/styles.ts CHANGED Viewed

@@ -4228,13 +4228,50 @@ button[data-terp="input"][data-placeholder="true"] {
 }
 `;
+/**
+ * The property stamped on the constructed sheet so a second call recognises it.
+ *
+ * On the sheet object rather than on an element or a `data-` attribute: the sheet
+ * lives on the `document`, so the mark is document-scoped exactly like the old
+ * element-id check was, and it cannot collide with the `data-terp*` selectors
+ * this very stylesheet declares.
+ */
+const ADOPTED_MARKER = "__terpStylesId";
+/** A constructed sheet plus the mark identifying it as ours. */
+type MarkedSheet = CSSStyleSheet & { [ADOPTED_MARKER]?: string };
+/**
+ * `document.adoptedStyleSheets` is absent in jsdom, so the property is read
+ * through a type that admits that. Cast via `unknown` rather than intersected
+ * with `Document`, because the DOM lib declares the property as always present
+ * and an intersection would keep that stricter declaration.
+ */
+type AdoptableDocument = { adoptedStyleSheets?: MarkedSheet[] };
 /**
  * Inject the react-core interaction-state stylesheet once per document.
  *
- * SSR-safe: no-op when `document` is undefined. Idempotent: the sheet element
- * is keyed by {@link TERP_STYLES_ID}, so repeated calls (from any component's
- * module scope) attach the rules exactly once. Content is set via
- * `textContent` — never `innerHTML` — so no HTML-injection sink is touched.
+ * Prefers a **constructable stylesheet** (`new CSSStyleSheet()` +
+ * `document.adoptedStyleSheets`), because that is the only injection route a
+ * Content-Security-Policy does not have to widen for. A `<style>` element's
+ * rules are inline styles as far as CSP is concerned, so shipping them obliged
+ * every generated app to serve `style-src 'unsafe-inline'` — a keyword that,
+ * once present, also permits every *other* inline stylesheet on the page,
+ * including one an injection managed to introduce. Measured in Chromium: an
+ * adopted sheet applies cleanly under `style-src 'self'` while a `<style>`
+ * element is reported as a `style-src-elem` violation and its rules dropped.
+ *
+ * The `<style>` element remains the fallback, because a browser without
+ * constructable stylesheets would otherwise render the chrome unstyled. Under a
+ * strict policy those browsers get no styling either way, so the fallback only
+ * ever helps.
+ *
+ * SSR-safe: no-op when `document` is undefined. Idempotent by either route — the
+ * adopted sheet carries {@link ADOPTED_MARKER}, the element is keyed by
+ * {@link TERP_STYLES_ID} — so repeated calls from any component's module scope
+ * attach the rules exactly once. Neither route touches an HTML sink: the element
+ * path sets `textContent`, never `innerHTML`, and `replaceSync` parses CSS only.
  */
 export function injectTerpStyles(): void {
   if (typeof document === "undefined") {
@@ -4243,6 +4280,23 @@ export function injectTerpStyles(): void {
   if (document.getElementById(TERP_STYLES_ID) !== null) {
     return;
   }
+  const adopted = (document as unknown as AdoptableDocument).adoptedStyleSheets;
+  if (adopted !== undefined && typeof CSSStyleSheet === "function") {
+    if (adopted.some((sheet) => sheet[ADOPTED_MARKER] === TERP_STYLES_ID)) {
+      return;
+    }
+    try {
+      const sheet: MarkedSheet = new CSSStyleSheet();
+      sheet.replaceSync(TERP_STYLES_CSS);
+      sheet[ADOPTED_MARKER] = TERP_STYLES_ID;
+      (document as unknown as AdoptableDocument).adoptedStyleSheets = [...adopted, sheet];
+      return;
+    } catch {
+      // A browser that exposes the API but refuses this sheet still gets styling.
+    }
+  }
   const el = document.createElement("style");
   el.id = TERP_STYLES_ID;
   el.textContent = TERP_STYLES_CSS;

package/src/uiText.test.tsx CHANGED Viewed

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { Page } from "./Page";
 import { ResourceList } from "./ResourceList";
 import { TerpProvider } from "./TerpProvider";
-import { resolveUiText, UiTextProvider } from "./uiText";
+import { resolveUiText, resolveUiTextNode, UiTextProvider } from "./uiText";
 afterEach(cleanup);
@@ -14,6 +14,20 @@ describe("resolveUiText", () => {
     expect(resolveUiText("Tasks")).toBe("Tasks");
     expect(resolveUiText({ id: "tasks.title", message: "Tasks" })).toBe("Tasks");
   });
+  it("resolves descriptors in prose slots and preserves rich React nodes", () => {
+    const resolve = (text: string | { readonly id: string; readonly message: string }) =>
+      typeof text === "string" ? text : `translated:${text.id}`;
+    expect(
+      resolveUiTextNode(
+        { id: "tasks.empty.description", message: "Create your first task." },
+        resolve,
+      ),
+    ).toBe("translated:tasks.empty.description");
+    const rich = <strong>Already rendered</strong>;
+    expect(resolveUiTextNode(rich, resolve)).toBe(rich);
+  });
 });
 describe("UiTextProvider", () => {

package/src/uiText.tsx CHANGED Viewed

@@ -1,5 +1,8 @@
 import { createContext, useCallback, useContext, useMemo } from "react";
 import type { ReactNode } from "react";
+import type { UiText } from "@terpjs/contract";
+export type { UiText } from "@terpjs/contract";
 /**
  * A piece of user-facing text: either a plain string (used as-is) or a message
@@ -7,11 +10,38 @@ import type { ReactNode } from "react";
  * `message` used as the fallback. Components accept `UiText` so an app can go
  * from hardcoded strings to a full i18n runtime without changing call sites.
  */
-export type UiText = string | { id: string; message: string };
 /** Resolves a {@link UiText} to the display string for the active locale. */
 export type ResolveUiText = (text: UiText) => string;
+/** Textual copy or an already-rendered rich node, for prose-bearing component slots. */
+export type UiTextNode = UiText | ReactNode;
+/**
+ * Resolve a descriptor/string while leaving rich React content untouched. Components
+ * with prose slots use this instead of making callers choose between localization and
+ * inline emphasis/links.
+ */
+export function resolveUiTextNode(
+  value: UiTextNode,
+  resolve: ResolveUiText = resolveUiText,
+): ReactNode {
+  if (typeof value === "string") {
+    return resolve(value);
+  }
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "id" in value &&
+    "message" in value &&
+    typeof value.id === "string" &&
+    typeof value.message === "string"
+  ) {
+    return resolve(value);
+  }
+  return value as ReactNode;
+}
 /** The default resolver: plain strings as-is, descriptors via their fallback `message`. */
 export function resolveUiText(text: UiText): string {
   return typeof text === "string" ? text : text.message;
@@ -385,3 +415,15 @@ export function useUiText(): ResolveUiText {
   const { resolveText } = useContext(UiTextContext);
   return useCallback((text: UiText) => resolveText(text), [resolveText]);
 }
+/** Props for {@link Trans}: one stable catalog id and its source-language fallback. */
+export interface TransProps {
+  id: string;
+  message: string;
+}
+/** Render authored copy through the active locale resolver, including plain JSX body text. */
+export function Trans({ id, message }: TransProps) {
+  const resolve = useUiText();
+  return <>{resolve({ id, message })}</>;
+}