feat(ui): i18n string layer + MessagesProvider

Break every string a component renders itself (labels, placeholders, ARIA
names, status text) out of the components into a default English dictionary
(src/i18n/messages.ts), read via useMessages(). Consumers translate the catalog
by wrapping in <MessagesProvider messages={locale}> — a PartialMessages dict
deep-merged (two levels) over the defaults. Explicit props (e.g. AppNav
searchPlaceholder, AiActions title) still override per-instance.

Wired: AppNav, MobileNav, SectionTabs, Sidebar, TableOfContents, CodeBlock/
CopyButton, AiActions, SupportMatrix, StatusBadge. Exues MessagesProvider,
useMessages, defaultMessages, Messages, PartialMessages.

Also: the nav search placeholder default is now "Search or ask" (was
"Search or ask AI…").

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: sgammon

packages/ui/src/components/ai-actions.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { Check, Copy, ExternalLink, Sparkles } from "lucide-react";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * AiActions — the "Use with AI" panel in the docs right rail: copy the page as
@@ -27,12 +28,13 @@ const itemClass =
   "flex items-center gap-2 rounded-lg border border-border bg-muted px-2.5 py-2 text-left text-[12.5px] font-medium text-foreground no-underline transition-colors hover:bg-accent";
 
 export function AiActions({
-  title = "Use with AI",
+  title,
   markdown,
   actions = [],
   className,
   ...props
 }: AiActionsProps) {
+  const m = useMessages();
   const [copied, setCopied] = React.useState(false);
 
   return (
@@ -42,7 +44,7 @@ export function AiActions({
     >
       <div className="mb-0.5 flex items-center gap-1.5 font-mono text-[11px] font-semibold tracking-wider text-subtle-foreground uppercase">
         <Sparkles aria-hidden className="h-[13px] w-[13px] text-[var(--primary-emphasis)]" />
-        {title}
+        {title ?? m.aiActions.title}
       </div>
 
       {markdown ? (
@@ -62,7 +64,7 @@ export function AiActions({
           ) : (
             <Copy aria-hidden className="h-3.5 w-3.5 shrink-0" />
           )}
-          {copied ? "Copied" : "Copy as Markdown"}
+          {copied ? m.aiActions.copied : m.aiActions.copyAsMarkdown}
         </button>
       ) : null}
 

packages/ui/src/components/app-nav.tsx

@@ -3,6 +3,7 @@ import { ChevronDown, Globe, History, Search, Sparkles, Sun } from "lucide-react
 import { cn } from "../lib/utils";
 import { Button } from "./button";
 import { ElideLogo } from "./elide-logo";
+import { useMessages } from "../i18n/provider";
 
 /**
  * AppNav — the 56px top nav bar present on every docs page: brand + "DOCS"
@@ -36,7 +37,7 @@ const defaultLogo = <ElideLogo />;
 export function AppNav({
   links,
   logo,
-  searchPlaceholder = "Search or ask AI…",
+  searchPlaceholder,
   locale = "EN",
   installHref = "/install",
   changelogHref = "/changelog",
@@ -46,9 +47,10 @@ export function AppNav({
   className,
   ...props
 }: AppNavProps) {
+  const m = useMessages();
   return (
     <nav
-      aria-label="Main navigation"
+      aria-label={m.appNav.navLabel}
       className={cn(
         "flex h-14 items-center gap-[18px] border-b border-border px-[22px] backdrop-blur-xl [background:var(--nav-background)]",
         className,
@@ -58,7 +60,7 @@ export function AppNav({
       <div className="flex items-center gap-2">
         {logo ?? defaultLogo}
         <span className="rounded-md border border-border-strong px-[7px] py-0.5 font-mono text-[10px] font-semibold tracking-wider text-muted-foreground">
-          DOCS
+          {m.appNav.docsBadge}
         </span>
       </div>
 
@@ -87,11 +89,11 @@ export function AppNav({
       <button
         type="button"
         onClick={onSearchClick}
-        aria-label="Search"
+        aria-label={m.appNav.searchLabel}
         className="flex h-[34px] w-[280px] items-center gap-2 rounded-[9px] border border-border bg-muted px-3 text-subtle-foreground transition-colors hover:border-border-strong"
       >
         <Search aria-hidden className="h-[15px] w-[15px] shrink-0" />
-        <span className="flex-1 text-left text-[13px]">{searchPlaceholder}</span>
+        <span className="flex-1 text-left text-[13px]">{searchPlaceholder ?? m.appNav.searchPlaceholder}</span>
         <Sparkles aria-hidden className="h-[13px] w-[13px] shrink-0 text-primary" />
         <kbd className="rounded-[5px] border border-border-strong px-1.5 py-px font-mono text-[11px] font-medium">
           ⌘K
@@ -101,7 +103,7 @@ export function AppNav({
       <button
         type="button"
         onClick={onThemeToggle}
-        aria-label="Toggle theme"
+        aria-label={m.appNav.toggleTheme}
         className="flex h-[34px] w-[34px] items-center justify-center rounded-[9px] border border-border text-muted-foreground transition-colors hover:bg-[var(--hover)] hover:text-foreground"
       >
         <Sun aria-hidden className="h-4 w-4" />
@@ -110,7 +112,7 @@ export function AppNav({
       <button
         type="button"
         onClick={onLocaleClick}
-        aria-label="Language"
+        aria-label={m.appNav.language}
         className="flex h-[34px] items-center gap-1.5 rounded-[9px] border border-border px-[11px] text-[12.5px] font-medium text-muted-foreground transition-colors hover:bg-[var(--hover)] hover:text-foreground"
       >
         <Globe aria-hidden className="h-[15px] w-[15px]" />
@@ -120,11 +122,11 @@ export function AppNav({
 
       <Button variant="changelog" size="sm" render={<a href={changelogHref} />}>
         <History aria-hidden className="h-[15px] w-[15px]" />
-        Changelog
+        {m.appNav.changelog}
       </Button>
 
       <Button variant="gradient" size="sm" render={<a href={installHref} />}>
-        Install
+        {m.appNav.install}
       </Button>
     </nav>
   );

packages/ui/src/components/code-block.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import { Check, Copy } from "lucide-react";
 import { Highlight, type PrismTheme } from "prism-react-renderer";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * CopyButton — copies `value` to the clipboard, flips to a check for 1.5s.
@@ -10,17 +11,19 @@ import { cn } from "../lib/utils";
 export function CopyButton({
   value,
   className,
-  label = "Copy",
+  label,
 }: {
   value: string;
   className?: string;
+  /** Visible label; omit or pass "" for an icon-only button. Defaults to the localized "Copy". */
   label?: string;
 }) {
+  const m = useMessages();
   const [copied, setCopied] = React.useState(false);
   return (
     <button
       type="button"
-      aria-label={copied ? "Copied" : label || "Copy"}
+      aria-label={copied ? m.codeBlock.copied : label || m.codeBlock.copy}
       onClick={() => {
         // Swallow clipboard rejections (e.g. no permission in a headless/denied
         // context) — the copy is optimistic and a failure shouldn't surface as an
@@ -36,7 +39,7 @@ export function CopyButton({
       )}
     >
       {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
-      {label ? <span>{copied ? "Copied" : label}</span> : null}
+      {label ? <span>{copied ? m.codeBlock.copied : label}</span> : null}
     </button>
   );
 }
@@ -153,6 +156,7 @@ export function CodeBlock({
   statusBar = variant === "editor",
   className,
 }: CodeBlockProps) {
+  const m = useMessages();
   const trimmed = code.replace(/\n$/, "");
   const lines = trimmed.split("\n");
   // `children` (pre-highlighted) wins; otherwise highlight the raw code.
@@ -165,7 +169,7 @@ export function CodeBlock({
           className="flex h-8 items-center gap-2 border-b px-3.5 font-mono text-[11px] font-semibold uppercase tracking-wider text-[var(--eld-syntax-line-number)]"
           style={elev}
         >
-          <span>{lang ?? "Terminal"}</span>
+          <span>{lang ?? m.codeBlock.terminal}</span>
         </div>
         <pre className="m-0 overflow-x-auto p-4 font-mono text-[13px] leading-[1.7] text-[var(--eld-syntax-default)]">
           {body}

packages/ui/src/components/mobile-nav.test.tsx

@@ -53,7 +53,7 @@ describe("MobileNav", () => {
     const onSearch = vi.fn();
     render(<MobileNav groups={groups} onSearch={onSearch} />);
 
-    await user.click(screen.getByRole("button", { name: /search or ask ai/i }));
+    await user.click(screen.getByRole("button", { name: /search or ask/i }));
     expect(onSearch).toHaveBeenCalledTimes(1);
   });
 });

packages/ui/src/components/mobile-nav.tsx

@@ -3,11 +3,12 @@ import { History, Menu, Search, Sparkle } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Button } from "./button";
 import { Sheet, SheetTrigger, SheetContent } from "./sheet";
+import { useMessages } from "../i18n/provider";
 
 /**
  * MobileNav — the docs shell at phone width (mockup 3b): a condensed top app
  * bar, a slide-in section drawer (built on the shipped `Sheet`), and a
- * persistent bottom "Search or ask AI" bar. Data-driven and presentational —
+ * persistent bottom "Search or ask" bar. Data-driven and presentational —
  * callers own routing (`href`s) and the search/AI action.
  */
 export interface MobileNavItem {
@@ -50,13 +51,14 @@ export function MobileNav({
   logo,
   onSearch,
   changelogHref,
-  searchPlaceholder = "Search or ask AI…",
+  searchPlaceholder,
   open,
   onOpenChange,
   className,
   children,
   ...props
 }: MobileNavProps) {
+  const m = useMessages();
   const [internalOpen, setInternalOpen] = React.useState(false);
   const drawerOpen = open ?? internalOpen;
   const setDrawerOpen = React.useCallback(
@@ -76,7 +78,7 @@ export function MobileNav({
               <Button
                 variant="outline"
                 size="icon"
-                aria-label="Open navigation"
+                aria-label={m.mobileNav.openNavigation}
                 className={cn(
                   drawerOpen && "border-[var(--primary)] bg-[var(--primary-soft)] text-[var(--primary-emphasis)]",
                 )}
@@ -86,7 +88,7 @@ export function MobileNav({
             <Menu aria-hidden className="h-[18px] w-[18px]" />
           </SheetTrigger>
           <div className="flex flex-1 items-center gap-2 overflow-hidden">{logo}</div>
-          <Button variant="outline" size="icon" aria-label="Search" onClick={onSearch}>
+          <Button variant="outline" size="icon" aria-label={m.mobileNav.searchLabel} onClick={onSearch}>
             <Search aria-hidden className="h-[17px] w-[17px]" />
           </Button>
         </header>
@@ -100,7 +102,7 @@ export function MobileNav({
             className="flex h-11 w-full items-center gap-2.5 rounded-xl border border-[var(--border-strong)] bg-[var(--muted)] px-3.5 text-[var(--subtle-foreground)]"
           >
             <Search aria-hidden className="h-4 w-4 text-[var(--primary-emphasis)]" />
-            <span className="flex-1 text-left text-sm">{searchPlaceholder}</span>
+            <span className="flex-1 text-left text-sm">{searchPlaceholder ?? m.mobileNav.searchPlaceholder}</span>
             <Sparkle aria-hidden className="h-[15px] w-[15px] text-[var(--primary-emphasis)]" />
           </button>
         </div>
@@ -109,7 +111,7 @@ export function MobileNav({
       <SheetContent
         side="left"
         showCloseButton={false}
-        aria-label={section?.title ? `${section.title} navigation` : "Navigation menu"}
+        aria-label={section?.title ? `${section.title} navigation` : m.mobileNav.dialogLabel}
         className="flex w-72 flex-col gap-5 p-4"
       >
         {section ? (
@@ -131,7 +133,7 @@ export function MobileNav({
           </div>
         ) : null}
 
-        <nav aria-label="Mobile navigation" className="flex flex-1 flex-col gap-4 overflow-y-auto">
+        <nav aria-label={m.mobileNav.navLabel} className="flex flex-1 flex-col gap-4 overflow-y-auto">
           {groups.map((group) => (
             <div key={group.label} className="flex flex-col gap-1">
               <div className="px-2.5 font-mono text-[10.5px] font-semibold uppercase tracking-wider text-[var(--subtle-foreground)]">
@@ -173,7 +175,7 @@ export function MobileNav({
           render={changelogHref ? <a href={changelogHref} /> : undefined}
         >
           <History aria-hidden className="h-[15px] w-[15px]" />
-          Changelog
+          {m.mobileNav.changelog}
         </Button>
       </SheetContent>
     </Sheet>

packages/ui/src/components/section-tabs.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * SectionTabs — the 46px top-level section bar under the main nav (Start ·
@@ -32,9 +33,10 @@ const dotColor: Record<NonNullable<SectionTabsVersion["status"]>, string> = {
 };
 
 export function SectionTabs({ items, version, onSelect, className, ...props }: SectionTabsProps) {
+  const m = useMessages();
   return (
     <nav
-      aria-label="Sections"
+      aria-label={m.sectionTabs.navLabel}
       className={cn(
         "flex h-[46px] items-center gap-1 border-b border-border bg-background px-[22px]",
         className,

packages/ui/src/components/sidebar.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import { Check, ChevronDown, ExternalLink } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Badge } from "./badge";
+import { useMessages } from "../i18n/provider";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -110,6 +111,7 @@ export interface SidebarItemProps {
 }
 
 export function SidebarItem({ label, href, active, external, comingSoon, onSelect }: SidebarItemProps) {
+  const m = useMessages();
   if (comingSoon) {
     return (
       <span
@@ -118,7 +120,7 @@ export function SidebarItem({ label, href, active, external, comingSoon, onSelec
       >
         {label}
         <Badge variant="neutral" size="sm" className="shrink-0">
-          Soon
+          {m.sidebar.comingSoon}
         </Badge>
       </span>
     );
@@ -177,9 +179,10 @@ export function Sidebar({
   className,
   ...props
 }: SidebarProps) {
+  const m = useMessages();
   return (
     <nav
-      aria-label="Sidebar"
+      aria-label={m.sidebar.navLabel}
       className={cn("flex w-[264px] flex-col gap-[22px] border-r border-border bg-background p-3.5", className)}
       {...props}
     >

packages/ui/src/components/status-badge.tsx

@@ -1,18 +1,19 @@
 import { Badge, type BadgeProps } from "./badge";
+import { useMessages } from "../i18n/provider";
 
 /**
  * StatusBadge — thin wrapper over `Badge`'s status tones. Maps an API-support
  * status (as used across the node:-compatibility reference pages) to a badge
- * variant, dot, and default label.
+ * variant, dot, and default (localized) label.
  */
 export type ApiStatus = "implemented" | "supported" | "partial" | "missing" | "planned";
 
-const STATUS_CONFIG: Record<ApiStatus, { variant: NonNullable<BadgeProps["variant"]>; label: string }> = {
-  implemented: { variant: "supported", label: "Implemented" },
-  supported: { variant: "supported", label: "Supported" },
-  partial: { variant: "partial", label: "Partial" },
-  missing: { variant: "missing", label: "Missing" },
-  planned: { variant: "missing", label: "Planned" },
+const STATUS_VARIANT: Record<ApiStatus, NonNullable<BadgeProps["variant"]>> = {
+  implemented: "supported",
+  supported: "supported",
+  partial: "partial",
+  missing: "missing",
+  planned: "missing",
 };
 
 export interface StatusBadgeProps extends Omit<BadgeProps, "variant" | "dot"> {
@@ -22,10 +23,10 @@ export interface StatusBadgeProps extends Omit<BadgeProps, "variant" | "dot"> {
 }
 
 export function StatusBadge({ status, label, children, ...props }: StatusBadgeProps) {
-  const { variant, label: defaultLabel } = STATUS_CONFIG[status];
+  const m = useMessages();
   return (
-    <Badge dot variant={variant} {...props}>
-      {children ?? label ?? defaultLabel}
+    <Badge dot variant={STATUS_VARIANT[status]} {...props}>
+      {children ?? label ?? m.statusBadge[status]}
     </Badge>
   );
 }