@cosmicdrift/kumiko-renderer 0.211.0 → 0.213.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.211.0",
+  "version": "0.213.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.211.0",
-    "@cosmicdrift/kumiko-headless": "0.211.0",
+    "@cosmicdrift/kumiko-framework": "0.213.0",
+    "@cosmicdrift/kumiko-headless": "0.213.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -25,7 +25,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",
-    "@cosmicdrift/kumiko-locale-de": "0.211.0"
+    "@cosmicdrift/kumiko-locale-de": "0.213.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/entity-list-row-action-entity-target.test.tsx

@@ -0,0 +1,194 @@
+// fw#2228: RowActionNavigate can now name an ObjectTarget (`entity`) instead
+// of a ScreenTarget (`screen`). This renders the real entityList pipeline
+// (KumikoScreen → EntityListBody) and asserts a click on the entity-target
+// row action calls nav.navigate with `{ entity, id }` — resolution to an
+// actual screen is the NavApi impl's job (renderer-web's resolveTarget), not
+// this platform-neutral package's. Mirrors
+// entity-list-row-action-kumiko-actions-view.test.tsx's harness.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type CorePrimitives,
+  type DataTableProps,
+  type DataTableRowAction,
+  PrimitivesProvider,
+} from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavTarget } from "../nav";
+import { NavProvider } from "../nav";
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async () => ({
+      isSuccess: true,
+      data: {
+        rows: [{ id: "invoice-42", customerId: "cust-7", status: "open" }],
+        nextCursor: null,
+        total: 1,
+      },
+    })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+let capturedRowActions: readonly DataTableRowAction[] | undefined;
+const captureDataTable: ComponentType<DataTableProps> = (props) => {
+  capturedRowActions = props.rowActions;
+  return null;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: captureDataTable,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function buildSchema(rowAction: EntityListScreenDefinition["rowActions"]): FeatureSchema {
+  const entity: EntityDefinition = {
+    fields: {
+      customerId: {
+        type: "text",
+        maxLength: 50,
+        required: false,
+        searchable: false,
+        sortable: false,
+      },
+      status: { type: "text", maxLength: 50, required: false, searchable: false, sortable: false },
+    },
+  };
+  const listScreen: EntityListScreenDefinition = {
+    id: "invoice-list",
+    type: "entityList",
+    entity: "invoice",
+    columns: ["status"],
+    rowActions: rowAction,
+  };
+  return {
+    featureName: "billing",
+    entities: { invoice: entity },
+    screens: [listScreen],
+  } as FeatureSchema;
+}
+
+function renderListScreen(schema: FeatureSchema, navigateSpy: (target: NavTarget) => void): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider
+          value={{
+            route: { screenId: "billing:invoice-list" },
+            navigate: navigateSpy,
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: () => {},
+          }}
+        >
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={schema} qn="billing:screen:invoice-list" />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+function requireAction(id: string): DataTableRowAction {
+  const action = capturedRowActions?.find((a) => a.id === id);
+  if (!action) throw new Error(`expected the '${id}' row action to be captured`);
+  return action;
+}
+
+describe("entityList navigate row-action with an entity-target (fw#2228)", () => {
+  test("clicking the row action calls nav.navigate with { entity, id }, not a screenId", async () => {
+    capturedRowActions = undefined;
+    const navigateCalls: NavTarget[] = [];
+
+    renderListScreen(
+      buildSchema([
+        { kind: "navigate", id: "view", label: "kumiko.actions.view", entity: "invoice" },
+      ]),
+      (target) => navigateCalls.push(target),
+    );
+
+    await waitFor(() => {
+      expect(capturedRowActions).toBeDefined();
+    });
+
+    await requireAction("view").onTrigger({
+      id: "invoice-42",
+      values: { id: "invoice-42", customerId: "cust-7", status: "open" },
+    });
+
+    expect(navigateCalls).toHaveLength(1);
+    expect(navigateCalls[0]).toEqual({ entity: "invoice", id: "invoice-42" });
+  });
+
+  test("an explicit entityId field-name still overrides the row['id'] default", async () => {
+    capturedRowActions = undefined;
+    const navigateCalls: NavTarget[] = [];
+
+    renderListScreen(
+      buildSchema([
+        {
+          kind: "navigate",
+          id: "view-customer",
+          label: "kumiko.actions.view",
+          entity: "customer",
+          entityId: "customerId",
+        },
+      ]),
+      (target) => navigateCalls.push(target),
+    );
+
+    await waitFor(() => {
+      expect(capturedRowActions).toBeDefined();
+    });
+
+    await requireAction("view-customer").onTrigger({
+      id: "invoice-42",
+      values: { id: "invoice-42", customerId: "cust-7" },
+    });
+
+    expect(navigateCalls).toEqual([{ entity: "customer", id: "cust-7" }]);
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -1297,23 +1297,34 @@ function EntityListBody({
   // nicht auseinanderdriften.
   const runNavigate = useCallback(
     (action: RowActionNavigate, row: ListRowViewModel) => {
-      // Default entityId für entityEdit-Targets: row["id"] wenn kein expliziter
-      // entityId-Feldname gesetzt ist. Nur für Targets DERSELBEN Entity — sonst
-      // bekäme ein Cross-Entity-Edit-Screen die falsche row.id injiziert.
-      const targetIsEntityEdit = schema.screens.some(
-        (s) =>
-          s.type === "entityEdit" &&
-          s.entity === screen.entity &&
-          lastSegment(s.id) === action.screen,
-      );
-      const explicit =
-        action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
-      const fallback = targetIsEntityEdit ? String(row.values["id"] ?? "") : undefined;
-      const entityId = explicit ?? fallback;
-      nav.navigate({
-        screenId: action.screen,
-        ...(entityId !== undefined && entityId !== "" && { entityId }),
-      });
+      if (action.entity !== undefined) {
+        // Entity-Targets (fw#2228) lösen sich erst in der NavApi-Impl gegen
+        // ALLE Features auf (resolveTarget in renderer-web/nav.tsx) — dieses
+        // Package kennt nur `schema` (das eine aufrufende Feature) und kann
+        // detailFor cross-feature nicht selbst nachschlagen.
+        const explicit =
+          action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
+        const id = explicit ?? String(row.values["id"] ?? "");
+        nav.navigate({ entity: action.entity, id });
+      } else if (action.screen !== undefined) {
+        // Default entityId für entityEdit-Targets: row["id"] wenn kein expliziter
+        // entityId-Feldname gesetzt ist. Nur für Targets DERSELBEN Entity — sonst
+        // bekäme ein Cross-Entity-Edit-Screen die falsche row.id injiziert.
+        const targetIsEntityEdit = schema.screens.some(
+          (s) =>
+            s.type === "entityEdit" &&
+            s.entity === screen.entity &&
+            lastSegment(s.id) === action.screen,
+        );
+        const explicit =
+          action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
+        const fallback = targetIsEntityEdit ? String(row.values["id"] ?? "") : undefined;
+        const entityId = explicit ?? fallback;
+        nav.navigate({
+          screenId: action.screen,
+          ...(entityId !== undefined && entityId !== "" && { entityId }),
+        });
+      }
       const params =
         action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
       if (params !== undefined) {
@@ -1658,12 +1669,24 @@ function ProjectionListBody({
 
   const runNavigate = useCallback(
     (action: RowActionNavigate, row: ListRowViewModel) => {
-      const entityId =
-        action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
-      nav.navigate({
-        screenId: action.screen,
-        ...(entityId !== undefined && entityId !== "" && { entityId }),
-      });
+      if (action.entity !== undefined) {
+        // Entity-Targets (fw#2228) — siehe EntityListBody.runNavigate für die
+        // Begründung, warum die Auflösung in der NavApi-Impl passiert. Anders
+        // als dort: KEIN row["id"]-Fallback — projectionList-Rows kommen aus
+        // einer beliebigen Query-Projection ohne garantiertes "id"-Feld
+        // (gleiche Begründung wie beim screen-Target unten). Der Boot-
+        // Validator erzwingt deshalb einen expliziten entityId für
+        // projectionList-entity-Targets.
+        const id = action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : "";
+        nav.navigate({ entity: action.entity, id });
+      } else if (action.screen !== undefined) {
+        const entityId =
+          action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
+        nav.navigate({
+          screenId: action.screen,
+          ...(entityId !== undefined && entityId !== "" && { entityId }),
+        });
+      }
       const params =
         action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
       if (params !== undefined) {
@@ -1963,46 +1986,68 @@ function ProjectionDetailBody({
         continue;
       }
       if (action.kind === "navigate") {
-        // Default entityId for an entityEdit target of the SAME entity
-        // (screen.detailFor plays entity's role here, like screen.entity
-        // does for entityList's runNavigate) — without this fallback the
-        // target opens an empty create-form instead of the shown record,
-        // silently. Searched cross-feature, consistent with editScreen above.
-        const explicit =
-          action.entityId !== undefined ? String(record[action.entityId] ?? "") : undefined;
-        const targetIsEntityEditSameEntity =
-          screen.detailFor !== undefined &&
-          appFeatures.some((feature) =>
-            feature.screens.some(
-              (s) =>
-                s.type === "entityEdit" &&
-                s.entity === screen.detailFor &&
-                lastSegment(s.id) === action.screen,
-            ),
-          );
-        const fallback = targetIsEntityEditSameEntity ? String(record["id"] ?? "") : undefined;
-        const navEntityId = explicit ?? fallback;
-        const targetScreen = action.screen;
-        out.push({
-          id: action.id,
-          label: effectiveTranslate(action.label),
-          ...(action.style !== undefined && { style: action.style }),
-          onPress: () => {
-            nav.navigate({
-              screenId: targetScreen,
-              ...(navEntityId !== undefined && navEntityId !== "" && { entityId: navEntityId }),
-            });
-            const params =
-              action.params !== undefined ? evalRowExtractor(action.params, record) : undefined;
-            if (params !== undefined) {
-              const stringified: Record<string, string | null> = {};
-              for (const [k, v] of Object.entries(params)) {
-                stringified[k] = v === null || v === undefined ? null : String(v);
-              }
-              nav.setSearchParams(stringified);
+        const runParams = (): void => {
+          const params =
+            action.params !== undefined ? evalRowExtractor(action.params, record) : undefined;
+          if (params !== undefined) {
+            const stringified: Record<string, string | null> = {};
+            for (const [k, v] of Object.entries(params)) {
+              stringified[k] = v === null || v === undefined ? null : String(v);
             }
-          },
-        });
+            nav.setSearchParams(stringified);
+          }
+        };
+        if (action.entity !== undefined) {
+          // Entity-Targets (fw#2228) — Auflösung passiert in der NavApi-Impl
+          // (siehe EntityListBody.runNavigate), nicht hier. KEIN record["id"]-
+          // Fallback: record kommt aus einer beliebigen Detail-Query ohne
+          // garantiertes "id"-Feld, der Boot-Validator erzwingt deshalb einen
+          // expliziten entityId für projectionDetail-entity-Targets.
+          const targetEntity = action.entity;
+          const id = action.entityId !== undefined ? String(record[action.entityId] ?? "") : "";
+          out.push({
+            id: action.id,
+            label: effectiveTranslate(action.label),
+            ...(action.style !== undefined && { style: action.style }),
+            onPress: () => {
+              nav.navigate({ entity: targetEntity, id });
+              runParams();
+            },
+          });
+        } else if (action.screen !== undefined) {
+          // Default entityId for an entityEdit target of the SAME entity
+          // (screen.detailFor plays entity's role here, like screen.entity
+          // does for entityList's runNavigate) — without this fallback the
+          // target opens an empty create-form instead of the shown record,
+          // silently. Searched cross-feature, consistent with editScreen above.
+          const explicit =
+            action.entityId !== undefined ? String(record[action.entityId] ?? "") : undefined;
+          const targetIsEntityEditSameEntity =
+            screen.detailFor !== undefined &&
+            appFeatures.some((feature) =>
+              feature.screens.some(
+                (s) =>
+                  s.type === "entityEdit" &&
+                  s.entity === screen.detailFor &&
+                  lastSegment(s.id) === action.screen,
+              ),
+            );
+          const fallback = targetIsEntityEditSameEntity ? String(record["id"] ?? "") : undefined;
+          const navEntityId = explicit ?? fallback;
+          const targetScreen = action.screen;
+          out.push({
+            id: action.id,
+            label: effectiveTranslate(action.label),
+            ...(action.style !== undefined && { style: action.style }),
+            onPress: () => {
+              nav.navigate({
+                screenId: targetScreen,
+                ...(navEntityId !== undefined && navEntityId !== "" && { entityId: navEntityId }),
+              });
+              runParams();
+            },
+          });
+        }
         continue;
       }
       // writeHandler — same dispatch/refetch/failure-surfacing pattern as

package/src/components/__tests__/render-field-unit-format.test.tsx

@@ -0,0 +1,102 @@
+// fw#2187: readOnly fields with an explicit `field.renderer: { format: "unit" }`
+// must render through applyFormatSpec's unit case, and default to the
+// LocaleProvider's App-Locale when the FormatSpec itself carries no `locale`
+// — same posture as render-field-app-locale.test.tsx for money/date inputs,
+// but for the FieldRendererOutput (readOnly + declared renderer) path, which
+// that file doesn't cover.
+//
+// Capture-Text instead of a real primitive, same pattern as
+// render-field-app-locale.test.tsx (Capture-Input there).
+
+import { describe, expect, test } from "bun:test";
+import type { EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
+import { render } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { type CorePrimitives, PrimitivesProvider, type TextProps } from "../../primitives";
+import { RenderField } from "../render-field";
+
+let captured: TextProps | undefined;
+const captureText: ComponentType<TextProps> = (props) => {
+  captured = props;
+  return null;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: noop,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: noop,
+  Section: noop,
+  Card: noop,
+  Grid: noop,
+  GridCell: noop,
+  Text: captureText,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function livingSpaceField(
+  renderer: EditFieldViewModel["renderer"],
+  value: unknown = 58,
+): EditFieldViewModel {
+  return {
+    field: "livingSpace",
+    label: "Wohnfläche",
+    type: "decimal",
+    value,
+    visible: true,
+    readOnly: true,
+    required: false,
+    renderer,
+  };
+}
+
+function renderUnderLocale(locale: string, field: EditFieldViewModel): void {
+  captured = undefined;
+  render(
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale })}>
+      <PrimitivesProvider value={testPrimitives}>
+        <RenderField field={field} onChange={() => {}} />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RenderField — unit-FormatSpec (fw#2187)", () => {
+  test("m2 rendert Zahl + m²-Suffix, locale-formatiert über das App-Locale", () => {
+    renderUnderLocale("de-DE", livingSpaceField({ format: "unit", unit: "m2" }));
+    expect(captured?.children).toBe("58 m²");
+  });
+
+  test("ein anderes App-Locale ändert die Zahl-Formatierung (en-US: Punkt statt Komma)", () => {
+    renderUnderLocale("en-US", livingSpaceField({ format: "unit", unit: "m2" }, 58.5));
+    expect(captured?.children).toBe("58.5 m²");
+  });
+
+  test("CLDR-sanktionierte Unit (km) rendert über Intl.NumberFormat(style:'unit')", () => {
+    renderUnderLocale("en-US", livingSpaceField({ format: "unit", unit: "km" }, 3));
+    expect(captured?.children).toBe("3 km");
+  });
+
+  test("explizites renderer.locale gewinnt gegen das App-Locale", () => {
+    renderUnderLocale("en-US", livingSpaceField({ format: "unit", unit: "m2", locale: "de-DE" }));
+    expect(captured?.children).toBe("58 m²");
+  });
+});
+
+describe("RenderField — App-Locale an FieldRendererOutput durchreichen (fw#2187)", () => {
+  test("number-FormatSpec ohne eigenes locale bekommt das App-Locale (de-DE, Komma statt Punkt)", () => {
+    renderUnderLocale("de-DE", livingSpaceField({ format: "number" }, 1234.5));
+    expect(captured?.children).toBe("1.234,5");
+  });
+});

package/src/components/render-field.tsx

@@ -106,6 +106,7 @@ export function RenderField({
       <FieldRendererOutput
         field={field}
         renderer={field.renderer}
+        appLocale={appLocale}
         {...(row !== undefined && { row })}
       />
     ) : field.type === "embedded" && field.embeddedListCells !== undefined ? (
@@ -340,10 +341,12 @@ function FieldRendererOutput({
   field,
   renderer,
   row,
+  appLocale,
 }: {
   readonly field: EditFieldViewModel;
   readonly renderer: FieldRenderer;
   readonly row?: Readonly<Record<string, unknown>>;
+  readonly appLocale: string;
 }): ReactNode {
   const { Text } = usePrimitives();
   const componentName =
@@ -352,8 +355,16 @@ function FieldRendererOutput({
       : undefined;
   const Component = useColumnRenderer(componentName);
   if (isFormatSpec(renderer)) {
+    // App locale as default when the FormatSpec declares none of its own —
+    // otherwise locale-sensitive formats (timestamp/date/number/decimal/
+    // bigInt/unit) fell back to Intl's runtime default instead of the app
+    // language chosen via LocaleProvider (fw#2187). An explicit
+    // `renderer.locale` still wins, same pattern as dateLocale vs. appLocale
+    // further below in readOnlyDisplayText.
     return (
-      <Text testId={`field-value-${field.field}`}>{applyFormatSpec(renderer, field.value)}</Text>
+      <Text testId={`field-value-${field.field}`}>
+        {applyFormatSpec({ locale: appLocale, ...renderer }, field.value)}
+      </Text>
     );
   }
   if (componentName !== undefined) {

package/src/i18n.tsx

@@ -1,19 +1,18 @@
-// Locale-Handling für React-Consumer des Kumiko-Renderers. Eine dünne
-// Schicht um den platform-agnostischen `LocaleResolver`-Contract aus
-// @cosmicdrift/kumiko-headless: Provider, Hooks, Default-Noop-Resolver und ein
-// Fallback-Bundle-Merge für Feature-gelieferte Translations.
+// Locale handling for React consumers of the Kumiko renderer. A thin layer
+// around the platform-agnostic `LocaleResolver` contract from
+// @cosmicdrift/kumiko-headless: provider, hooks, a default no-op resolver,
+// and a fallback-bundle merge for feature-supplied translations.
 //
-// Architektur-Idee:
-//   1. App liefert genau einen `LocaleResolver` über `<LocaleProvider>`
-//      (oder überhaupt keinen → Default-Resolver returnt keys as-is).
-//   2. Feature-Plugins dürfen Fallback-Bundles mitbringen: wenn der
-//      App-Resolver einen Key nicht auflöst, probiert `useTranslation`
-//      die Plugin-Bundles. Das hält Feature-UI unabhängig von der
-//      App-seitigen i18next-Instanz und funktioniert out-of-the-box,
-//      bleibt aber vollständig overridbar.
-//   3. Re-Render bei Locale-Wechsel via `useSyncExternalStore` auf
-//      dem Resolver's `subscribe()` — App-Code kann mitten in der
-//      Session die Sprache umschalten ohne Reload.
+// Architecture:
+//   1. The app supplies exactly one `LocaleResolver` via `<LocaleProvider>`
+//      (or none at all → the default resolver returns keys as-is).
+//   2. Feature plugins may bring fallback bundles: when the app resolver
+//      can't resolve a key, `useTranslation` tries the plugin bundles.
+//      This keeps feature UI independent of the app's own i18next instance
+//      and works out of the box, while staying fully overridable.
+//   3. Re-render on locale change via `useSyncExternalStore` on the
+//      resolver's `subscribe()` — app code can switch language mid-session
+//      without a reload.
 
 import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
 import {
@@ -78,14 +77,13 @@ const EMPTY_FALLBACK_BUNDLES: readonly TranslationsByLocale[] = [];
 
 export type LocaleProviderProps = {
   readonly resolver: LocaleResolver;
-  /** Von Feature-Plugins gelieferte Default-Bundles. Lookup-Reihenfolge
-   *  pro Key: (1) App-Resolver, (2) diese Bundles in Array-Order,
-   *  (3) Key as-is. Apps können somit einzelne Keys overriden ohne
-   *  ganze Feature-Bundles austauschen zu müssen. */
+  /** Default bundles supplied by feature plugins. Lookup order per key:
+   *  (1) app resolver, (2) these bundles in array order, (3) key as-is.
+   *  Apps can thus override individual keys without swapping out whole
+   *  feature bundles. */
   readonly fallbackBundles?: readonly TranslationsByLocale[];
-  /** Auf den fallbackLocale wird zurückgegriffen, wenn weder der
-   *  current-locale- noch der key-Lookup im Plugin-Bundle greift.
-   *  Default: `"en"`. */
+  /** Falls back to fallbackLocale when neither the current-locale nor the
+   *  key lookup hits in a plugin bundle. Default: `"en"`. */
   readonly fallbackLocale?: string;
   readonly children: ReactNode;
 };
@@ -96,12 +94,12 @@ export function LocaleProvider({
   fallbackLocale = "en",
   children,
 }: LocaleProviderProps): ReactNode {
-  // Ohne Memoization baut jeder Re-Render des Providers (z.B. weil ein
-  // Ahnen-Component neu rendert) ein neues Context-Value-Objekt — jeder
-  // Consumer von useTranslation()/useLocale() sieht dann eine neue `ctx`-
-  // Referenz und damit selbst mit useCallback-Memoization einen neuen `t`.
-  // Konsequenz: `t` in einem useEffect-Dependency-Array triggert einen
-  // Endlos-Loop (siehe admin-shell Overview-Screens, Prod-Incident).
+  // Without memoization every re-render of the provider (e.g. because an
+  // ancestor component re-renders) builds a new context-value object —
+  // every consumer of useTranslation()/useLocale() then sees a new `ctx`
+  // reference and, even with useCallback memoization, a new `t`.
+  // Consequence: `t` in a useEffect dependency array triggers an infinite
+  // loop (see admin-shell Overview screens, prod incident).
   const value = useMemo(
     () => ({ resolver, fallbackBundles, fallbackLocale }),
     [resolver, fallbackBundles, fallbackLocale],