@carlonicora/nextjs-jsonapi 4.1.1 → 4.2.0

package/src/shadcnui/custom/multi-select.tsx

@@ -18,6 +18,7 @@ import {
 } from "../ui/command";
 import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover";
 import { Separator } from "../ui/separator";
+import { useUiText } from "../ui/use-ui-text";
 
 /**
  * Variants for the multi-select component to handle different styles.
@@ -91,10 +92,25 @@ interface MultiSelectProps
 
   /**
    * Placeholder text to be displayed when no values are selected.
-   * Optional, defaults to "Select options".
+   * Optional, defaults to `ui.labels.select_options`, else "Select options".
    */
   placeholder?: string;
 
+  /** Placeholder of the search input. Defaults to `ui.search.placeholder_global`, else "Search...". */
+  searchPlaceholder?: string;
+
+  /** Text of the select-all row. Defaults to `ui.labels.select_all`, else "(Select All)". */
+  selectAllLabel?: string;
+
+  /** Text of the clear row. Defaults to `ui.buttons.clear`, else "Clear". */
+  clearLabel?: string;
+
+  /** Text of the close row. Defaults to `ui.labels.close`, else "Close". */
+  closeLabel?: string;
+
+  /** Text of the overflow badge. Defaults to `ui.labels.more_count`, else "+ {count} more". */
+  formatMoreLabel?: (count: number) => string;
+
   /**
    * Animation duration in seconds for the visual effects (e.g., bouncing badges).
    * Optional, defaults to 0 (no animation).
@@ -134,13 +150,13 @@ interface MultiSelectProps
 
   /**
    * Text to display when loading.
-   * Optional, defaults to "Searching...".
+   * Optional, defaults to `ui.labels.searching`, else "Searching...".
    */
   loadingText?: string;
 
   /**
    * Text to display when no results are found.
-   * Optional, defaults to "No results found.".
+   * Optional, defaults to `ui.search.no_results_found`, else "No results found.".
    */
   emptyText?: string;
 
@@ -166,21 +182,38 @@ export const MultiSelect = React.forwardRef<HTMLButtonElement, MultiSelectProps>
       variant,
       defaultValue = [],
       value,
-      placeholder = "Select options",
+      placeholder: placeholderProp,
       animation = 0,
       maxCount = 3,
       modalPopover = false,
       className,
       onSearchChange,
       loading = false,
-      loadingText = "Searching...",
-      emptyText = "No results found.",
+      loadingText: loadingTextProp,
+      emptyText: emptyTextProp,
+      searchPlaceholder: searchPlaceholderProp,
+      selectAllLabel: selectAllLabelProp,
+      clearLabel: clearLabelProp,
+      closeLabel: closeLabelProp,
+      formatMoreLabel,
       hideSelectAll = false,
       isOptionSelected,
       ...props
     },
     _ref,
   ) => {
+    // Chrome text: an explicit prop wins, else the app's translation, else English.
+    const uiText = useUiText();
+    const placeholder = placeholderProp ?? uiText("ui.labels.select_options", "Select options");
+    const loadingText = loadingTextProp ?? uiText("ui.labels.searching", "Searching...");
+    const emptyText = emptyTextProp ?? uiText("ui.search.no_results_found", "No results found.");
+    const searchPlaceholder = searchPlaceholderProp ?? uiText("ui.search.placeholder_global", "Search...");
+    const selectAllLabel = selectAllLabelProp ?? uiText("ui.labels.select_all", "(Select All)");
+    const clearLabel = clearLabelProp ?? uiText("ui.buttons.clear", "Clear");
+    const closeLabel = closeLabelProp ?? uiText("ui.labels.close", "Close");
+    const moreLabel = (count: number) =>
+      formatMoreLabel ? formatMoreLabel(count) : uiText("ui.labels.more_count", "+ {count} more", { count });
+
     // Using internal state only if value prop is not provided (uncontrolled mode)
     const [internalSelectedValues, setInternalSelectedValues] = React.useState<string[]>(defaultValue);
 
@@ -331,7 +364,7 @@ export const MultiSelect = React.forwardRef<HTMLButtonElement, MultiSelectProps>
                     )}
                     style={{ animationDuration: `${animation}s` }}
                   >
-                    {`+ ${selectedValues.length - maxCount} more`}
+                    {moreLabel(selectedValues.length - maxCount)}
                     <XCircle
                       data-remove-button
                       className="ms-2 h-4 w-4 cursor-pointer"
@@ -381,7 +414,7 @@ export const MultiSelect = React.forwardRef<HTMLButtonElement, MultiSelectProps>
           <Command filter={commandFilterByKeywords}>
             <CommandInput
               autoFocus
-              placeholder="Search..."
+              placeholder={searchPlaceholder}
               onKeyDown={handleInputKeyDown}
               onValueChange={onSearchChange}
             />
@@ -397,7 +430,7 @@ export const MultiSelect = React.forwardRef<HTMLButtonElement, MultiSelectProps>
                   <CommandItem
                     key="all"
                     value={SELECT_ALL_VALUE}
-                    keywords={["(Select All)"]}
+                    keywords={[selectAllLabel]}
                     onSelect={toggleAll}
                     className="cursor-pointer hover:bg-muted data-selected:hover:bg-muted bg-transparent data-selected:bg-transparent"
                   >
@@ -411,7 +444,7 @@ export const MultiSelect = React.forwardRef<HTMLButtonElement, MultiSelectProps>
                     >
                       <CheckIcon className="h-4 w-4" />
                     </div>
-                    <span>(Select All)</span>
+                    <span>{selectAllLabel}</span>
                   </CommandItem>
                 )}
                 {options.map((option) => {
@@ -449,22 +482,22 @@ export const MultiSelect = React.forwardRef<HTMLButtonElement, MultiSelectProps>
                     <>
                       <CommandItem
                         value={CLEAR_VALUE}
-                        keywords={["Clear"]}
+                        keywords={[clearLabel]}
                         onSelect={handleClear}
                         className="flex-1 cursor-pointer justify-center"
                       >
-                        Clear
+                        {clearLabel}
                       </CommandItem>
                       <Separator orientation="vertical" className="flex h-full min-h-6" />
                     </>
                   )}
                   <CommandItem
                     value={CLOSE_VALUE}
-                    keywords={["Close"]}
+                    keywords={[closeLabel]}
                     onSelect={() => setIsPopoverOpen(false)}
                     className="max-w-full flex-1 cursor-pointer justify-center hover:bg-muted data-selected:hover:bg-muted bg-transparent data-selected:bg-transparent"
                   >
-                    Close
+                    {closeLabel}
                   </CommandItem>
                 </div>
               </CommandGroup>

package/src/shadcnui/custom/multiple-selector.tsx

@@ -9,6 +9,7 @@ import { forwardRef, useEffect } from "react";
 import { cn } from "../../utils/cn";
 import { Badge } from "../ui/badge";
 import { Command, CommandGroup, CommandItem, CommandList, commandFilterByKeywords } from "../ui/command";
+import { useUiText } from "../ui/use-ui-text";
 
 export interface Option {
   value: string;
@@ -58,6 +59,10 @@ export interface MultipleSelectorProps {
   onMaxSelected?: (maxLimit: number) => void;
   /** Hide the placeholder when there are options selected. */
   hidePlaceholderWhenSelected?: boolean;
+  /** Text of the creatable row. Defaults to `ui.labels.create_option`, else `Create "{value}"`. */
+  formatCreateLabel?: (value: string) => string;
+  /** Text of the overflow badge. Defaults to `ui.labels.more_count`, else "+{count} more". */
+  formatMoreLabel?: (count: number) => string;
   disabled?: boolean;
   /** Group the options base on provided key. */
   groupBy?: string;
@@ -204,6 +209,8 @@ const MultipleSelector = React.forwardRef<MultipleSelectorRef, MultipleSelectorP
       maxSelected = Number.MAX_SAFE_INTEGER,
       onMaxSelected,
       hidePlaceholderWhenSelected,
+      formatCreateLabel,
+      formatMoreLabel,
       disabled,
       groupBy,
       className,
@@ -220,6 +227,7 @@ const MultipleSelector = React.forwardRef<MultipleSelectorRef, MultipleSelectorP
     }: MultipleSelectorProps,
     ref: React.Ref<MultipleSelectorRef>,
   ) => {
+    const uiText = useUiText();
     const inputRef = React.useRef<HTMLInputElement>(null);
     const containerRef = React.useRef<HTMLDivElement>(null);
     const [open, setOpen] = React.useState(false);
@@ -431,7 +439,9 @@ const MultipleSelector = React.forwardRef<MultipleSelectorRef, MultipleSelectorP
             onChange?.(newOptions);
           }}
         >
-          {`Create "${inputValue}"`}
+          {formatCreateLabel
+            ? formatCreateLabel(inputValue)
+            : uiText("ui.labels.create_option", 'Create "{value}"', { value: inputValue })}
         </CommandItem>
       );
 
@@ -547,7 +557,9 @@ const MultipleSelector = React.forwardRef<MultipleSelectorRef, MultipleSelectorP
             })}
             {hiddenCount > 0 && (
               <Badge className={cn("bg-transparent text-foreground hover:bg-transparent", badgeClassName)}>
-                {`+${hiddenCount} more`}
+                {formatMoreLabel
+                  ? formatMoreLabel(hiddenCount)
+                  : uiText("ui.labels.more_count", "+{count} more", { count: hiddenCount })}
               </Badge>
             )}
             <CommandPrimitive.Input

package/src/shadcnui/ui/__tests__/use-ui-text.test.tsx

@@ -0,0 +1,76 @@
+import { render, renderHook, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { configureI18n, type I18nConfig } from "../../../i18n/config";
+import { Spinner } from "../spinner";
+import { useUiText } from "../use-ui-text";
+
+const catalogue: Record<string, string> = {
+  "ui.labels.loading": "Caricamento",
+  "ui.labels.more_count": "+{count} altri",
+};
+
+/** A next-intl-shaped `t`: `has` probes, missing keys come back as the key path. */
+function useCatalogueTranslations() {
+  const t = (key: string, values?: Record<string, unknown>) =>
+    (catalogue[key] ?? key).replace(/\{(\w+)\}/g, (match, name: string) =>
+      values && name in values ? String(values[name]) : match,
+    );
+  (t as unknown as { has: (key: string) => boolean }).has = (key: string) => key in catalogue;
+  return t;
+}
+
+function configure(useTranslations: I18nConfig["useTranslations"]) {
+  configureI18n({ useTranslations } as unknown as I18nConfig);
+}
+
+afterEach(() => {
+  configureI18n(null as unknown as I18nConfig);
+});
+
+describe("useUiText", () => {
+  it("returns the English fallback when i18n is not configured", () => {
+    const { result } = renderHook(() => useUiText());
+    expect(result.current("ui.labels.close", "Close")).toBe("Close");
+    expect(result.current("ui.labels.more_count", "+ {count} more", { count: 2 })).toBe("+ 2 more");
+  });
+
+  it("returns the app's translation when the key exists", () => {
+    configure(useCatalogueTranslations);
+    const { result } = renderHook(() => useUiText());
+    expect(result.current("ui.labels.loading", "Loading")).toBe("Caricamento");
+    expect(result.current("ui.labels.more_count", "+ {count} more", { count: 3 })).toBe("+3 altri");
+  });
+
+  it("returns the English fallback when the app lacks the key", () => {
+    configure(useCatalogueTranslations);
+    const { result } = renderHook(() => useUiText());
+    expect(result.current("ui.labels.close", "Close")).toBe("Close");
+  });
+
+  it("returns the English fallback when a has-less t hands back the key path or throws", () => {
+    configure(() => (key: string) => key);
+    expect(renderHook(() => useUiText()).result.current("ui.labels.close", "Close")).toBe("Close");
+
+    configure(() => () => {
+      throw new Error("missing");
+    });
+    expect(renderHook(() => useUiText()).result.current("ui.labels.close", "Close")).toBe("Close");
+  });
+});
+
+describe("Spinner label", () => {
+  it("announces the translated label, and an explicit aria-label still wins", () => {
+    configure(useCatalogueTranslations);
+    const { unmount } = render(<Spinner />);
+    expect(screen.getByRole("status")).toHaveAttribute("aria-label", "Caricamento");
+    unmount();
+
+    render(<Spinner aria-label="Saving" />);
+    expect(screen.getByRole("status")).toHaveAttribute("aria-label", "Saving");
+  });
+
+  it("keeps the English label when i18n is not configured", () => {
+    render(<Spinner />);
+    expect(screen.getByRole("status")).toHaveAttribute("aria-label", "Loading");
+  });
+});

package/src/shadcnui/ui/breadcrumb.tsx

@@ -66,7 +66,14 @@ function BreadcrumbSeparator({ children, className, ...props }: React.ComponentP
   );
 }
 
-function BreadcrumbEllipsis({ className, ...props }: React.ComponentProps<"span">) {
+function BreadcrumbEllipsis({
+  className,
+  label = "More",
+  ...props
+}: React.ComponentProps<"span"> & {
+  /** Screen-reader text. Plain prop (no lookup): this file has no "use client" and may render on the server. */
+  label?: string;
+}) {
   return (
     <span
       data-slot="breadcrumb-ellipsis"
@@ -76,7 +83,7 @@ function BreadcrumbEllipsis({ className, ...props }: React.ComponentProps<"span"
       {...props}
     >
       <MoreHorizontalIcon />
-      <span className="sr-only">More</span>
+      <span className="sr-only">{label}</span>
     </span>
   );
 }

package/src/shadcnui/ui/carousel.tsx

@@ -7,6 +7,7 @@ import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
 import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 import { useDir } from "../../contexts/DirectionContext";
+import { useUiText } from "./use-ui-text";
 
 type CarouselApi = UseEmblaCarouselType[1];
 type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
@@ -162,9 +163,14 @@ function CarouselPrevious({
   className,
   variant = "outline",
   size = "icon-sm",
+  label,
   ...props
-}: React.ComponentProps<typeof Button>) {
+}: React.ComponentProps<typeof Button> & {
+  /** Screen-reader name. Defaults to `ui.labels.previous_slide`, else "Previous slide". */
+  label?: string;
+}) {
   const { orientation, scrollPrev, canScrollPrev } = useCarousel();
+  const uiText = useUiText();
 
   return (
     <Button
@@ -184,7 +190,7 @@ function CarouselPrevious({
       {...props}
     >
       <ChevronLeftIcon className={orientation === "horizontal" ? "rtl:rotate-180" : undefined} />
-      <span className="sr-only">Previous slide</span>
+      <span className="sr-only">{label ?? uiText("ui.labels.previous_slide", "Previous slide")}</span>
     </Button>
   );
 }
@@ -193,9 +199,14 @@ function CarouselNext({
   className,
   variant = "outline",
   size = "icon-sm",
+  label,
   ...props
-}: React.ComponentProps<typeof Button>) {
+}: React.ComponentProps<typeof Button> & {
+  /** Screen-reader name. Defaults to `ui.labels.next_slide`, else "Next slide". */
+  label?: string;
+}) {
   const { orientation, scrollNext, canScrollNext } = useCarousel();
+  const uiText = useUiText();
 
   return (
     <Button
@@ -215,7 +226,7 @@ function CarouselNext({
       {...props}
     >
       <ChevronRightIcon className={orientation === "horizontal" ? "rtl:rotate-180" : undefined} />
-      <span className="sr-only">Next slide</span>
+      <span className="sr-only">{label ?? uiText("ui.labels.next_slide", "Next slide")}</span>
     </Button>
   );
 }

package/src/shadcnui/ui/dialog.tsx

@@ -6,6 +6,7 @@ import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
 import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
 import { XIcon } from "lucide-react";
+import { useUiText } from "./use-ui-text";
 
 function Dialog({ ...props }: DialogPrimitive.Root.Props) {
   return <DialogPrimitive.Root data-slot="dialog" {...props} />;
@@ -40,10 +41,14 @@ function DialogContent({
   className,
   children,
   showCloseButton = true,
+  closeLabel,
   ...props
 }: DialogPrimitive.Popup.Props & {
   showCloseButton?: boolean;
+  /** Screen-reader name of the close button. Defaults to `ui.labels.close`, else "Close". */
+  closeLabel?: string;
 }) {
+  const uiText = useUiText();
   return (
     <DialogPortal>
       <DialogOverlay />
@@ -65,7 +70,7 @@ function DialogContent({
             render={<Button variant="ghost" className="absolute top-2 end-2" size="icon-sm" />}
           >
             <XIcon />
-            <span className="sr-only">Close</span>
+            <span className="sr-only">{closeLabel ?? uiText("ui.labels.close", "Close")}</span>
           </DialogPrimitive.Close>
         )}
       </DialogPrimitive.Popup>
@@ -80,11 +85,15 @@ function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
 function DialogFooter({
   className,
   showCloseButton = false,
+  closeLabel,
   children,
   ...props
 }: React.ComponentProps<"div"> & {
   showCloseButton?: boolean;
+  /** Text of the footer close button. Defaults to `ui.labels.close`, else "Close". */
+  closeLabel?: string;
 }) {
+  const uiText = useUiText();
   return (
     <div
       data-slot="dialog-footer"
@@ -92,7 +101,11 @@ function DialogFooter({
       {...props}
     >
       {children}
-      {showCloseButton && <DialogPrimitive.Close render={<Button variant="outline" />}>Close</DialogPrimitive.Close>}
+      {showCloseButton && (
+        <DialogPrimitive.Close render={<Button variant="outline" />}>
+          {closeLabel ?? uiText("ui.labels.close", "Close")}
+        </DialogPrimitive.Close>
+      )}
     </div>
   );
 }

package/src/shadcnui/ui/sheet.tsx

@@ -8,6 +8,7 @@ import { resolvePhysicalSide, type LogicalSide } from "@/lib/direction";
 import { Button } from "@/components/ui/button";
 import { XIcon } from "lucide-react";
 import { useDir } from "../../contexts/DirectionContext";
+import { useUiText } from "./use-ui-text";
 
 function Sheet({ ...props }: SheetPrimitive.Root.Props) {
   return <SheetPrimitive.Root data-slot="sheet" {...props} />;
@@ -44,12 +45,16 @@ function SheetContent({
   // Logical default: identical to "right" in LTR, mirrors to the left in RTL.
   side = "end",
   showCloseButton = true,
+  closeLabel,
   ...props
 }: SheetPrimitive.Popup.Props & {
   side?: LogicalSide;
   showCloseButton?: boolean;
+  /** Screen-reader name of the close button. Defaults to `ui.labels.close`, else "Close". */
+  closeLabel?: string;
 }) {
   const dir = useDir();
+  const uiText = useUiText();
   const physicalSide = resolvePhysicalSide(side, dir);
 
   return (
@@ -85,7 +90,7 @@ function SheetContent({
             }
           >
             <XIcon />
-            <span className="sr-only">Close</span>
+            <span className="sr-only">{closeLabel ?? uiText("ui.labels.close", "Close")}</span>
           </SheetPrimitive.Close>
         )}
       </SheetPrimitive.Popup>

package/src/shadcnui/ui/sidebar.tsx

@@ -16,6 +16,7 @@ import { resolvePhysicalSide } from "@/lib/direction";
 import { cn } from "@/lib/utils";
 import { PanelLeftIcon } from "lucide-react";
 import { useDir } from "../../contexts/DirectionContext";
+import { useUiText } from "./use-ui-text";
 import type { SessionSnapshot } from "../../server/ServerSession";
 import { mapThenable } from "../../utils/map-thenable";
 import { getViewportContext } from "../../utils/use-mobile";
@@ -262,6 +263,7 @@ function Sidebar({
 }) {
   const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
   const dir = useDir();
+  const uiText = useUiText();
   // Logical "start"/"end" is resolved once, here. Everything downstream
   // (data-side, the positioning ternaries, the mobile SheetContent) consumes
   // the resolved PHYSICAL side, so "left"/"right" callers are unchanged.
@@ -295,8 +297,10 @@ function Sidebar({
           side={side}
         >
           <SheetHeader className="sr-only">
-            <SheetTitle>Sidebar</SheetTitle>
-            <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+            <SheetTitle>{uiText("ui.labels.sidebar", "Sidebar")}</SheetTitle>
+            <SheetDescription>
+              {uiText("ui.labels.sidebar_description", "Displays the mobile sidebar.")}
+            </SheetDescription>
           </SheetHeader>
           <div className="flex h-full w-full flex-col">{children}</div>
         </SheetContent>
@@ -352,8 +356,21 @@ function Sidebar({
   );
 }
 
-function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<typeof Button>) {
+function SidebarTrigger({
+  className,
+  onClick,
+  label,
+  ...props
+}: React.ComponentProps<typeof Button> & {
+  /**
+   * Accessible name of the toggle. Falls back to an explicit `aria-label`, then
+   * `ui.labels.toggle_sidebar`, then "Toggle Sidebar".
+   */
+  label?: string;
+}) {
   const { toggleSidebar } = useSidebar();
+  const uiText = useUiText();
+  const text = label ?? props["aria-label"] ?? uiText("ui.labels.toggle_sidebar", "Toggle Sidebar");
 
   return (
     <Button
@@ -369,22 +386,31 @@ function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<t
       {...props}
     >
       <PanelLeftIcon className="rtl:rotate-180" />
-      <span className="sr-only">Toggle Sidebar</span>
+      <span className="sr-only">{text}</span>
     </Button>
   );
 }
 
-function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
+function SidebarRail({
+  className,
+  label,
+  ...props
+}: React.ComponentProps<"button"> & {
+  /** Accessible name and tooltip of the rail. Defaults to `ui.labels.toggle_sidebar`, else "Toggle Sidebar". */
+  label?: string;
+}) {
   const { toggleSidebar } = useSidebar();
+  const uiText = useUiText();
+  const text = label ?? uiText("ui.labels.toggle_sidebar", "Toggle Sidebar");
 
   return (
     <button
       data-sidebar="rail"
       data-slot="sidebar-rail"
-      aria-label="Toggle Sidebar"
+      aria-label={text}
       tabIndex={-1}
       onClick={toggleSidebar}
-      title="Toggle Sidebar"
+      title={text}
       className={cn(
         // rtl-ok: the whole rail block is keyed to the resolved physical side
         "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] sm:flex", // rtl-ok: keyed to resolved physical side

package/src/shadcnui/ui/spinner.tsx

@@ -1,8 +1,11 @@
+"use client";
+
 import { cva, type VariantProps } from "class-variance-authority";
 import { Loader2Icon } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "@/lib/utils";
+import { useUiText } from "./use-ui-text";
 
 const spinnerVariants = cva("animate-spin", {
   variants: {
@@ -22,11 +25,13 @@ function Spinner({
   size,
   ...props
 }: React.ComponentProps<typeof Loader2Icon> & VariantProps<typeof spinnerVariants>) {
+  // An explicit `aria-label` in `props` is spread below and wins over this.
+  const uiText = useUiText();
   return (
     <Loader2Icon
       data-slot="spinner"
       role="status"
-      aria-label="Loading"
+      aria-label={uiText("ui.labels.loading", "Loading")}
       className={cn(spinnerVariants({ size, className }))}
       {...props}
     />

package/src/shadcnui/ui/use-ui-text.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import { useCallback } from "react";
+import { useI18nTranslations } from "../../i18n/config";
+
+/** The injected `t`, plus next-intl's optional non-throwing `has` probe. */
+type Translate = ((key: string, values?: Record<string, unknown>) => string) & {
+  has?: (key: string) => boolean;
+};
+
+/** Fills `{name}` placeholders in an English fallback. */
+function interpolate(text: string, values?: Record<string, unknown>): string {
+  if (!values) return text;
+  return text.replace(/\{(\w+)\}/g, (match, name: string) => (name in values ? String(values[name]) : match));
+}
+
+/**
+ * Chrome text for the shadcnui primitives (the "Close" behind a dialog's X,
+ * the sidebar toggle's label, a multi-select's "Search..."), in the active
+ * language.
+ *
+ * The primitives stay framework-agnostic: they never import next-intl. This
+ * reads the `useTranslations` the host app passed to `configureI18n()`, and
+ * returns the English `fallback` whenever that cannot produce the text — i18n
+ * not configured, the app has no such key, or the lookup throws. An app that
+ * never defines the key therefore renders exactly what it rendered before.
+ *
+ * Every primitive that uses this also takes an explicit label prop; a value
+ * passed there always wins over the lookup.
+ */
+export function useUiText(): (key: string, fallback: string, values?: Record<string, unknown>) => string {
+  const t = useI18nTranslations() as Translate;
+
+  return useCallback(
+    (key: string, fallback: string, values?: Record<string, unknown>): string => {
+      if (typeof t.has === "function" && !t.has(key)) return interpolate(fallback, values);
+      try {
+        const text = t(key, values);
+        // The unconfigured fallback, and next-intl's default for a missing
+        // key, both hand back the key path itself.
+        if (!text || text === key || text.endsWith(`.${key}`)) return interpolate(fallback, values);
+        return text;
+      } catch {
+        return interpolate(fallback, values);
+      }
+    },
+    [t],
+  );
+}

package/src/utils/__tests__/date-formatter.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { formatDate, FormatOption } from "../date-formatter";
+import { dateFormatLocale, formatDate, FormatOption } from "../date-formatter";
 
 describe("formatDate", () => {
   beforeEach(() => {
@@ -158,4 +158,27 @@ describe("formatDate", () => {
       expect(result).toBe("15/06/2024");
     });
   });
+
+  describe("timeSince in other languages", () => {
+    it("keeps the English wording for en-GB", () => {
+      expect(formatDate(new Date("2024-06-15T09:00:00Z"), "timeSince", "en-GB")).toBe("3 hours ago");
+    });
+
+    it("uses the locale's relative-time wording for Italian", () => {
+      expect(formatDate(new Date("2024-06-15T09:00:00Z"), "timeSince", "it")).toBe("3 ore fa");
+      expect(formatDate(new Date("2024-06-15T11:59:30Z"), "timeSince", "it")).toBe("30 secondi fa");
+    });
+  });
+
+  describe("dateFormatLocale", () => {
+    it("maps English and missing locales to en-GB", () => {
+      expect(dateFormatLocale("en")).toBe("en-GB");
+      expect(dateFormatLocale("en-US")).toBe("en-GB");
+      expect(dateFormatLocale(undefined)).toBe("en-GB");
+    });
+
+    it("passes other locales through", () => {
+      expect(dateFormatLocale("it")).toBe("it");
+    });
+  });
 });