From e517848ecfc0b282c37c18bfcc0b6ac4f899adb9 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Wed, 13 May 2026 06:31:04 +0200
Subject: [PATCH 1/2] feat(registry): add localized registry routes

---
 .github/workflows/ci.yml                      |    3 +
 .../{ => [locale]}/components/[slug]/page.tsx |  107 +-
 .../app/{ => [locale]}/components/page.tsx    |   64 +-
 .../registry/app/{ => [locale]}/docs/page.tsx |   45 +-
 apps/registry/app/[locale]/layout.tsx         |  140 +++
 .../app/[locale]/llms-full.txt/route.ts       |   85 ++
 apps/registry/app/[locale]/llms.txt/route.ts  |   78 ++
 .../registry/app/{ => [locale]}/not-found.tsx |   21 +-
 apps/registry/app/[locale]/page.tsx           |   65 +
 .../app/{ => [locale]}/philosophy/page.tsx    |   43 +-
 apps/registry/app/[locale]/report/page.tsx    |   57 +
 .../{ => [locale]}/report/report-bug-form.tsx |   83 +-
 .../app/[locale]/request-component/page.tsx   |   55 +
 .../request-component-form.tsx                |   83 +-
 apps/registry/app/{ => [locale]}/vs/page.tsx  |   61 +-
 .../app/{ => [locale]}/vs/shadcn/page.tsx     |   79 +-
 apps/registry/app/layout.tsx                  |  113 --
 apps/registry/app/llms-full.txt/route.ts      |   26 +-
 apps/registry/app/llms.txt/route.ts           |   28 +-
 apps/registry/app/page.tsx                    |   42 -
 apps/registry/app/r/[name]/route.ts           |   56 +-
 apps/registry/app/report/page.tsx             |   43 -
 apps/registry/app/request-component/page.tsx  |   33 -
 apps/registry/app/sitemap.ts                  |   72 +-
 apps/registry/components/footer/footer.tsx    |  109 +-
 apps/registry/components/header/header.tsx    |   61 +-
 apps/registry/components/landing/landing.tsx  |  109 +-
 .../{components.mdx => components/en.mdx}     |    0
 apps/registry/content/pages/components/fr.mdx |    9 +
 .../content/pages/{docs.mdx => docs/en.mdx}   |    0
 apps/registry/content/pages/docs/fr.mdx       |   33 +
 .../content/pages/{home.mdx => home/en.mdx}   |    0
 apps/registry/content/pages/home/fr.mdx       |   62 +
 .../{philosophy.mdx => philosophy/en.mdx}     |    0
 apps/registry/content/pages/philosophy/fr.mdx |   62 +
 apps/registry/i18n/locales.ts                 |    4 +
 apps/registry/i18n/request.ts                 |   19 +
 apps/registry/i18n/routing.ts                 |   20 +
 apps/registry/lib/component-metadata.json     |  666 ++++++++++
 apps/registry/lib/content.ts                  |   31 +-
 apps/registry/lib/og.ts                       |   15 +-
 apps/registry/lib/registry-i18n.ts            |   26 +
 apps/registry/lib/seo.ts                      |   46 +-
 apps/registry/lib/sidebar-sections.ts         |  116 +-
 apps/registry/messages/en.json                |  152 +++
 apps/registry/messages/fr.json                |  152 +++
 apps/registry/next.config.mjs                 |    6 +-
 apps/registry/package.json                    |    2 +
 apps/registry/proxy.ts                        |    9 +
 apps/registry/registry.json                   | 1108 +++++++++++++----
 .../scripts/check-page-translations.ts        |   46 +
 .../scripts/generate-component-metadata.ts    |    3 +
 .../scripts/inline-component-source.ts        |    8 +
 .../scripts/stamp-registry-metadata.ts        |    6 +
 apps/registry/types/registry.ts               |    5 +
 pnpm-lock.yaml                                |  273 +++-
 56 files changed, 3777 insertions(+), 863 deletions(-)
 rename apps/registry/app/{ => [locale]}/components/[slug]/page.tsx (76%)
 rename apps/registry/app/{ => [locale]}/components/page.tsx (60%)
 rename apps/registry/app/{ => [locale]}/docs/page.tsx (71%)
 create mode 100644 apps/registry/app/[locale]/layout.tsx
 create mode 100644 apps/registry/app/[locale]/llms-full.txt/route.ts
 create mode 100644 apps/registry/app/[locale]/llms.txt/route.ts
 rename apps/registry/app/{ => [locale]}/not-found.tsx (81%)
 create mode 100644 apps/registry/app/[locale]/page.tsx
 rename apps/registry/app/{ => [locale]}/philosophy/page.tsx (67%)
 create mode 100644 apps/registry/app/[locale]/report/page.tsx
 rename apps/registry/app/{ => [locale]}/report/report-bug-form.tsx (68%)
 create mode 100644 apps/registry/app/[locale]/request-component/page.tsx
 rename apps/registry/app/{ => [locale]}/request-component/request-component-form.tsx (67%)
 rename apps/registry/app/{ => [locale]}/vs/page.tsx (73%)
 rename apps/registry/app/{ => [locale]}/vs/shadcn/page.tsx (86%)
 delete mode 100644 apps/registry/app/layout.tsx
 delete mode 100644 apps/registry/app/page.tsx
 delete mode 100644 apps/registry/app/report/page.tsx
 delete mode 100644 apps/registry/app/request-component/page.tsx
 rename apps/registry/content/pages/{components.mdx => components/en.mdx} (100%)
 create mode 100644 apps/registry/content/pages/components/fr.mdx
 rename apps/registry/content/pages/{docs.mdx => docs/en.mdx} (100%)
 create mode 100644 apps/registry/content/pages/docs/fr.mdx
 rename apps/registry/content/pages/{home.mdx => home/en.mdx} (100%)
 create mode 100644 apps/registry/content/pages/home/fr.mdx
 rename apps/registry/content/pages/{philosophy.mdx => philosophy/en.mdx} (100%)
 create mode 100644 apps/registry/content/pages/philosophy/fr.mdx
 create mode 100644 apps/registry/i18n/locales.ts
 create mode 100644 apps/registry/i18n/request.ts
 create mode 100644 apps/registry/i18n/routing.ts
 create mode 100644 apps/registry/lib/registry-i18n.ts
 create mode 100644 apps/registry/messages/en.json
 create mode 100644 apps/registry/messages/fr.json
 create mode 100644 apps/registry/proxy.ts
 create mode 100644 apps/registry/scripts/check-page-translations.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e9a769c1..a0f55ceb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,6 +33,9 @@ jobs:
       - name: Build
         run: pnpm build
 
+      - name: Check page translations
+        run: pnpm -F @vllnt/ui-registry check:translations
+
       - name: Test
         run: pnpm test:once
 
diff --git a/apps/registry/app/components/[slug]/page.tsx b/apps/registry/app/[locale]/components/[slug]/page.tsx
similarity index 76%
rename from apps/registry/app/components/[slug]/page.tsx
rename to apps/registry/app/[locale]/components/[slug]/page.tsx
index 827ecfa4..83a2196d 100644
--- a/apps/registry/app/components/[slug]/page.tsx
+++ b/apps/registry/app/[locale]/components/[slug]/page.tsx
@@ -4,19 +4,17 @@ import path from "node:path";
 import { Breadcrumb, CodeBlock, Sidebar, TableOfContents } from "@vllnt/ui";
 import { ExternalLink } from "lucide-react";
 import type { Metadata } from "next";
-import Link from "next/link";
 import { notFound } from "next/navigation";
+import { getTranslations, setRequestLocale } from "next-intl/server";
 
 import { QuickAdd } from "@/components/quick-add";
 import { StorybookEmbed } from "@/components/storybook-embed";
+import { Link, type Locale, routing } from "@/i18n/routing";
 import componentMetadata from "@/lib/component-metadata.json";
-import {
-  breadcrumbLd,
-  jsonLdScript,
-  softwareSourceCodeLd,
-} from "@/lib/jsonld";
+import { breadcrumbLd, jsonLdScript, softwareSourceCodeLd } from "@/lib/jsonld";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical } from "@/lib/seo";
+import { getLocalizedDescription } from "@/lib/registry-i18n";
+import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
 import {
   getCategoryForComponent,
   getSidebarSections,
@@ -25,7 +23,7 @@ import registryData from "@/registry.json";
 import type { Registry, RegistryComponent } from "@/types/registry";
 
 type Props = {
-  params: Promise<{ slug: string }>;
+  params: Promise<{ locale: Locale; slug: string }>;
 };
 
 const registry = registryData as Registry;
@@ -45,13 +43,18 @@ const STORYBOOK_URL =
   process.env.NEXT_PUBLIC_STORYBOOK_URL ?? "http://localhost:6006";
 
 export async function generateStaticParams() {
-  return registry.items
+  const components = registry.items
     .filter(
       (item): item is RegistryComponent => item.type === "registry:component",
     )
-    .map((item) => ({
-      slug: item.name,
-    }));
+    .map((item) => item.name);
+
+  return routing.locales.flatMap((locale) =>
+    components.map((slug) => ({
+      locale,
+      slug,
+    })),
+  );
 }
 
 function getNpmUrl(packageName: string): string {
@@ -59,7 +62,7 @@ function getNpmUrl(packageName: string): string {
 }
 
 export async function generateMetadata(props: Props): Promise<Metadata> {
-  const { slug } = await props.params;
+  const { locale, slug } = await props.params;
   const component = registry.items.find(
     (item): item is RegistryComponent =>
       item.name === slug && item.type === "registry:component",
@@ -72,7 +75,7 @@ export async function generateMetadata(props: Props): Promise<Metadata> {
   const meta = metadata_map[slug];
   const category = getCategoryForComponent(slug);
   const title = meta?.title ?? component.title;
-  const description = meta?.description ?? component.description;
+  const description = getLocalizedDescription(component, locale);
 
   const ogParameters = {
     category,
@@ -82,16 +85,23 @@ export async function generateMetadata(props: Props): Promise<Metadata> {
   };
 
   return {
-    alternates: { canonical: canonical(`/components/${slug}`) },
+    alternates: {
+      canonical: canonical(`/components/${slug}`, locale),
+      languages: languageAlternates(`/components/${slug}`),
+    },
     description,
-    openGraph: generateOGMetadata(ogParameters),
+    openGraph: generateOGMetadata(ogParameters, {
+      locale,
+      pathname: `/components/${slug}`,
+    }),
     title: `${title} - VLLNT UI`,
     twitter: generateTwitterMetadata(ogParameters),
   };
 }
 
 export default async function ComponentPage(props: Props) {
-  const { slug } = await props.params;
+  const { locale, slug } = await props.params;
+  setRequestLocale(locale);
   const component = registry.items.find(
     (item): item is RegistryComponent =>
       item.name === slug && item.type === "registry:component",
@@ -103,7 +113,9 @@ export default async function ComponentPage(props: Props) {
 
   const meta = metadata_map[slug];
   const displayTitle = meta?.title ?? component.title ?? component.name;
-  const displayDescription = meta?.description ?? component.description ?? "";
+  const displayDescription = getLocalizedDescription(component, locale);
+  const t = await getTranslations({ locale, namespace: "pages.component" });
+  const common = await getTranslations({ locale, namespace: "common" });
 
   // Read component source for code display
   let componentCode = "";
@@ -158,17 +170,16 @@ export default async function ComponentPage(props: Props) {
   const installCommand = `pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/${component.name}.json`;
 
   const sections = [
-    { id: "installation", title: "Installation" },
-    ...(meta?.defaultStoryId ? [{ id: "storybook", title: "Storybook" }] : []),
-    ...(componentCode ? [{ id: "code", title: "Code" }] : []),
+    { id: "installation", title: t("installation") },
+    ...(meta?.defaultStoryId
+      ? [{ id: "storybook", title: t("storybook") }]
+      : []),
+    ...(componentCode ? [{ id: "code", title: t("code") }] : []),
     ...(component.dependencies && component.dependencies.length > 0
-      ? [{ id: "dependencies", title: "Dependencies" }]
+      ? [{ id: "dependencies", title: t("dependencies") }]
       : []),
   ] as { id: string; title: string }[];
 
-  const SITE_URL =
-    process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
-
   return (
     <>
       <script
@@ -180,18 +191,23 @@ export default async function ComponentPage(props: Props) {
               title: displayTitle,
             }),
             breadcrumbLd([
-              { name: "Home", url: SITE_URL },
-              { name: "Components", url: `${SITE_URL}/components` },
+              { name: common("home"), url: canonical("/", locale) },
+              {
+                name: common("components"),
+                url: canonical("/components", locale),
+              },
               {
                 name: displayTitle,
-                url: `${SITE_URL}/components/${component.name}`,
+                url: canonical(`/components/${component.name}`, locale),
               },
             ]),
           ]),
         }}
         type="application/ld+json"
       />
-      <Sidebar sections={getSidebarSections(getCategoryForComponent(slug))} />
+      <Sidebar
+        sections={getSidebarSections(getCategoryForComponent(slug), locale)}
+      />
       <main className="flex-1 overflow-y-auto bg-background overflow-x-hidden">
         <div className="mx-auto max-w-7xl px-4 py-8 lg:px-8">
           <div className="grid grid-cols-1 xl:grid-cols-[minmax(0,1fr)_200px] gap-8">
@@ -201,8 +217,14 @@ export default async function ComponentPage(props: Props) {
                 <Breadcrumb
                   className="mb-4 text-muted-foreground"
                   items={[
-                    { href: "/", label: "Home" },
-                    { href: "/components", label: "Components" },
+                    {
+                      href: localizePathname("/", locale),
+                      label: common("home"),
+                    },
+                    {
+                      href: localizePathname("/components", locale),
+                      label: common("components"),
+                    },
                     { label: displayTitle },
                   ]}
                 />
@@ -216,7 +238,7 @@ export default async function ComponentPage(props: Props) {
                     className="inline-flex h-9 items-center rounded-md border border-border px-4 text-sm font-medium hover:bg-muted"
                     href={`/report?component=${component.name}`}
                   >
-                    Report a bug
+                    {t("reportBug")}
                   </Link>
                 </div>
               </div>
@@ -235,7 +257,9 @@ export default async function ComponentPage(props: Props) {
 
               {/* Installation */}
               <div className="mb-8 scroll-mt-8" id="installation">
-                <h2 className="text-2xl font-semibold mb-4">Installation</h2>
+                <h2 className="text-2xl font-semibold mb-4">
+                  {t("installation")}
+                </h2>
                 <CodeBlock language="bash" showLanguage={true}>
                   {installCommand}
                 </CodeBlock>
@@ -244,10 +268,11 @@ export default async function ComponentPage(props: Props) {
               {/* Storybook link */}
               {meta?.defaultStoryId ? (
                 <div className="mb-8 scroll-mt-8" id="storybook">
-                  <h2 className="text-2xl font-semibold mb-4">Storybook</h2>
+                  <h2 className="text-2xl font-semibold mb-4">
+                    {t("storybook")}
+                  </h2>
                   <p className="text-muted-foreground mb-4">
-                    Explore all variants, controls, and accessibility checks in
-                    the interactive Storybook playground.
+                    {t("storybookDescription")}
                   </p>
                   <Link
                     className="inline-flex items-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
@@ -255,13 +280,13 @@ export default async function ComponentPage(props: Props) {
                     rel="noopener noreferrer"
                     target="_blank"
                   >
-                    View in Storybook
+                    {t("viewInStorybook")}
                     <ExternalLink className="h-4 w-4" />
                   </Link>
                   {meta.stories.length > 1 ? (
                     <div className="mt-4">
                       <p className="text-sm text-muted-foreground mb-2">
-                        {meta.stories.length} stories available:
+                        {t("storiesAvailable", { count: meta.stories.length })}
                       </p>
                       <div className="flex flex-wrap gap-2">
                         {meta.stories.map((story) => (
@@ -284,7 +309,7 @@ export default async function ComponentPage(props: Props) {
               {/* Code */}
               {componentCode ? (
                 <div className="mb-8 scroll-mt-8" id="code">
-                  <h2 className="text-2xl font-semibold mb-4">Code</h2>
+                  <h2 className="text-2xl font-semibold mb-4">{t("code")}</h2>
                   <CodeBlock language="typescript" showLanguage={true}>
                     {componentCode}
                   </CodeBlock>
@@ -294,7 +319,9 @@ export default async function ComponentPage(props: Props) {
               {/* Dependencies */}
               {component.dependencies && component.dependencies.length > 0 ? (
                 <div className="mb-8 scroll-mt-8" id="dependencies">
-                  <h2 className="text-2xl font-semibold mb-4">Dependencies</h2>
+                  <h2 className="text-2xl font-semibold mb-4">
+                    {t("dependencies")}
+                  </h2>
                   <div className="rounded-lg border bg-card p-6">
                     <ul className="space-y-2">
                       {component.dependencies.map((dep) => {
diff --git a/apps/registry/app/components/page.tsx b/apps/registry/app/[locale]/components/page.tsx
similarity index 60%
rename from apps/registry/app/components/page.tsx
rename to apps/registry/app/[locale]/components/page.tsx
index c5736e24..4b82d64f 100644
--- a/apps/registry/app/components/page.tsx
+++ b/apps/registry/app/[locale]/components/page.tsx
@@ -1,38 +1,51 @@
 import { Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
-import Link from "next/link";
+import { getTranslations, setRequestLocale } from "next-intl/server";
 
+import { Link, type Locale } from "@/i18n/routing";
 import componentMetadata from "@/lib/component-metadata.json";
 import { getPageContent } from "@/lib/content";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical } from "@/lib/seo";
+import { getLocalizedDescription } from "@/lib/registry-i18n";
+import { canonical, languageAlternates } from "@/lib/seo";
 import {
-  components,
+  getGroupedComponents,
   getSidebarSections,
-  groupedComponents,
 } from "@/lib/sidebar-sections";
 
 const metadata_map = componentMetadata as Record<
   string,
   {
     description: string;
+    descriptions?: Partial<Record<string, string>>;
     stories: { id: string; name: string }[];
     title: string;
   }
 >;
 
-export async function generateMetadata(): Promise<Metadata> {
-  const { frontmatter } = await getPageContent("components");
+type Props = {
+  params: Promise<{ locale: Locale }>;
+};
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const { frontmatter } = await getPageContent("components", locale);
   const og = frontmatter.og;
 
   return {
-    alternates: { canonical: canonical("/components") },
+    alternates: {
+      canonical: canonical("/components", locale),
+      languages: languageAlternates("/components"),
+    },
     description: frontmatter.description,
-    openGraph: generateOGMetadata({
-      description: og?.description ?? frontmatter.description,
-      title: og?.title ?? frontmatter.title,
-      type: og?.type ?? frontmatter.type,
-    }),
+    openGraph: generateOGMetadata(
+      {
+        description: og?.description ?? frontmatter.description,
+        title: og?.title ?? frontmatter.title,
+        type: og?.type ?? frontmatter.type,
+      },
+      { locale, pathname: "/components" },
+    ),
     title: frontmatter.title,
     twitter: generateTwitterMetadata({
       description: og?.description ?? frontmatter.description,
@@ -42,17 +55,22 @@ export async function generateMetadata(): Promise<Metadata> {
   };
 }
 
-export default function ComponentsPage() {
+export default async function ComponentsPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  const { frontmatter } = await getPageContent("components", locale);
+  const t = await getTranslations({ locale, namespace: "pages.components" });
+  const groupedComponents = getGroupedComponents(locale);
+
   return (
     <>
-      <Sidebar sections={getSidebarSections()} />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto px-4 py-16 lg:px-8">
           <div className="mb-12">
-            <h1 className="text-4xl font-semibold mb-4">Components</h1>
+            <h1 className="text-4xl font-semibold mb-4">{frontmatter.title}</h1>
             <p className="text-muted-foreground text-lg">
-              Explore all {components.length} components available in the
-              library.
+              {frontmatter.description}
             </p>
           </div>
 
@@ -63,6 +81,10 @@ export default function ComponentsPage() {
                 {group.items.map((component) => {
                   const meta = metadata_map[component.name];
                   const storyCount = meta?.stories?.length ?? 0;
+                  const description = getLocalizedDescription(
+                    component,
+                    locale,
+                  );
 
                   return (
                     <Link
@@ -74,17 +96,17 @@ export default function ComponentsPage() {
                         <h3 className="text-sm font-medium group-hover:text-foreground transition-colors">
                           {component.title}
                         </h3>
-                        {meta?.description ? (
+                        {description ? (
                           <p className="text-xs text-muted-foreground mt-1 line-clamp-2">
-                            {meta.description}
+                            {description}
                           </p>
                         ) : null}
                       </div>
                       <div className="px-3 py-2 shrink-0 flex items-center justify-between">
                         <span className="text-xs text-muted-foreground">
                           {storyCount > 0
-                            ? `${storyCount} ${storyCount === 1 ? "story" : "stories"}`
-                            : "No preview"}
+                            ? t("stories", { count: storyCount })
+                            : t("noPreview")}
                         </span>
                       </div>
                     </Link>
diff --git a/apps/registry/app/docs/page.tsx b/apps/registry/app/[locale]/docs/page.tsx
similarity index 71%
rename from apps/registry/app/docs/page.tsx
rename to apps/registry/app/[locale]/docs/page.tsx
index af33081d..ac9c53d8 100644
--- a/apps/registry/app/docs/page.tsx
+++ b/apps/registry/app/[locale]/docs/page.tsx
@@ -1,26 +1,39 @@
 import { Breadcrumb, MDXContent, Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
+import { setRequestLocale } from "next-intl/server";
 
+import type { Locale } from "@/i18n/routing";
 import { getPageContent } from "@/lib/content";
 import { breadcrumbLd, jsonLdScript } from "@/lib/jsonld";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical } from "@/lib/seo";
+import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
 import { getSidebarSections } from "@/lib/sidebar-sections";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
 
-export async function generateMetadata(): Promise<Metadata> {
-  const { frontmatter } = await getPageContent("docs");
+type Props = {
+  params: Promise<{ locale: Locale }>;
+};
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const { frontmatter } = await getPageContent("docs", locale);
   const og = frontmatter.og;
 
   return {
-    alternates: { canonical: canonical("/docs") },
+    alternates: {
+      canonical: canonical("/docs", locale),
+      languages: languageAlternates("/docs"),
+    },
     description: frontmatter.description,
-    openGraph: generateOGMetadata({
-      description: og?.description ?? frontmatter.description,
-      title: og?.title ?? frontmatter.title,
-      type: og?.type ?? frontmatter.type,
-    }),
+    openGraph: generateOGMetadata(
+      {
+        description: og?.description ?? frontmatter.description,
+        title: og?.title ?? frontmatter.title,
+        type: og?.type ?? frontmatter.type,
+      },
+      { locale, pathname: "/docs" },
+    ),
     title: frontmatter.title,
     twitter: generateTwitterMetadata({
       description: og?.description ?? frontmatter.description,
@@ -30,8 +43,10 @@ export async function generateMetadata(): Promise<Metadata> {
   };
 }
 
-export default async function DocumentationPage() {
-  const { content } = await getPageContent("docs");
+export default async function DocumentationPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  const { content, frontmatter } = await getPageContent("docs", locale);
 
   return (
     <>
@@ -46,20 +61,20 @@ export default async function DocumentationPage() {
         }}
         type="application/ld+json"
       />
-      <Sidebar sections={getSidebarSections()} />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto px-4 py-16 lg:px-8">
           <div className="mb-8">
             <Breadcrumb
               className="mb-4 text-muted-foreground"
               items={[
-                { href: "/", label: "Home" },
+                { href: localizePathname("/", locale), label: "Home" },
                 { label: "Docs" },
               ]}
             />
-            <h1 className="text-4xl font-semibold mb-4">Documentation</h1>
+            <h1 className="text-4xl font-semibold mb-4">{frontmatter.title}</h1>
             <p className="text-muted-foreground text-lg">
-              Learn how to use VLLNT UI components in your projects.
+              {frontmatter.description}
             </p>
           </div>
 
diff --git a/apps/registry/app/[locale]/layout.tsx b/apps/registry/app/[locale]/layout.tsx
new file mode 100644
index 00000000..8f6a7dbf
--- /dev/null
+++ b/apps/registry/app/[locale]/layout.tsx
@@ -0,0 +1,140 @@
+import "@vllnt/ui/styles.css";
+import "@vllnt/ui/themes/default.css";
+import "../globals.css";
+
+import { Analytics } from "@vercel/analytics/next";
+import { SpeedInsights } from "@vercel/speed-insights/next";
+import { SidebarProvider, ThemeProvider } from "@vllnt/ui";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { hasLocale, NextIntlClientProvider } from "next-intl";
+import { setRequestLocale } from "next-intl/server";
+import type React from "react";
+
+import { Header } from "@/components/header";
+import { routing } from "@/i18n/routing";
+import { jsonLdScript, organizationLd, websiteLd } from "@/lib/jsonld";
+import { alternateOgLocales, languageAlternates, ogLocale } from "@/lib/seo";
+
+type Props = {
+  children: React.ReactNode;
+  params: Promise<{ locale: string }>;
+};
+
+export function generateStaticParams() {
+  return routing.locales.map((locale) => ({ locale }));
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale: requestedLocale } = await params;
+  const locale = hasLocale(routing.locales, requestedLocale)
+    ? requestedLocale
+    : routing.defaultLocale;
+
+  return {
+    alternates: { languages: languageAlternates("/") },
+    applicationName: "VLLNT UI",
+    authors: [{ name: "VLLNT", url: "https://github.com/vllnt" }],
+    category: "Developer Tools",
+    creator: "VLLNT",
+    description:
+      "Agent-first React component registry. 225 accessible components built on Radix UI, Tailwind CSS, and CVA. Install via the shadcn CLI.",
+    formatDetection: {
+      address: false,
+      email: false,
+      telephone: false,
+    },
+    generator: "Next.js",
+    keywords: [
+      "react",
+      "components",
+      "react components",
+      "ui library",
+      "component library",
+      "tailwind",
+      "tailwindcss",
+      "radix",
+      "radix-ui",
+      "shadcn",
+      "shadcn-ui",
+      "registry",
+      "design system",
+      "accessible",
+      "typescript",
+      "ai",
+      "llms.txt",
+      "open source",
+    ],
+    metadataBase: new URL(
+      process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai",
+    ),
+    openGraph: {
+      alternateLocale: alternateOgLocales(locale),
+      locale: ogLocale(locale),
+      siteName: "VLLNT UI",
+      type: "website",
+    },
+    publisher: "VLLNT",
+    referrer: "origin-when-cross-origin",
+    robots: {
+      follow: true,
+      googleBot: {
+        follow: true,
+        index: true,
+        "max-image-preview": "large",
+        "max-snippet": -1,
+        "max-video-preview": -1,
+      },
+      index: true,
+    },
+    title: "VLLNT UI - 225 agent-first React components",
+    twitter: {
+      card: "summary_large_image",
+      creator: "@vllnt",
+      site: "@vllnt",
+    },
+  };
+}
+
+export default async function LocaleLayout({ children, params }: Props) {
+  const { locale } = await params;
+  if (!hasLocale(routing.locales, locale)) {
+    notFound();
+  }
+
+  setRequestLocale(locale);
+
+  return (
+    <html lang={locale} suppressHydrationWarning>
+      <head>
+        <script
+          dangerouslySetInnerHTML={{ __html: jsonLdScript(organizationLd()) }}
+          type="application/ld+json"
+        />
+        <script
+          dangerouslySetInnerHTML={{ __html: jsonLdScript(websiteLd()) }}
+          type="application/ld+json"
+        />
+      </head>
+      <body className="h-full overflow-hidden">
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="dark"
+          disableTransitionOnChange
+          enableSystem
+        >
+          <SidebarProvider>
+            <div className="flex h-full flex-col overflow-hidden">
+              <NextIntlClientProvider>
+                <Header locale={locale} />
+                <div className="flex flex-1 overflow-hidden">{children}</div>
+              </NextIntlClientProvider>
+            </div>
+          </SidebarProvider>
+        </ThemeProvider>
+        <Analytics />
+        <SpeedInsights />
+      </body>
+    </html>
+  );
+}
diff --git a/apps/registry/app/[locale]/llms-full.txt/route.ts b/apps/registry/app/[locale]/llms-full.txt/route.ts
new file mode 100644
index 00000000..f3257f29
--- /dev/null
+++ b/apps/registry/app/[locale]/llms-full.txt/route.ts
@@ -0,0 +1,85 @@
+/* eslint-disable @typescript-eslint/naming-convention, functional/no-loop-statements, max-lines-per-function */
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { isLocale, routing } from "../../../i18n/routing";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+
+function stripFrontmatter(source: string): string {
+  if (!source.startsWith("---")) return source;
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return source;
+  return source.slice(end + 4).replace(/^\n+/, "");
+}
+
+async function readDocumentPage(slug: string): Promise<string> {
+  const file = path.join(process.cwd(), "content", "pages", slug, "fr.mdx");
+  try {
+    const raw = await readFile(file, "utf8");
+    return stripFrontmatter(raw).trim();
+  } catch {
+    return "";
+  }
+}
+
+export const dynamic = "force-dynamic";
+export const revalidate = 86_400;
+
+type RouteParameters = {
+  params: Promise<{ locale: string }>;
+};
+
+function redirectToRoot(request: Request): Response {
+  const url = new URL(request.url);
+  const host = request.headers.get("host");
+  const protocol = request.headers.get("x-forwarded-proto");
+  if (host) url.host = host;
+  if (protocol) url.protocol = `${protocol}:`;
+  url.pathname = "/llms-full.txt";
+  return Response.redirect(url, 308);
+}
+
+export async function GET(
+  request: Request,
+  routeParameters: RouteParameters,
+): Promise<Response> {
+  const { locale } = await routeParameters.params;
+  if (!isLocale(locale)) {
+    return new Response("Not found", { status: 404 });
+  }
+  if (locale === routing.defaultLocale) {
+    return redirectToRoot(request);
+  }
+
+  const pages = [
+    { slug: "home", title: "Accueil" },
+    { slug: "docs", title: "Documentation" },
+    { slug: "philosophy", title: "Philosophie" },
+    { slug: "components", title: "Composants" },
+  ];
+  const lines = [
+    "# VLLNT UI - Reference francaise",
+    "",
+    `> Contexte agent localise. Les schemas de registre restent canoniques sur ${SITE_URL}/r/<name>.json.`,
+    "",
+  ];
+
+  for (const page of pages) {
+    const body = await readDocumentPage(page.slug);
+    if (!body) continue;
+    lines.push(`## ${page.title}`);
+    lines.push("");
+    lines.push(body);
+    lines.push("");
+  }
+
+  return new Response(lines.join("\n"), {
+    headers: {
+      "Cache-Control":
+        "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+  });
+}
diff --git a/apps/registry/app/[locale]/llms.txt/route.ts b/apps/registry/app/[locale]/llms.txt/route.ts
new file mode 100644
index 00000000..955c1a7f
--- /dev/null
+++ b/apps/registry/app/[locale]/llms.txt/route.ts
@@ -0,0 +1,78 @@
+/* eslint-disable @typescript-eslint/naming-convention, functional/no-loop-statements, max-lines-per-function */
+
+import { isLocale, routing } from "../../../i18n/routing";
+import registry from "../../../registry.json";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+
+type RegistryItem = {
+  readonly description: string;
+  readonly name: string;
+  readonly title: string;
+};
+
+export const dynamic = "force-dynamic";
+export const revalidate = 86_400;
+
+type RouteParameters = {
+  params: Promise<{ locale: string }>;
+};
+
+function redirectToRoot(request: Request): Response {
+  const url = new URL(request.url);
+  const host = request.headers.get("host");
+  const protocol = request.headers.get("x-forwarded-proto");
+  if (host) url.host = host;
+  if (protocol) url.protocol = `${protocol}:`;
+  url.pathname = "/llms.txt";
+  return Response.redirect(url, 308);
+}
+
+export async function GET(
+  request: Request,
+  routeParameters: RouteParameters,
+): Promise<Response> {
+  const { locale } = await routeParameters.params;
+  if (!isLocale(locale)) {
+    return new Response("Not found", { status: 404 });
+  }
+  if (locale === routing.defaultLocale) {
+    return redirectToRoot(request);
+  }
+
+  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
+  const lines: string[] = [
+    "# VLLNT UI",
+    "",
+    "> Index francais pour agents. Les endpoints /r/*.json restent canoniques en anglais; les pages humaines existent aussi sous /fr/.",
+    "",
+    "## Documentation",
+    "",
+    `- [Accueil](${SITE_URL}/fr): demarrer avec VLLNT UI`,
+    `- [Documentation](${SITE_URL}/fr/docs): installation, theming et registre`,
+    `- [Composants](${SITE_URL}/fr/components): parcourir les composants`,
+    `- [Version anglaise](${SITE_URL}/llms.txt): index canonique`,
+    "",
+    "## Registre API",
+    "",
+    `- [Registry index](${SITE_URL}/r/registry.json): liste machine-readable de tous les composants`,
+    `- [Sitemap](${SITE_URL}/sitemap.xml): routes publiques avec hreflang`,
+    "",
+    "## Composants",
+    "",
+  ];
+
+  for (const item of [...items].sort((a, b) => a.name.localeCompare(b.name))) {
+    lines.push(
+      `- [${item.title}](${SITE_URL}/fr/components/${item.name}): ${item.description}`,
+    );
+  }
+
+  return new Response(lines.join("\n"), {
+    headers: {
+      "Cache-Control":
+        "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+  });
+}
diff --git a/apps/registry/app/not-found.tsx b/apps/registry/app/[locale]/not-found.tsx
similarity index 81%
rename from apps/registry/app/not-found.tsx
rename to apps/registry/app/[locale]/not-found.tsx
index 8c2e9c69..e375abd2 100644
--- a/apps/registry/app/not-found.tsx
+++ b/apps/registry/app/[locale]/not-found.tsx
@@ -1,7 +1,8 @@
 import { Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
-import Link from "next/link";
+import { useLocale, useTranslations } from "next-intl";
 
+import { isLocale, Link } from "@/i18n/routing";
 import { getSidebarSections } from "@/lib/sidebar-sections";
 
 export const metadata: Metadata = {
@@ -10,7 +11,7 @@ export const metadata: Metadata = {
   title: "Page not found · VLLNT UI",
 };
 
-const POPULAR_COMPONENTS: ReadonlyArray<{ name: string; slug: string }> = [
+const POPULAR_COMPONENTS: readonly { name: string; slug: string }[] = [
   { name: "Button", slug: "button" },
   { name: "DataTable", slug: "data-table" },
   { name: "AI Chat Input", slug: "ai-chat-input" },
@@ -23,18 +24,22 @@ const REQUEST_URL =
   "https://github.com/vllnt/ui/issues/new?template=feature_request.yml&labels=enhancement,component";
 
 export default function NotFound() {
+  const requestedLocale = useLocale();
+  const locale = isLocale(requestedLocale) ? requestedLocale : "en";
+  const common = useTranslations("common");
+  const t = useTranslations("pages.notFound");
+
   return (
     <>
-      <Sidebar sections={getSidebarSections()} />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto px-4 py-24 lg:px-8 max-w-3xl">
           <p className="text-sm font-medium text-muted-foreground tracking-wide uppercase">
             404
           </p>
-          <h1 className="mt-3 text-4xl font-semibold">Page not found</h1>
+          <h1 className="mt-3 text-4xl font-semibold">{t("title")}</h1>
           <p className="mt-4 text-lg text-muted-foreground">
-            That route does not exist. Try one of the popular components below,
-            or jump back to the index.
+            {t("description")}
           </p>
 
           <div className="mt-8 flex flex-wrap gap-3">
@@ -42,7 +47,7 @@ export default function NotFound() {
               className="inline-flex h-10 items-center rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
               href="/components"
             >
-              Browse all components
+              {common("browseComponents")}
             </Link>
             <Link
               className="inline-flex h-10 items-center rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
@@ -62,7 +67,7 @@ export default function NotFound() {
 
           <section className="mt-16">
             <h2 className="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
-              Popular components
+              {t("popular")}
             </h2>
             <ul className="mt-4 grid grid-cols-2 gap-3 sm:grid-cols-3">
               {POPULAR_COMPONENTS.map((component) => (
diff --git a/apps/registry/app/[locale]/page.tsx b/apps/registry/app/[locale]/page.tsx
new file mode 100644
index 00000000..7a42c2a4
--- /dev/null
+++ b/apps/registry/app/[locale]/page.tsx
@@ -0,0 +1,65 @@
+import { Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import { setRequestLocale } from "next-intl/server";
+
+import { Landing } from "@/components/landing/landing";
+import type { Locale } from "@/i18n/routing";
+import { getPageContent } from "@/lib/content";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical, languageAlternates } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+import { getComponentCount, getLibraryVersion } from "@/lib/stats";
+
+type Props = {
+  params: Promise<{ locale: Locale }>;
+};
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const componentCount = getComponentCount();
+  const version = getLibraryVersion();
+  const { frontmatter } = await getPageContent("home", locale);
+  const og = frontmatter.og;
+  const title = frontmatter.title
+    .replace("{count}", String(componentCount))
+    .replace("{version}", version);
+  const description = frontmatter.description
+    .replace("{count}", String(componentCount))
+    .replace("{version}", version);
+
+  return {
+    alternates: {
+      canonical: canonical("/", locale),
+      languages: languageAlternates("/"),
+    },
+    description,
+    openGraph: generateOGMetadata(
+      {
+        description: og?.description ?? description,
+        title: og?.title ?? title,
+        type: og?.type ?? "home",
+      },
+      { locale, pathname: "/" },
+    ),
+    title,
+    twitter: generateTwitterMetadata({
+      description,
+      title,
+      type: "home",
+    }),
+  };
+}
+
+export default async function HomePage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+
+  return (
+    <>
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <Landing />
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/philosophy/page.tsx b/apps/registry/app/[locale]/philosophy/page.tsx
similarity index 67%
rename from apps/registry/app/philosophy/page.tsx
rename to apps/registry/app/[locale]/philosophy/page.tsx
index 80330f9a..c66abaa9 100644
--- a/apps/registry/app/philosophy/page.tsx
+++ b/apps/registry/app/[locale]/philosophy/page.tsx
@@ -1,23 +1,36 @@
 import { MDXContent, Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
+import { setRequestLocale } from "next-intl/server";
 
+import type { Locale } from "@/i18n/routing";
 import { getPageContent } from "@/lib/content";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical } from "@/lib/seo";
+import { canonical, languageAlternates } from "@/lib/seo";
 import { getSidebarSections } from "@/lib/sidebar-sections";
 
-export async function generateMetadata(): Promise<Metadata> {
-  const { frontmatter } = await getPageContent("philosophy");
+type Props = {
+  params: Promise<{ locale: Locale }>;
+};
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const { frontmatter } = await getPageContent("philosophy", locale);
   const og = frontmatter.og;
 
   return {
-    alternates: { canonical: canonical("/philosophy") },
+    alternates: {
+      canonical: canonical("/philosophy", locale),
+      languages: languageAlternates("/philosophy"),
+    },
     description: frontmatter.description,
-    openGraph: generateOGMetadata({
-      description: og?.description ?? frontmatter.description,
-      title: og?.title ?? frontmatter.title,
-      type: og?.type ?? frontmatter.type,
-    }),
+    openGraph: generateOGMetadata(
+      {
+        description: og?.description ?? frontmatter.description,
+        title: og?.title ?? frontmatter.title,
+        type: og?.type ?? frontmatter.type,
+      },
+      { locale, pathname: "/philosophy" },
+    ),
     title: frontmatter.title,
     twitter: generateTwitterMetadata({
       description: og?.description ?? frontmatter.description,
@@ -27,18 +40,20 @@ export async function generateMetadata(): Promise<Metadata> {
   };
 }
 
-export default async function PhilosophyPage() {
-  const { content } = await getPageContent("philosophy");
+export default async function PhilosophyPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  const { content, frontmatter } = await getPageContent("philosophy", locale);
 
   return (
     <>
-      <Sidebar sections={getSidebarSections()} />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto px-4 py-16 lg:px-8">
           <div className="mb-8">
-            <h1 className="text-4xl font-semibold mb-4">Philosophy</h1>
+            <h1 className="text-4xl font-semibold mb-4">{frontmatter.title}</h1>
             <p className="text-muted-foreground text-lg">
-              The principles that guide VLLNT UI design and development.
+              {frontmatter.description}
             </p>
           </div>
 
diff --git a/apps/registry/app/[locale]/report/page.tsx b/apps/registry/app/[locale]/report/page.tsx
new file mode 100644
index 00000000..3fd4dee1
--- /dev/null
+++ b/apps/registry/app/[locale]/report/page.tsx
@@ -0,0 +1,57 @@
+import { Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import { getTranslations, setRequestLocale } from "next-intl/server";
+
+import type { Locale } from "@/i18n/routing";
+import { canonical, languageAlternates } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+
+import { ReportBugForm } from "./report-bug-form";
+
+type SearchParameters = {
+  readonly component?: string;
+};
+
+type Props = {
+  params: Promise<{ locale: Locale }>;
+  searchParams: Promise<SearchParameters>;
+};
+
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "pages.report" });
+
+  return {
+    alternates: {
+      canonical: canonical("/report", locale),
+      languages: languageAlternates("/report"),
+    },
+    description: t("metaDescription"),
+    robots: { follow: true, index: false },
+    title: `${t("title")} - VLLNT UI`,
+  };
+}
+
+export default async function ReportBugPage({ params, searchParams }: Props) {
+  const { locale } = await params;
+  const { component } = await searchParams;
+  setRequestLocale(locale);
+  const t = await getTranslations({ locale, namespace: "pages.report" });
+
+  return (
+    <>
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <div className="container mx-auto max-w-2xl px-4 py-16 lg:px-8">
+          <h1 className="text-4xl font-semibold mb-3">{t("title")}</h1>
+          <p className="text-muted-foreground text-lg mb-8">
+            {t("description")}
+          </p>
+          <ReportBugForm initialComponent={component ?? ""} />
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/report/report-bug-form.tsx b/apps/registry/app/[locale]/report/report-bug-form.tsx
similarity index 68%
rename from apps/registry/app/report/report-bug-form.tsx
rename to apps/registry/app/[locale]/report/report-bug-form.tsx
index cefa2d02..a8b7c11f 100644
--- a/apps/registry/app/report/report-bug-form.tsx
+++ b/apps/registry/app/[locale]/report/report-bug-form.tsx
@@ -1,7 +1,9 @@
 "use client";
 
+import { useId, useState } from "react";
+
+import { useTranslations } from "next-intl";
 import type * as React from "react";
-import { useState } from "react";
 
 const REPO = "vllnt/ui";
 
@@ -44,47 +46,53 @@ function buildIssueUrl({
     .filter(Boolean)
     .join("\n");
 
-  const params = new URLSearchParams({
-    template: "bug_report.yml",
-    title: `${titleSlug}${summary || "bug summary"}`,
+  const parameters = new URLSearchParams({
     body,
     labels: component ? `bug,component:${component}` : "bug",
+    template: "bug_report.yml",
+    title: `${titleSlug}${summary || "bug summary"}`,
   });
 
-  return `https://github.com/${REPO}/issues/new?${params.toString()}`;
+  return `https://github.com/${REPO}/issues/new?${parameters.toString()}`;
 }
 
 function Field({
-  autoFocus,
   label,
   onChange,
   placeholder,
   required,
   value,
 }: {
-  autoFocus?: boolean;
   label: string;
   onChange: (value: string) => void;
   placeholder?: string;
   required?: boolean;
   value: string;
 }) {
+  const labelId = useId();
+
   return (
-    <label className="block">
-      <span className="text-sm font-medium">
+    <div>
+      <span className="text-sm font-medium" id={labelId}>
         {label}
-        {required ? <span className="ml-1 text-destructive">*</span> : null}
+        {required ? (
+          <span aria-hidden="true" className="ml-1 text-destructive">
+            *
+          </span>
+        ) : null}
       </span>
       <input
-        autoFocus={autoFocus}
+        aria-labelledby={labelId}
         className="mt-2 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
-        onChange={(event) => onChange(event.target.value)}
+        onChange={(event) => {
+          onChange(event.target.value);
+        }}
         placeholder={placeholder}
         required={required}
         type="text"
         value={value}
       />
-    </label>
+    </div>
   );
 }
 
@@ -103,21 +111,30 @@ function TextField({
   rows?: number;
   value: string;
 }) {
+  const labelId = useId();
+
   return (
-    <label className="block">
-      <span className="text-sm font-medium">
+    <div>
+      <span className="text-sm font-medium" id={labelId}>
         {label}
-        {required ? <span className="ml-1 text-destructive">*</span> : null}
+        {required ? (
+          <span aria-hidden="true" className="ml-1 text-destructive">
+            *
+          </span>
+        ) : null}
       </span>
       <textarea
+        aria-labelledby={labelId}
         className="mt-2 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
-        onChange={(event) => onChange(event.target.value)}
+        onChange={(event) => {
+          onChange(event.target.value);
+        }}
         placeholder={placeholder}
         required={required}
         rows={rows}
         value={value}
       />
-    </label>
+    </div>
   );
 }
 
@@ -126,13 +143,14 @@ export function ReportBugForm({
 }: {
   initialComponent?: string;
 }) {
+  const t = useTranslations("forms.report");
   const [component, setComponent] = useState(initialComponent);
   const [summary, setSummary] = useState("");
   const [repro, setRepro] = useState("");
   const [expected, setExpected] = useState("");
   const [actual, setActual] = useState("");
 
-  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+  function handleSubmit(event: React.SyntheticEvent<HTMLFormElement>) {
     event.preventDefault();
     const url = buildIssueUrl({ actual, component, expected, repro, summary });
     window.open(url, "_blank", "noopener,noreferrer");
@@ -141,38 +159,37 @@ export function ReportBugForm({
   return (
     <form className="space-y-5" onSubmit={handleSubmit}>
       <Field
-        label="Component (optional)"
+        label={t("componentLabel")}
         onChange={setComponent}
-        placeholder="e.g. button, combobox, ai-chat-input"
+        placeholder={t("componentPlaceholder")}
         value={component}
       />
       <Field
-        autoFocus
-        label="One-line summary"
+        label={t("summaryLabel")}
         onChange={setSummary}
-        placeholder="Concise headline for the issue title."
+        placeholder={t("summaryPlaceholder")}
         required
         value={summary}
       />
       <TextField
-        label="Reproduction"
+        label={t("reproLabel")}
         onChange={setRepro}
-        placeholder="Minimal repo / sandbox link / runnable snippet."
+        placeholder={t("reproPlaceholder")}
         required
         rows={4}
         value={repro}
       />
       <TextField
-        label="Expected behavior"
+        label={t("expectedLabel")}
         onChange={setExpected}
-        placeholder="What you expected to happen."
+        placeholder={t("expectedPlaceholder")}
         required
         value={expected}
       />
       <TextField
-        label="Actual behavior"
+        label={t("actualLabel")}
         onChange={setActual}
-        placeholder="What actually happened. Include console output or screenshots if useful."
+        placeholder={t("actualPlaceholder")}
         required
         rows={4}
         value={actual}
@@ -181,11 +198,9 @@ export function ReportBugForm({
         className="inline-flex h-10 items-center rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
         type="submit"
       >
-        Open prefilled GitHub issue
+        {t("submit")}
       </button>
-      <p className="text-xs text-muted-foreground">
-        Submitting opens a new GitHub issue tab. Nothing is sent to a server.
-      </p>
+      <p className="text-xs text-muted-foreground">{t("note")}</p>
     </form>
   );
 }
diff --git a/apps/registry/app/[locale]/request-component/page.tsx b/apps/registry/app/[locale]/request-component/page.tsx
new file mode 100644
index 00000000..065dff7f
--- /dev/null
+++ b/apps/registry/app/[locale]/request-component/page.tsx
@@ -0,0 +1,55 @@
+import { Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import { getTranslations, setRequestLocale } from "next-intl/server";
+
+import type { Locale } from "@/i18n/routing";
+import { canonical, languageAlternates } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+
+import { RequestComponentForm } from "./request-component-form";
+
+type Props = {
+  params: Promise<{ locale: Locale }>;
+};
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({
+    locale,
+    namespace: "pages.requestComponent",
+  });
+
+  return {
+    alternates: {
+      canonical: canonical("/request-component", locale),
+      languages: languageAlternates("/request-component"),
+    },
+    description: t("metaDescription"),
+    robots: { follow: true, index: false },
+    title: `${t("title")} - VLLNT UI`,
+  };
+}
+
+export default async function RequestComponentPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  const t = await getTranslations({
+    locale,
+    namespace: "pages.requestComponent",
+  });
+
+  return (
+    <>
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <div className="container mx-auto max-w-2xl px-4 py-16 lg:px-8">
+          <h1 className="text-4xl font-semibold mb-3">{t("title")}</h1>
+          <p className="text-muted-foreground text-lg mb-8">
+            {t("description")}
+          </p>
+          <RequestComponentForm />
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/request-component/request-component-form.tsx b/apps/registry/app/[locale]/request-component/request-component-form.tsx
similarity index 67%
rename from apps/registry/app/request-component/request-component-form.tsx
rename to apps/registry/app/[locale]/request-component/request-component-form.tsx
index ad28b1f3..f71b4df5 100644
--- a/apps/registry/app/request-component/request-component-form.tsx
+++ b/apps/registry/app/[locale]/request-component/request-component-form.tsx
@@ -1,7 +1,9 @@
 "use client";
 
+import { useId, useState } from "react";
+
+import { useTranslations } from "next-intl";
 import type * as React from "react";
-import { useState } from "react";
 
 const REPO = "vllnt/ui";
 
@@ -40,47 +42,53 @@ function buildIssueUrl({
     .filter(Boolean)
     .join("\n");
 
-  const params = new URLSearchParams({
-    template: "feature_request.yml",
-    title: `[feat] ${name || "new component"}`,
+  const parameters = new URLSearchParams({
     body,
     labels: "enhancement,component",
+    template: "feature_request.yml",
+    title: `[feat] ${name || "new component"}`,
   });
 
-  return `https://github.com/${REPO}/issues/new?${params.toString()}`;
+  return `https://github.com/${REPO}/issues/new?${parameters.toString()}`;
 }
 
 function Field({
-  autoFocus,
   label,
   onChange,
   placeholder,
   required,
   value,
 }: {
-  autoFocus?: boolean;
   label: string;
   onChange: (value: string) => void;
   placeholder?: string;
   required?: boolean;
   value: string;
 }) {
+  const labelId = useId();
+
   return (
-    <label className="block">
-      <span className="text-sm font-medium">
+    <div>
+      <span className="text-sm font-medium" id={labelId}>
         {label}
-        {required ? <span className="ml-1 text-destructive">*</span> : null}
+        {required ? (
+          <span aria-hidden="true" className="ml-1 text-destructive">
+            *
+          </span>
+        ) : null}
       </span>
       <input
-        autoFocus={autoFocus}
+        aria-labelledby={labelId}
         className="mt-2 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
-        onChange={(event) => onChange(event.target.value)}
+        onChange={(event) => {
+          onChange(event.target.value);
+        }}
         placeholder={placeholder}
         required={required}
         type="text"
         value={value}
       />
-    </label>
+    </div>
   );
 }
 
@@ -99,32 +107,42 @@ function TextField({
   rows?: number;
   value: string;
 }) {
+  const labelId = useId();
+
   return (
-    <label className="block">
-      <span className="text-sm font-medium">
+    <div>
+      <span className="text-sm font-medium" id={labelId}>
         {label}
-        {required ? <span className="ml-1 text-destructive">*</span> : null}
+        {required ? (
+          <span aria-hidden="true" className="ml-1 text-destructive">
+            *
+          </span>
+        ) : null}
       </span>
       <textarea
+        aria-labelledby={labelId}
         className="mt-2 block w-full rounded-md border border-border bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
-        onChange={(event) => onChange(event.target.value)}
+        onChange={(event) => {
+          onChange(event.target.value);
+        }}
         placeholder={placeholder}
         required={required}
         rows={rows}
         value={value}
       />
-    </label>
+    </div>
   );
 }
 
 export function RequestComponentForm() {
+  const t = useTranslations("forms.requestComponent");
   const [name, setName] = useState("");
   const [problem, setProblem] = useState("");
   const [similar, setSimilar] = useState("");
   const [useCase, setUseCase] = useState("");
   const [reference, setReference] = useState("");
 
-  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+  function handleSubmit(event: React.SyntheticEvent<HTMLFormElement>) {
     event.preventDefault();
     const url = buildIssueUrl({ name, problem, reference, similar, useCase });
     window.open(url, "_blank", "noopener,noreferrer");
@@ -133,38 +151,37 @@ export function RequestComponentForm() {
   return (
     <form className="space-y-5" onSubmit={handleSubmit}>
       <Field
-        autoFocus
-        label="Component name"
+        label={t("nameLabel")}
         onChange={setName}
-        placeholder="e.g. ToastStack"
+        placeholder={t("namePlaceholder")}
         required
         value={name}
       />
       <TextField
-        label="What problem does it solve?"
+        label={t("problemLabel")}
         onChange={setProblem}
-        placeholder="The user-facing need, not the implementation."
+        placeholder={t("problemPlaceholder")}
         required
         rows={3}
         value={problem}
       />
       <Field
-        label="Similar to (optional)"
+        label={t("similarLabel")}
         onChange={setSimilar}
-        placeholder="shadcn Toast, Radix Toast, etc."
+        placeholder={t("similarPlaceholder")}
         value={similar}
       />
       <TextField
-        label="Use case"
+        label={t("useCaseLabel")}
         onChange={setUseCase}
-        placeholder="The concrete scenario where you'd reach for this."
+        placeholder={t("useCasePlaceholder")}
         rows={3}
         value={useCase}
       />
       <TextField
-        label="References / prior art (optional)"
+        label={t("referenceLabel")}
         onChange={setReference}
-        placeholder="Links, screenshots, design references…"
+        placeholder={t("referencePlaceholder")}
         rows={3}
         value={reference}
       />
@@ -172,11 +189,9 @@ export function RequestComponentForm() {
         className="inline-flex h-10 items-center rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
         type="submit"
       >
-        Open prefilled GitHub issue
+        {t("submit")}
       </button>
-      <p className="text-xs text-muted-foreground">
-        Submitting opens a new GitHub issue tab. Nothing is sent to a server.
-      </p>
+      <p className="text-xs text-muted-foreground">{t("note")}</p>
     </form>
   );
 }
diff --git a/apps/registry/app/vs/page.tsx b/apps/registry/app/[locale]/vs/page.tsx
similarity index 73%
rename from apps/registry/app/vs/page.tsx
rename to apps/registry/app/[locale]/vs/page.tsx
index 105f97d1..d4180fb2 100644
--- a/apps/registry/app/vs/page.tsx
+++ b/apps/registry/app/[locale]/vs/page.tsx
@@ -1,61 +1,76 @@
 import { Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
-import Link from "next/link";
+import { setRequestLocale } from "next-intl/server";
 
-import { canonical } from "@/lib/seo";
+import { Link, type Locale } from "@/i18n/routing";
+import { canonical, languageAlternates } from "@/lib/seo";
 import { getSidebarSections } from "@/lib/sidebar-sections";
 
-export const metadata: Metadata = {
-  alternates: { canonical: canonical("/vs") },
-  description:
-    "Honest, evidence-based comparison of VLLNT UI vs shadcn/ui, Radix UI, HeadlessUI, and NextUI.",
-  title: "VLLNT UI vs · Comparisons",
+type Props = {
+  params: Promise<{ locale: Locale }>;
 };
 
-const COMPARISONS: ReadonlyArray<{
-  readonly slug: string;
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+
+  return {
+    alternates: {
+      canonical: canonical("/vs", locale),
+      languages: languageAlternates("/vs"),
+    },
+    description:
+      "Honest, evidence-based comparison of VLLNT UI vs shadcn/ui, Radix UI, HeadlessUI, and NextUI.",
+    title: "VLLNT UI vs · Comparisons",
+  };
+}
+
+const COMPARISONS: readonly {
+  readonly available: boolean;
   readonly name: string;
+  readonly slug: string;
   readonly tagline: string;
-  readonly available: boolean;
-}> = [
+}[] = [
   {
-    slug: "shadcn",
+    available: true,
     name: "shadcn/ui",
+    slug: "shadcn",
     tagline:
       "Closest sibling. Same registry format. Different component count and agent surface.",
-    available: true,
   },
   {
-    slug: "radix",
+    available: false,
     name: "Radix UI",
+    slug: "radix",
     tagline: "Accessible primitives — VLLNT UI is built on top of these.",
-    available: false,
   },
   {
-    slug: "headless-ui",
+    available: false,
     name: "HeadlessUI",
+    slug: "headless-ui",
     tagline: "Tailwind Labs primitives — different ecosystem.",
-    available: false,
   },
   {
-    slug: "nextui",
+    available: false,
     name: "NextUI",
+    slug: "nextui",
     tagline: "Component library with its own design language.",
-    available: false,
   },
 ];
 
-export default function VsIndexPage() {
+export default async function VsIndexPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+
   return (
     <>
-      <Sidebar sections={getSidebarSections()} />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto max-w-3xl px-4 py-16 lg:px-8">
           <h1 className="text-4xl font-semibold mb-3">VLLNT UI vs the rest</h1>
           <p className="text-muted-foreground text-lg mb-10">
             Honest comparisons. We call out where alternatives are stronger,
-            where VLLNT UI fits better, and where the gap is small enough to
-            not matter.
+            where VLLNT UI fits better, and where the gap is small enough to not
+            matter.
           </p>
 
           <ul className="space-y-3">
diff --git a/apps/registry/app/vs/shadcn/page.tsx b/apps/registry/app/[locale]/vs/shadcn/page.tsx
similarity index 86%
rename from apps/registry/app/vs/shadcn/page.tsx
rename to apps/registry/app/[locale]/vs/shadcn/page.tsx
index bdcda1f4..52945497 100644
--- a/apps/registry/app/vs/shadcn/page.tsx
+++ b/apps/registry/app/[locale]/vs/shadcn/page.tsx
@@ -1,142 +1,157 @@
 import { Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
+import { setRequestLocale } from "next-intl/server";
 
-import { canonical } from "@/lib/seo";
+import type { Locale } from "@/i18n/routing";
+import { canonical, languageAlternates } from "@/lib/seo";
 import { getSidebarSections } from "@/lib/sidebar-sections";
 import { getComponentCount, getLibraryVersion } from "@/lib/stats";
 
-export const metadata: Metadata = {
-  alternates: { canonical: canonical("/vs/shadcn") },
-  description:
-    "VLLNT UI vs shadcn/ui — registry format, component count, agent surface, theming, accessibility. Honest comparison.",
-  title: "VLLNT UI vs shadcn/ui",
+type Props = {
+  params: Promise<{ locale: Locale }>;
 };
 
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+
+  return {
+    alternates: {
+      canonical: canonical("/vs/shadcn", locale),
+      languages: languageAlternates("/vs/shadcn"),
+    },
+    description:
+      "VLLNT UI vs shadcn/ui - registry format, component count, agent surface, theming, accessibility. Honest comparison.",
+    title: "VLLNT UI vs shadcn/ui",
+  };
+}
+
 type Row = {
   readonly attribute: string;
-  readonly vllnt: string;
   readonly shadcn: string;
-  readonly winner?: "vllnt" | "shadcn" | "even";
+  readonly vllnt: string;
+  readonly winner?: "even" | "shadcn" | "vllnt";
 };
 
-export default function VsShadcnPage() {
+export default async function VsShadcnPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
   const componentCount = getComponentCount();
   const version = getLibraryVersion();
 
   const rows: readonly Row[] = [
     {
       attribute: "Component count",
-      vllnt: `${componentCount} components`,
       shadcn: "~50 components",
+      vllnt: `${componentCount} components`,
       winner: "vllnt",
     },
     {
       attribute: "Install model",
-      vllnt: "shadcn CLI against /r/<name>.json",
       shadcn: "shadcn CLI against ui.shadcn.com/r",
+      vllnt: "shadcn CLI against /r/<name>.json",
       winner: "even",
     },
     {
       attribute: "You own the source after install",
-      vllnt: "Yes",
       shadcn: "Yes",
+      vllnt: "Yes",
       winner: "even",
     },
     {
       attribute: "Sibling-component resolution",
-      vllnt: "Hybrid: leaf source + @vllnt/ui peer dep for siblings",
       shadcn: "All source inlined per component",
+      vllnt: "Hybrid: leaf source + @vllnt/ui peer dep for siblings",
       winner: "vllnt",
     },
     {
       attribute: "/llms.txt agent index",
-      vllnt: "Yes — llmstxt.org compliant",
       shadcn: "No",
+      vllnt: "Yes — llmstxt.org compliant",
       winner: "vllnt",
     },
     {
       attribute: "MCP server",
-      vllnt: "Yes — ui.vllnt.ai/mcp (search/get/list tools)",
       shadcn: "No",
+      vllnt: "Yes — ui.vllnt.ai/mcp (search/get/list tools)",
       winner: "vllnt",
     },
     {
       attribute: "Per-component a11y schema in JSON",
-      vllnt: "Yes — keyboard map, ARIA roles, focus model",
       shadcn: "No",
+      vllnt: "Yes — keyboard map, ARIA roles, focus model",
       winner: "vllnt",
     },
     {
       attribute: "Per-component examples in JSON",
-      vllnt: "Yes — code-as-data, agent-readable",
       shadcn: "No",
+      vllnt: "Yes — code-as-data, agent-readable",
       winner: "vllnt",
     },
     {
       attribute: "Per-component props schema in JSON",
-      vllnt: "Yes — TSDoc-shaped",
       shadcn: "No",
+      vllnt: "Yes — TSDoc-shaped",
       winner: "vllnt",
     },
     {
       attribute: "version + stability per component",
-      vllnt: "Yes (stable / beta / experimental / deprecated)",
       shadcn: "No",
+      vllnt: "Yes (stable / beta / experimental / deprecated)",
       winner: "vllnt",
     },
     {
       attribute: "Theming",
-      vllnt: "CSS variables + design tokens (DESIGN.md)",
       shadcn: "CSS variables",
+      vllnt: "CSS variables + design tokens (DESIGN.md)",
       winner: "vllnt",
     },
     {
       attribute: "Accessibility primitives",
-      vllnt: "Radix UI",
       shadcn: "Radix UI",
+      vllnt: "Radix UI",
       winner: "even",
     },
     {
       attribute: "Variant system",
-      vllnt: "CVA",
       shadcn: "CVA",
+      vllnt: "CVA",
       winner: "even",
     },
     {
       attribute: "Community size",
-      vllnt: "Smaller, growing",
       shadcn: "Massive — millions of installs",
+      vllnt: "Smaller, growing",
       winner: "shadcn",
     },
     {
       attribute: "Namespace recognition",
-      vllnt: "@vllnt/ui (newer)",
       shadcn: "shadcn (industry standard)",
+      vllnt: "@vllnt/ui (newer)",
       winner: "shadcn",
     },
     {
       attribute: "Tutorials + content",
-      vllnt: "Limited (young project)",
       shadcn: "Extensive — countless videos, blogs, courses",
+      vllnt: "Limited (young project)",
       winner: "shadcn",
     },
     {
       attribute: "Templates / starter kits",
-      vllnt: "Coming soon",
       shadcn: "Many official + community templates",
+      vllnt: "Coming soon",
       winner: "shadcn",
     },
     {
       attribute: "License",
-      vllnt: "MIT",
       shadcn: "MIT",
+      vllnt: "MIT",
       winner: "even",
     },
   ];
 
   return (
     <>
-      <Sidebar sections={getSidebarSections()} />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto max-w-4xl px-4 py-16 lg:px-8">
           <p className="text-sm uppercase tracking-wide text-muted-foreground">
@@ -150,8 +165,8 @@ export default function VsShadcnPage() {
               shadcn/ui is the industry standard. VLLNT UI is a younger sibling
               that takes the same registry idea further: more components, an
               agent-first surface (<code>/llms.txt</code>, <code>/mcp</code>,
-              richer JSON descriptors), and a hybrid install model that
-              dedupes shared primitives via <code>@vllnt/ui</code>.
+              richer JSON descriptors), and a hybrid install model that dedupes
+              shared primitives via <code>@vllnt/ui</code>.
             </p>
             <p>
               If you want maximum community signal and the largest pool of
@@ -203,8 +218,8 @@ export default function VsShadcnPage() {
               that benefits from being &ldquo;just shadcn&rdquo;.
             </p>
             <p>
-              <strong>Pick VLLNT UI</strong> when you need components beyond
-              the shadcn core (timelines, maps, AI compounds, runtime overlays,
+              <strong>Pick VLLNT UI</strong> when you need components beyond the
+              shadcn core (timelines, maps, AI compounds, runtime overlays,
               canvas primitives), when AI agents are part of your authoring
               flow, or when you want the registry data structured enough to
               query programmatically.
diff --git a/apps/registry/app/layout.tsx b/apps/registry/app/layout.tsx
deleted file mode 100644
index 0153efe7..00000000
--- a/apps/registry/app/layout.tsx
+++ /dev/null
@@ -1,113 +0,0 @@
-import "@vllnt/ui/styles.css";
-import "@vllnt/ui/themes/default.css";
-
-import { Analytics } from "@vercel/analytics/next";
-import { SpeedInsights } from "@vercel/speed-insights/next";
-import { SidebarProvider, ThemeProvider } from "@vllnt/ui";
-import type { Metadata } from "next";
-import type React from "react";
-
-import { Header } from "@/components/header";
-import { jsonLdScript, organizationLd, websiteLd } from "@/lib/jsonld";
-
-import "./globals.css";
-
-export const metadata: Metadata = {
-  applicationName: "VLLNT UI",
-  authors: [{ name: "VLLNT", url: "https://github.com/vllnt" }],
-  category: "Developer Tools",
-  creator: "VLLNT",
-  description:
-    "Agent-first React component registry. 225 accessible components built on Radix UI, Tailwind CSS, and CVA. Install via the shadcn CLI.",
-  formatDetection: {
-    address: false,
-    email: false,
-    telephone: false,
-  },
-  generator: "Next.js",
-  keywords: [
-    "react",
-    "components",
-    "react components",
-    "ui library",
-    "component library",
-    "tailwind",
-    "tailwindcss",
-    "radix",
-    "radix-ui",
-    "shadcn",
-    "shadcn-ui",
-    "registry",
-    "design system",
-    "accessible",
-    "typescript",
-    "ai",
-    "llms.txt",
-    "open source",
-  ],
-  metadataBase: new URL(
-    process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai",
-  ),
-  openGraph: {
-    locale: "en_US",
-    siteName: "VLLNT UI",
-    type: "website",
-  },
-  publisher: "VLLNT",
-  referrer: "origin-when-cross-origin",
-  robots: {
-    follow: true,
-    googleBot: {
-      follow: true,
-      index: true,
-      "max-image-preview": "large",
-      "max-snippet": -1,
-      "max-video-preview": -1,
-    },
-    index: true,
-  },
-  title: "VLLNT UI — 225 agent-first React components",
-  twitter: {
-    card: "summary_large_image",
-    creator: "@vllnt",
-    site: "@vllnt",
-  },
-};
-
-export default function RootLayout({
-  children,
-}: {
-  readonly children: React.ReactNode;
-}) {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <script
-          dangerouslySetInnerHTML={{ __html: jsonLdScript(organizationLd()) }}
-          type="application/ld+json"
-        />
-        <script
-          dangerouslySetInnerHTML={{ __html: jsonLdScript(websiteLd()) }}
-          type="application/ld+json"
-        />
-      </head>
-      <body className="h-full overflow-hidden">
-        <ThemeProvider
-          attribute="class"
-          defaultTheme="dark"
-          disableTransitionOnChange
-          enableSystem
-        >
-          <SidebarProvider>
-            <div className="flex h-full flex-col overflow-hidden">
-              <Header />
-              <div className="flex flex-1 overflow-hidden">{children}</div>
-            </div>
-          </SidebarProvider>
-        </ThemeProvider>
-        <Analytics />
-        <SpeedInsights />
-      </body>
-    </html>
-  );
-}
diff --git a/apps/registry/app/llms-full.txt/route.ts b/apps/registry/app/llms-full.txt/route.ts
index c1c5fb42..5f662449 100644
--- a/apps/registry/app/llms-full.txt/route.ts
+++ b/apps/registry/app/llms-full.txt/route.ts
@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/naming-convention, functional/no-loop-statements, max-lines-per-function */
+
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 
@@ -6,15 +8,15 @@ import registry from "../../registry.json";
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
 
 type RegistryItem = {
-  readonly name: string;
-  readonly title: string;
-  readonly description: string;
   readonly category: string;
   readonly dependencies?: readonly string[];
+  readonly description: string;
+  readonly name: string;
   readonly registryDependencies?: readonly string[];
+  readonly title: string;
 };
 
-const DOC_PAGES: ReadonlyArray<{ slug: string; title: string }> = [
+const DOC_PAGES: readonly { slug: string; title: string }[] = [
   { slug: "home", title: "Get Started" },
   { slug: "docs", title: "Documentation" },
   { slug: "philosophy", title: "Philosophy" },
@@ -28,13 +30,8 @@ function stripFrontmatter(source: string): string {
   return source.slice(end + 4).replace(/^\n+/, "");
 }
 
-async function readDocPage(slug: string): Promise<string> {
-  const file = path.join(
-    process.cwd(),
-    "content",
-    "pages",
-    `${slug}.mdx`,
-  );
+async function readDocumentPage(slug: string): Promise<string> {
+  const file = path.join(process.cwd(), "content", "pages", slug, "en.mdx");
   try {
     const raw = await readFile(file, "utf8");
     return stripFrontmatter(raw).trim();
@@ -66,7 +63,7 @@ async function buildLlmsFullTxt(): Promise<string> {
   lines.push("");
 
   for (const page of DOC_PAGES) {
-    const body = await readDocPage(page.slug);
+    const body = await readDocumentPage(page.slug);
     if (!body) continue;
     lines.push(`## ${page.title}`);
     lines.push("");
@@ -107,14 +104,15 @@ async function buildLlmsFullTxt(): Promise<string> {
 }
 
 export const dynamic = "force-static";
-export const revalidate = 86400;
+export const revalidate = 86_400;
 
 export async function GET(): Promise<Response> {
   const body = await buildLlmsFullTxt();
   return new Response(body, {
     headers: {
+      "Cache-Control":
+        "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
       "Content-Type": "text/plain; charset=utf-8",
-      "Cache-Control": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
     },
   });
 }
diff --git a/apps/registry/app/llms.txt/route.ts b/apps/registry/app/llms.txt/route.ts
index 32130fb2..a87a58e9 100644
--- a/apps/registry/app/llms.txt/route.ts
+++ b/apps/registry/app/llms.txt/route.ts
@@ -1,12 +1,14 @@
+/* eslint-disable @typescript-eslint/naming-convention, functional/no-loop-statements, max-lines-per-function */
+
 import registry from "../../registry.json";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
 
 type RegistryItem = {
+  readonly category: string;
+  readonly description: string;
   readonly name: string;
   readonly title: string;
-  readonly description: string;
-  readonly category: string;
 };
 
 const CATEGORY_ORDER: readonly string[] = [
@@ -51,9 +53,7 @@ function buildLlmsTxt(): string {
 
   const sortedCategories = [
     ...CATEGORY_ORDER.filter((c) => grouped.has(c)),
-    ...[...grouped.keys()]
-      .filter((c) => !CATEGORY_ORDER.includes(c))
-      .sort(),
+    ...[...grouped.keys()].filter((c) => !CATEGORY_ORDER.includes(c)).sort(),
   ];
 
   const lines: string[] = [];
@@ -73,6 +73,9 @@ function buildLlmsTxt(): string {
   lines.push(
     `- [Documentation](${SITE_URL}/docs): theming, registry usage, conventions`,
   );
+  lines.push(
+    `- [Documentation FR](${SITE_URL}/fr/docs): version francaise de la documentation`,
+  );
   lines.push(
     `- [Philosophy](${SITE_URL}/philosophy): design principles and component patterns`,
   );
@@ -89,6 +92,12 @@ function buildLlmsTxt(): string {
   lines.push(
     `- [Sitemap](${SITE_URL}/sitemap.xml): every public route, refreshed per deploy`,
   );
+  lines.push(
+    `- [French llms.txt](${SITE_URL}/fr/llms.txt): localized agent index`,
+  );
+  lines.push(
+    `- [French llms-full.txt](${SITE_URL}/fr/llms-full.txt): localized long-form agent context`,
+  );
   lines.push(
     "- Install command: `pnpm dlx shadcn@latest add " +
       `${SITE_URL}/r/<name>.json` +
@@ -102,7 +111,9 @@ function buildLlmsTxt(): string {
     const label = CATEGORY_LABEL[category] ?? category;
     lines.push(`## Components — ${label}`);
     lines.push("");
-    for (const item of [...bucket].sort((a, b) => a.name.localeCompare(b.name))) {
+    for (const item of [...bucket].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
       lines.push(
         `- [${item.title}](${SITE_URL}/components/${item.name}): ${item.description}`,
       );
@@ -114,13 +125,14 @@ function buildLlmsTxt(): string {
 }
 
 export const dynamic = "force-static";
-export const revalidate = 86400;
+export const revalidate = 86_400;
 
 export function GET(): Response {
   return new Response(buildLlmsTxt(), {
     headers: {
+      "Cache-Control":
+        "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
       "Content-Type": "text/plain; charset=utf-8",
-      "Cache-Control": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
     },
   });
 }
diff --git a/apps/registry/app/page.tsx b/apps/registry/app/page.tsx
deleted file mode 100644
index d3b6a6cf..00000000
--- a/apps/registry/app/page.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-import { Sidebar } from "@vllnt/ui";
-import type { Metadata } from "next";
-
-import { Landing } from "@/components/landing/landing";
-import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical } from "@/lib/seo";
-import { getSidebarSections } from "@/lib/sidebar-sections";
-import { getComponentCount, getLibraryVersion } from "@/lib/stats";
-
-export function generateMetadata(): Metadata {
-  const componentCount = getComponentCount();
-  const version = getLibraryVersion();
-  const title = `VLLNT UI — ${componentCount} agent-first React components`;
-  const description = `Install any of ${componentCount} accessible React components with the shadcn CLI. Built on Radix UI, Tailwind CSS, and CVA. Every component is a machine-readable JSON descriptor agents can consume directly. v${version}, MIT licensed.`;
-
-  return {
-    alternates: { canonical: canonical("/") },
-    description,
-    openGraph: generateOGMetadata({
-      description,
-      title,
-      type: "home",
-    }),
-    title,
-    twitter: generateTwitterMetadata({
-      description,
-      title,
-      type: "home",
-    }),
-  };
-}
-
-export default function HomePage() {
-  return (
-    <>
-      <Sidebar sections={getSidebarSections()} />
-      <main className="flex-1 overflow-y-auto bg-background">
-        <Landing />
-      </main>
-    </>
-  );
-}
diff --git a/apps/registry/app/r/[name]/route.ts b/apps/registry/app/r/[name]/route.ts
index b5a9aef9..ab58192d 100644
--- a/apps/registry/app/r/[name]/route.ts
+++ b/apps/registry/app/r/[name]/route.ts
@@ -3,6 +3,11 @@ import path from "node:path";
 
 import { NextResponse } from "next/server";
 
+import { isLocale, type Locale } from "@/i18n/routing";
+import {
+  getDescriptionSourceLocale,
+  getLocalizedDescription,
+} from "@/lib/registry-i18n";
 import registryData from "@/registry.json";
 import type { Registry, RegistryComponent } from "@/types/registry";
 
@@ -23,13 +28,41 @@ async function readComponentFile(filePath: string) {
   }
 }
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
+function parseRegistryName(
+  rawName: string,
+): undefined | { componentName: string; locale?: Locale; overlay: boolean } {
+  const overlayMatch = /^(.+)\.([a-z]{2}(?:-[A-Z]{2})?)\.json$/.exec(rawName);
+  if (overlayMatch?.[1] && overlayMatch[2]) {
+    if (!isLocale(overlayMatch[2])) return undefined;
+    return {
+      componentName: overlayMatch[1],
+      locale: overlayMatch[2],
+      overlay: true,
+    };
+  }
+
+  return {
+    componentName: rawName.endsWith(".json") ? rawName.slice(0, -5) : rawName,
+    overlay: false,
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention, max-lines-per-function
 export async function GET(_request: Request, routeParameters: RouteParameters) {
   try {
     const { name } = await routeParameters.params;
+    const parsed = parseRegistryName(name);
+    if (!parsed) {
+      return NextResponse.json(
+        { error: "Locale not supported" },
+        { status: 404 },
+      );
+    }
+
     const component = registry.items.find(
       (item): item is RegistryComponent =>
-        item.name === name && item.type === "registry:component",
+        item.name === parsed.componentName &&
+        item.type === "registry:component",
     );
 
     if (!component) {
@@ -39,6 +72,25 @@ export async function GET(_request: Request, routeParameters: RouteParameters) {
       );
     }
 
+    if (parsed.overlay) {
+      const locale = parsed.locale;
+      if (!locale) {
+        return NextResponse.json(
+          { error: "Locale not supported" },
+          { status: 404 },
+        );
+      }
+
+      return NextResponse.json({
+        canonical: `/r/${component.name}.json`,
+        description: getLocalizedDescription(component, locale),
+        locale,
+        name: component.name,
+        sourceLocale: getDescriptionSourceLocale(component, locale),
+        title: component.title,
+      });
+    }
+
     const files = await Promise.all(
       component.files.map((file) => readComponentFile(file.path)),
     );
diff --git a/apps/registry/app/report/page.tsx b/apps/registry/app/report/page.tsx
deleted file mode 100644
index 22bd14db..00000000
--- a/apps/registry/app/report/page.tsx
+++ /dev/null
@@ -1,43 +0,0 @@
-import { Sidebar } from "@vllnt/ui";
-import type { Metadata } from "next";
-
-import { canonical } from "@/lib/seo";
-import { getSidebarSections } from "@/lib/sidebar-sections";
-
-import { ReportBugForm } from "./report-bug-form";
-
-export const metadata: Metadata = {
-  alternates: { canonical: canonical("/report") },
-  description:
-    "Report a bug in VLLNT UI. The form opens a prefilled GitHub issue — no backend.",
-  robots: { follow: true, index: false },
-  title: "Report a bug · VLLNT UI",
-};
-
-type SearchParameters = {
-  readonly component?: string;
-};
-
-export default async function ReportBugPage({
-  searchParams,
-}: {
-  searchParams: Promise<SearchParameters>;
-}) {
-  const { component } = await searchParams;
-
-  return (
-    <>
-      <Sidebar sections={getSidebarSections()} />
-      <main className="flex-1 overflow-y-auto bg-background">
-        <div className="container mx-auto max-w-2xl px-4 py-16 lg:px-8">
-          <h1 className="text-4xl font-semibold mb-3">Report a bug</h1>
-          <p className="text-muted-foreground text-lg mb-8">
-            Found something broken? Fill out the fields and we&rsquo;ll open a
-            prefilled GitHub issue with the right labels and template.
-          </p>
-          <ReportBugForm initialComponent={component ?? ""} />
-        </div>
-      </main>
-    </>
-  );
-}
diff --git a/apps/registry/app/request-component/page.tsx b/apps/registry/app/request-component/page.tsx
deleted file mode 100644
index d57b7373..00000000
--- a/apps/registry/app/request-component/page.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-import { Sidebar } from "@vllnt/ui";
-import type { Metadata } from "next";
-
-import { canonical } from "@/lib/seo";
-import { getSidebarSections } from "@/lib/sidebar-sections";
-
-import { RequestComponentForm } from "./request-component-form";
-
-export const metadata: Metadata = {
-  alternates: { canonical: canonical("/request-component") },
-  description:
-    "Request a new VLLNT UI component. The form opens a prefilled GitHub issue — no backend.",
-  robots: { follow: true, index: false },
-  title: "Request a component · VLLNT UI",
-};
-
-export default function RequestComponentPage() {
-  return (
-    <>
-      <Sidebar sections={getSidebarSections()} />
-      <main className="flex-1 overflow-y-auto bg-background">
-        <div className="container mx-auto max-w-2xl px-4 py-16 lg:px-8">
-          <h1 className="text-4xl font-semibold mb-3">Request a component</h1>
-          <p className="text-muted-foreground text-lg mb-8">
-            Don&rsquo;t see what you need? Fill out the fields and we&rsquo;ll
-            open a prefilled GitHub issue with the right labels and template.
-          </p>
-          <RequestComponentForm />
-        </div>
-      </main>
-    </>
-  );
-}
diff --git a/apps/registry/app/sitemap.ts b/apps/registry/app/sitemap.ts
index 816f585b..d8b44094 100644
--- a/apps/registry/app/sitemap.ts
+++ b/apps/registry/app/sitemap.ts
@@ -1,5 +1,10 @@
+/* eslint-disable max-lines-per-function */
+
 import type { MetadataRoute } from "next";
 
+import { routing } from "@/i18n/routing";
+import { canonical, languageAlternates } from "@/lib/seo";
+
 import registry from "../registry.json";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
@@ -11,54 +16,63 @@ type RegistryItem = {
 export default function sitemap(): MetadataRoute.Sitemap {
   const lastModified = new Date();
 
-  const staticRoutes: MetadataRoute.Sitemap = [
+  const staticPaths = [
+    { changeFrequency: "weekly" as const, pathname: "/", priority: 1 },
     {
-      url: SITE_URL,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 1.0,
-    },
-    {
-      url: `${SITE_URL}/components`,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 1.0,
+      changeFrequency: "weekly" as const,
+      pathname: "/components",
+      priority: 1,
     },
+    { changeFrequency: "weekly" as const, pathname: "/docs", priority: 0.8 },
     {
-      url: `${SITE_URL}/docs`,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 0.8,
+      changeFrequency: "monthly" as const,
+      pathname: "/philosophy",
+      priority: 0.6,
     },
+    { changeFrequency: "monthly" as const, pathname: "/vs", priority: 0.5 },
     {
-      url: `${SITE_URL}/philosophy`,
-      lastModified,
-      changeFrequency: "monthly",
-      priority: 0.6,
+      changeFrequency: "monthly" as const,
+      pathname: "/vs/shadcn",
+      priority: 0.5,
     },
   ];
 
+  const staticRoutes: MetadataRoute.Sitemap = staticPaths.flatMap((route) =>
+    routing.locales.map((locale) => ({
+      alternates: { languages: languageAlternates(route.pathname) },
+      changeFrequency: route.changeFrequency,
+      lastModified,
+      priority: route.priority,
+      url: canonical(route.pathname, locale),
+    })),
+  );
+
   const items = (registry as { readonly items: readonly RegistryItem[] }).items;
 
-  const componentRoutes: MetadataRoute.Sitemap = items.map((item) => ({
-    url: `${SITE_URL}/components/${item.name}`,
-    lastModified,
-    changeFrequency: "weekly",
-    priority: 0.7,
-  }));
+  const componentRoutes: MetadataRoute.Sitemap = items.flatMap((item) =>
+    routing.locales.map((locale) => ({
+      alternates: {
+        languages: languageAlternates(`/components/${item.name}`),
+      },
+      changeFrequency: "weekly" as const,
+      lastModified,
+      priority: 0.7,
+      url: canonical(`/components/${item.name}`, locale),
+    })),
+  );
 
   const registryEndpoints: MetadataRoute.Sitemap = [
     {
-      url: `${SITE_URL}/r/registry.json`,
-      lastModified,
       changeFrequency: "weekly",
+      lastModified,
       priority: 0.3,
+      url: `${SITE_URL}/r/registry.json`,
     },
     ...items.map((item) => ({
-      url: `${SITE_URL}/r/${item.name}.json`,
-      lastModified,
       changeFrequency: "weekly" as const,
+      lastModified,
       priority: 0.3,
+      url: `${SITE_URL}/r/${item.name}.json`,
     })),
   ];
 
diff --git a/apps/registry/components/footer/footer.tsx b/apps/registry/components/footer/footer.tsx
index 1f4787bb..876da891 100644
--- a/apps/registry/components/footer/footer.tsx
+++ b/apps/registry/components/footer/footer.tsx
@@ -1,4 +1,8 @@
-import Link from "next/link";
+/* eslint-disable max-lines-per-function */
+
+import { useTranslations } from "next-intl";
+
+import { Link } from "@/i18n/routing";
 
 const GITHUB_URL = "https://github.com/vllnt/ui";
 const STORYBOOK_URL = "https://storybook.vllnt.ai";
@@ -12,70 +16,81 @@ const LICENSE_URL = "https://github.com/vllnt/ui/blob/main/LICENSE";
 const COC_URL = "https://github.com/vllnt/ui/blob/main/CODE_OF_CONDUCT.md";
 
 type FooterLink = {
+  readonly external?: boolean;
   readonly href: string;
   readonly label: string;
-  readonly external?: boolean;
+  readonly localized?: boolean;
 };
 
 type FooterColumn = {
-  readonly title: string;
   readonly links: readonly FooterLink[];
+  readonly title: string;
 };
 
-const COLUMNS: readonly FooterColumn[] = [
-  {
-    title: "Library",
-    links: [
-      { href: "/components", label: "Components" },
-      { href: "/docs", label: "Docs" },
-      { href: "/philosophy", label: "Philosophy" },
-    ],
-  },
-  {
-    title: "Resources",
-    links: [
-      { external: true, href: STORYBOOK_URL, label: "Storybook" },
-      { href: "/r/registry.json", label: "Registry JSON" },
-      { href: "/llms.txt", label: "llms.txt" },
-      { href: "/mcp", label: "MCP" },
-      { external: true, href: GITHUB_URL, label: "GitHub" },
-    ],
-  },
-  {
-    title: "Community",
-    links: [
-      { external: true, href: REQUEST_URL, label: "Request a component" },
-      { external: true, href: REPORT_URL, label: "Report a bug" },
-      { external: true, href: DISCUSSIONS_URL, label: "Discussions" },
-      { external: true, href: SPONSOR_URL, label: "Sponsor" },
-    ],
-  },
-  {
-    title: "Legal",
-    links: [
-      { external: true, href: LICENSE_URL, label: "License (MIT)" },
-      { external: true, href: COC_URL, label: "Code of Conduct" },
-    ],
-  },
-];
-
 export function Footer() {
+  const t = useTranslations("footer");
+  const common = useTranslations("common");
+  const columns: readonly FooterColumn[] = [
+    {
+      links: [
+        { href: "/components", label: common("components") },
+        { href: "/docs", label: common("docs") },
+        { href: "/philosophy", label: common("philosophy") },
+      ],
+      title: t("library"),
+    },
+    {
+      links: [
+        { external: true, href: STORYBOOK_URL, label: t("storybook") },
+        {
+          href: "/r/registry.json",
+          label: t("registryJson"),
+          localized: false,
+        },
+        { href: "/llms.txt", label: "llms.txt", localized: false },
+        { href: "/mcp", label: "MCP", localized: false },
+        { external: true, href: GITHUB_URL, label: common("github") },
+      ],
+      title: t("resources"),
+    },
+    {
+      links: [
+        {
+          external: true,
+          href: REQUEST_URL,
+          label: common("requestComponent"),
+        },
+        { external: true, href: REPORT_URL, label: t("reportBug") },
+        { external: true, href: DISCUSSIONS_URL, label: t("discussions") },
+        { external: true, href: SPONSOR_URL, label: t("sponsor") },
+      ],
+      title: t("community"),
+    },
+    {
+      links: [
+        { external: true, href: LICENSE_URL, label: "License (MIT)" },
+        { external: true, href: COC_URL, label: "Code of Conduct" },
+      ],
+      title: t("legal"),
+    },
+  ];
+
   return (
     <footer className="border-t border-border bg-background">
       <div className="mx-auto max-w-7xl px-4 py-12 lg:px-8">
         <div className="grid grid-cols-2 gap-8 sm:grid-cols-4">
-          {COLUMNS.map((column) => (
+          {columns.map((column) => (
             <div key={column.title}>
               <h3 className="text-sm font-semibold">{column.title}</h3>
               <ul className="mt-4 space-y-2">
                 {column.links.map((link) =>
-                  link.external ? (
+                  link.external || link.localized === false ? (
                     <li key={link.href}>
                       <a
                         className="text-sm text-muted-foreground hover:text-foreground"
                         href={link.href}
-                        rel="noreferrer"
-                        target="_blank"
+                        rel={link.external ? "noreferrer" : undefined}
+                        target={link.external ? "_blank" : undefined}
                       >
                         {link.label}
                       </a>
@@ -96,11 +111,9 @@ export function Footer() {
           ))}
         </div>
         <div className="mt-12 flex flex-col gap-2 border-t border-border pt-6 sm:flex-row sm:items-center sm:justify-between">
+          <p className="text-xs text-muted-foreground">{t("builtWith")}</p>
           <p className="text-xs text-muted-foreground">
-            VLLNT UI · MIT licensed · Built with Radix UI, Tailwind CSS, and CVA
-          </p>
-          <p className="text-xs text-muted-foreground">
-            Maintained by{" "}
+            {t("maintainedBy")}{" "}
             <a
               className="hover:text-foreground"
               href="https://github.com/vllnt"
diff --git a/apps/registry/components/header/header.tsx b/apps/registry/components/header/header.tsx
index 54842b4b..152c3131 100644
--- a/apps/registry/components/header/header.tsx
+++ b/apps/registry/components/header/header.tsx
@@ -1,9 +1,17 @@
 "use client";
 
 import { NavbarSaas, SearchDialog } from "@vllnt/ui";
-import { Github } from "lucide-react";
-import { useRouter } from "next/navigation";
+import { ExternalLink, Languages } from "lucide-react";
+import { useTranslations } from "next-intl";
 
+import {
+  Link,
+  type Locale,
+  routing,
+  usePathname,
+  useRouter,
+} from "@/i18n/routing";
+import { localizePathname } from "@/lib/seo";
 import registryData from "@/registry.json";
 
 const GITHUB_URL = "https://github.com/vllnt/ui";
@@ -12,14 +20,26 @@ type Registry = {
   items: { description?: string; name: string; title: string; type: string }[];
 };
 
-export function Header() {
+type HeaderProps = {
+  locale: Locale;
+};
+
+export function Header({ locale }: HeaderProps) {
   const router = useRouter();
+  const pathname = usePathname();
+  const t = useTranslations("header");
   const registry = registryData as Registry;
 
   const navItems = [
-    { href: "/", title: "Get Started" },
-    { href: "/philosophy", title: "Philosophy" },
-    { href: "/components", title: "Components" },
+    { href: localizePathname("/", locale), title: t("navGetStarted") },
+    {
+      href: localizePathname("/philosophy", locale),
+      title: t("navPhilosophy"),
+    },
+    {
+      href: localizePathname("/components", locale),
+      title: t("navComponents"),
+    },
   ];
 
   const searchItems = registry.items
@@ -37,23 +57,40 @@ export function Header() {
       rightSlot={
         <div className="flex items-center gap-2">
           <SearchDialog
-            buttonText="Search components..."
-            emptyText="No components found."
-            groupHeading="Components"
+            buttonText={t("searchButton")}
+            emptyText={t("searchEmpty")}
+            groupHeading={t("searchGroup")}
             items={searchItems}
             onSelect={(item) => {
               router.push(`/components/${item.id}`);
             }}
-            searchPlaceholder="Search components..."
+            searchPlaceholder={t("searchPlaceholder")}
           />
+          <div className="flex items-center rounded-md border border-border">
+            <Languages
+              aria-hidden="true"
+              className="ml-2 h-4 w-4 text-muted-foreground"
+            />
+            {routing.locales.map((entry) => (
+              <Link
+                aria-current={entry === locale ? "page" : undefined}
+                className="px-2 py-1 text-xs font-medium uppercase text-muted-foreground hover:text-foreground aria-[current=page]:text-foreground"
+                href={pathname}
+                key={entry}
+                locale={entry}
+              >
+                {entry}
+              </Link>
+            ))}
+          </div>
           <a
-            aria-label="VLLNT UI on GitHub"
+            aria-label={t("githubLabel")}
             className="inline-flex h-9 w-9 items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-foreground"
             href={GITHUB_URL}
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
+            <ExternalLink className="h-4 w-4" />
           </a>
         </div>
       }
diff --git a/apps/registry/components/landing/landing.tsx b/apps/registry/components/landing/landing.tsx
index 14aa6d5c..1a47c299 100644
--- a/apps/registry/components/landing/landing.tsx
+++ b/apps/registry/components/landing/landing.tsx
@@ -1,13 +1,11 @@
+/* eslint-disable max-lines-per-function */
+
 import { CodeBlock } from "@vllnt/ui";
-import {
-  ArrowRight,
-  Github,
-  Sparkles,
-  Terminal,
-} from "lucide-react";
-import Link from "next/link";
+import { ArrowRight, ExternalLink, Sparkles, Terminal } from "lucide-react";
+import { useTranslations } from "next-intl";
 
 import { Footer } from "@/components/footer/footer";
+import { Link } from "@/i18n/routing";
 import {
   getCategoryCount,
   getComponentCount,
@@ -21,13 +19,6 @@ const STORYBOOK_URL = "https://storybook.vllnt.ai";
 const REQUEST_URL =
   "https://github.com/vllnt/ui/issues/new?template=feature_request.yml&labels=enhancement,component";
 
-const TRUST_BADGES = [
-  { label: "MIT" },
-  { label: "TypeScript" },
-  { label: "RSC compatible" },
-  { label: "Tailwind v4 ready" },
-];
-
 function Hero({
   componentCount,
   version,
@@ -35,26 +26,32 @@ function Hero({
   componentCount: number;
   version: string;
 }) {
+  const t = useTranslations("landing.hero");
+  const trustBadges = [
+    { label: "MIT" },
+    { label: "TypeScript" },
+    { label: t("rscCompatible") },
+    { label: t("tailwindReady") },
+  ];
+
   return (
     <section className="border-b border-border">
       <div className="mx-auto max-w-7xl px-4 py-20 lg:px-8">
         <p className="text-sm font-medium uppercase tracking-wide text-muted-foreground">
-          v{version} · MIT
+          {t("kicker", { version })}
         </p>
         <h1 className="mt-3 text-4xl font-semibold leading-tight md:text-5xl lg:text-6xl">
-          {componentCount} agent-first React components.
+          {t("title", { count: componentCount })}
           <br />
-          <span className="text-muted-foreground">Copy, paste, ship.</span>
+          <span className="text-muted-foreground">{t("subtitle")}</span>
         </h1>
         <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
-          Built on Radix UI, Tailwind CSS, and CVA. Every component is also a
-          machine-readable JSON descriptor: agents (Claude, Cursor, Cline,
-          Continue) read the registry directly without scraping HTML.
+          {t("description")}
         </p>
 
         <div className="mt-8">
           <CodeBlock language="bash">
-            {`pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/button.json`}
+            pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/button.json
           </CodeBlock>
         </div>
 
@@ -63,14 +60,14 @@ function Hero({
             className="inline-flex h-11 items-center gap-2 rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
             href="/components"
           >
-            Browse {componentCount} components
+            {t("browseComponents", { count: componentCount })}
             <ArrowRight className="h-4 w-4" />
           </Link>
           <Link
             className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
             href="/docs"
           >
-            Read the docs
+            {t("readDocs")}
           </Link>
           <a
             className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
@@ -78,13 +75,13 @@ function Hero({
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
-            GitHub
+            <ExternalLink className="h-4 w-4" />
+            {t("github")}
           </a>
         </div>
 
         <ul className="mt-8 flex flex-wrap gap-3 text-xs text-muted-foreground">
-          {TRUST_BADGES.map((badge) => (
+          {trustBadges.map((badge) => (
             <li
               className="rounded-full border border-border bg-muted/40 px-3 py-1"
               key={badge.label}
@@ -109,16 +106,18 @@ function Stats({
   generatedAt?: string;
   version: string;
 }) {
+  const t = useTranslations("landing.stats");
+
   return (
     <section className="border-b border-border bg-muted/30">
       <div className="mx-auto grid max-w-7xl grid-cols-2 gap-6 px-4 py-12 lg:grid-cols-4 lg:px-8">
-        <Stat label="Components" value={String(componentCount)} />
-        <Stat label="Categories" value={String(categoryCount)} />
-        <Stat label="Library version" value={`v${version}`} />
+        <Stat label={t("components")} value={String(componentCount)} />
+        <Stat label={t("categories")} value={String(categoryCount)} />
+        <Stat label={t("libraryVersion")} value={`v${version}`} />
         <Stat
-          label="Last build"
+          label={t("lastBuild")}
           value={
-            generatedAt ? new Date(generatedAt).toISOString().slice(0, 10) : "—"
+            generatedAt ? new Date(generatedAt).toISOString().slice(0, 10) : "-"
           }
         />
       </div>
@@ -136,36 +135,33 @@ function Stat({ label, value }: { label: string; value: string }) {
 }
 
 function AgentCallout() {
+  const t = useTranslations("landing.agent");
+
   return (
     <section className="border-b border-border">
       <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
         <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
           <Sparkles className="h-4 w-4" />
-          Agent-first
+          {t("eyebrow")}
         </div>
-        <h2 className="mt-2 text-3xl font-semibold">
-          Built so AI coding agents can use it directly.
-        </h2>
+        <h2 className="mt-2 text-3xl font-semibold">{t("title")}</h2>
         <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
-          Every component ships as a machine-readable JSON descriptor with
-          name, version, stability, accessibility schema, usage examples,
-          and prop definitions. Agents discover the registry through three
-          surfaces.
+          {t("description")}
         </p>
 
         <div className="mt-8 grid gap-4 md:grid-cols-3">
           <AgentCard
-            description="Concise index per the llmstxt.org spec — sections, links, descriptions."
+            description={t("llmsDescription")}
             href="/llms.txt"
             title="/llms.txt"
           />
           <AgentCard
-            description="Full registry context in one fetch — docs + per-component descriptors."
+            description={t("llmsFullDescription")}
             href="/llms-full.txt"
             title="/llms-full.txt"
           />
           <AgentCard
-            description="Streamable HTTP MCP server. Tools: search_components, get_component, list_categories."
+            description={t("mcpDescription")}
             href="/mcp"
             title="/mcp"
           />
@@ -184,6 +180,8 @@ function AgentCard({
   href: string;
   title: string;
 }) {
+  const t = useTranslations("landing.agent");
+
   return (
     <a
       className="group rounded-lg border border-border p-5 hover:border-foreground/40"
@@ -197,7 +195,7 @@ function AgentCard({
       </div>
       <p className="mt-3 text-sm text-muted-foreground">{description}</p>
       <p className="mt-4 inline-flex items-center gap-1 text-xs font-medium text-foreground">
-        Open
+        {t("open")}
         <ArrowRight className="h-3 w-3 transition-transform group-hover:translate-x-0.5" />
       </p>
     </a>
@@ -205,15 +203,19 @@ function AgentCard({
 }
 
 function FeaturedComponents() {
+  const t = useTranslations("landing.featured");
   const featured = getFeaturedComponents();
   if (featured.length === 0) return null;
   return (
     <section className="border-b border-border">
       <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-        <h2 className="text-2xl font-semibold">Featured components</h2>
+        <h2 className="text-2xl font-semibold">{t("title")}</h2>
         <p className="mt-2 text-muted-foreground">
-          A few favourites. Browse all {getComponentCount()} from{" "}
-          <Link className="font-medium text-foreground underline" href="/components">
+          {t("description", { count: getComponentCount() })}{" "}
+          <Link
+            className="font-medium text-foreground underline"
+            href="/components"
+          >
             /components
           </Link>
           .
@@ -240,13 +242,14 @@ function FeaturedComponents() {
 }
 
 function CommunityCTA() {
+  const t = useTranslations("landing.community");
+
   return (
     <section>
       <div className="mx-auto max-w-7xl px-4 py-20 lg:px-8">
-        <h2 className="text-3xl font-semibold">Build with the community.</h2>
+        <h2 className="text-3xl font-semibold">{t("title")}</h2>
         <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
-          MIT licensed. No tracking. No backend. Issues, ideas, and pull
-          requests welcome.
+          {t("description")}
         </p>
         <div className="mt-8 flex flex-wrap gap-3">
           <a
@@ -255,8 +258,8 @@ function CommunityCTA() {
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
-            Star on GitHub
+            <ExternalLink className="h-4 w-4" />
+            {t("starGithub")}
           </a>
           <a
             className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
@@ -264,7 +267,7 @@ function CommunityCTA() {
             rel="noreferrer"
             target="_blank"
           >
-            Request a component
+            {t("requestComponent")}
           </a>
           <a
             className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
@@ -272,7 +275,7 @@ function CommunityCTA() {
             rel="noreferrer"
             target="_blank"
           >
-            Open Storybook
+            {t("openStorybook")}
           </a>
         </div>
       </div>
diff --git a/apps/registry/content/pages/components.mdx b/apps/registry/content/pages/components/en.mdx
similarity index 100%
rename from apps/registry/content/pages/components.mdx
rename to apps/registry/content/pages/components/en.mdx
diff --git a/apps/registry/content/pages/components/fr.mdx b/apps/registry/content/pages/components/fr.mdx
new file mode 100644
index 00000000..7b7c4763
--- /dev/null
+++ b/apps/registry/content/pages/components/fr.mdx
@@ -0,0 +1,9 @@
+---
+title: Composants
+description: Explorez tous les composants disponibles dans la bibliotheque VLLNT UI.
+type: component
+og:
+  title: Composants
+  description: Explorez tous les composants VLLNT UI
+  type: component
+---
diff --git a/apps/registry/content/pages/docs.mdx b/apps/registry/content/pages/docs/en.mdx
similarity index 100%
rename from apps/registry/content/pages/docs.mdx
rename to apps/registry/content/pages/docs/en.mdx
diff --git a/apps/registry/content/pages/docs/fr.mdx b/apps/registry/content/pages/docs/fr.mdx
new file mode 100644
index 00000000..0a5ecc7e
--- /dev/null
+++ b/apps/registry/content/pages/docs/fr.mdx
@@ -0,0 +1,33 @@
+---
+title: Documentation
+description: Apprenez a utiliser les composants VLLNT UI dans vos projets.
+type: docs
+og:
+  title: Documentation
+  description: Apprenez a utiliser les composants VLLNT UI
+  type: docs
+---
+
+# Demarrer
+
+Bienvenue dans VLLNT UI. C'est un registre de composants construit avec le format shadcn/ui.
+
+## Installation
+
+Installez les composants avec la CLI shadcn :
+
+```bash
+pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/[component-name].json
+```
+
+## Utilisation
+
+Importez les composants depuis `@vllnt/ui` :
+
+```tsx
+import { Button } from '@vllnt/ui'
+
+export function MyComponent() {
+  return <Button>Click me</Button>
+}
+```
diff --git a/apps/registry/content/pages/home.mdx b/apps/registry/content/pages/home/en.mdx
similarity index 100%
rename from apps/registry/content/pages/home.mdx
rename to apps/registry/content/pages/home/en.mdx
diff --git a/apps/registry/content/pages/home/fr.mdx b/apps/registry/content/pages/home/fr.mdx
new file mode 100644
index 00000000..59c424f8
--- /dev/null
+++ b/apps/registry/content/pages/home/fr.mdx
@@ -0,0 +1,62 @@
+---
+title: VLLNT UI - Registre de composants
+description: 225 composants React agent-first. Installez avec la CLI shadcn - aucune bibliotheque a importer, aucun verrou de version.
+type: home
+og:
+  title: ui.vllnt.ai
+  description: Registre de composants React agent-first - installez avec la CLI shadcn
+  type: home
+---
+
+# Installez n'importe quel composant en une ligne
+
+Choisissez un composant, copiez sa commande d'installation, puis lancez-la. La CLI recupere la source depuis `ui.vllnt.ai/r/<name>.json` et l'ecrit directement dans votre depot. Le code vous appartient.
+
+## Installation
+
+```bash
+# pnpm
+pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/button.json
+
+# npm
+npx shadcn@latest add https://ui.vllnt.ai/r/button.json
+
+# yarn
+yarn dlx shadcn@latest add https://ui.vllnt.ai/r/button.json
+
+# bun
+bunx --bun shadcn@latest add https://ui.vllnt.ai/r/button.json
+```
+
+Remplacez `button.json` par le nom d'un composant du [registre](/components).
+
+## Pas de CLI supplementaire
+
+Il n'y a pas de `@vllnt/cli`. La CLI shadcn comprend deja le format de registre. L'utiliser avec `ui.vllnt.ai/r/<name>.json` est le chemin d'installation supporte.
+
+## Utilisation apres installation
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+export function MyComponent() {
+  return <Button>Click me</Button>;
+}
+```
+
+La CLI installe les fichiers source dans votre projet sous `components/ui/`, configurable via `components.json`. Les mises a jour restent explicites : relancez la commande quand vous voulez une version plus recente.
+
+## Pourquoi c'est utile aux agents
+
+Chaque composant est aussi expose comme descripteur JSON lisible par machine :
+
+- `https://ui.vllnt.ai/r/registry.json` - index des 225 composants
+- `https://ui.vllnt.ai/r/<name>.json` - un composant
+- `https://ui.vllnt.ai/llms.txt` - index concis selon la specification [llmstxt.org](https://llmstxt.org)
+- `https://ui.vllnt.ai/llms-full.txt` - contexte agent complet en une requete
+
+## Etapes suivantes
+
+- Parcourir [les 225 composants](/components)
+- Lire la [philosophie](/philosophy) de la bibliotheque
+- Lire la [documentation](/docs)
diff --git a/apps/registry/content/pages/philosophy.mdx b/apps/registry/content/pages/philosophy/en.mdx
similarity index 100%
rename from apps/registry/content/pages/philosophy.mdx
rename to apps/registry/content/pages/philosophy/en.mdx
diff --git a/apps/registry/content/pages/philosophy/fr.mdx b/apps/registry/content/pages/philosophy/fr.mdx
new file mode 100644
index 00000000..c543a866
--- /dev/null
+++ b/apps/registry/content/pages/philosophy/fr.mdx
@@ -0,0 +1,62 @@
+---
+title: Philosophie
+description: Les principes qui guident la conception et le developpement de VLLNT UI.
+type: page
+og:
+  title: Philosophie
+  description: Les principes derriere VLLNT UI
+  type: page
+---
+
+# Philosophie
+
+VLLNT UI repose sur des principes simples qui guident chaque decision de conception et chaque choix d'implementation.
+
+## Design minimaliste
+
+Moins, mais mieux. Chaque composant vise la simplicite. Un bon design doit devenir invisible : il fonctionne sans attirer inutilement l'attention. Nos composants sont :
+
+- Clairs et sans surcharge
+- Centrees sur les fonctionnalites essentielles
+- Sans decoration gratuite
+- Intentionnels dans chaque detail
+
+## Dark mode d'abord
+
+Le mode sombre n'est pas un ajout tardif : c'est la direction principale. Chaque composant est concu pour les fonds sombres, avec une lisibilite et un confort visuel solides. Le mode clair existe, mais VLLNT UI brille surtout en sombre.
+
+- Concu pour les environnements peu lumineux
+- Fatigue visuelle reduite
+- Esthetique moderne
+- Apparence professionnelle
+
+## Pas de style emoji
+
+Nous gardons une approche professionnelle, basee sur le texte. Les emojis et les icones decoratives restent rares, pour que les composants restent durables et universels.
+
+- Communication textuelle
+- Ton professionnel
+- Compatibilite universelle
+- Typographie propre
+
+## Composants rapides
+
+La performance n'est pas negociable. Chaque composant est optimise pour la vitesse et l'efficacite :
+
+- Implementations legeres
+- Dependances minimales
+- Rendu optimise
+- Temps de chargement courts
+
+## Excellence technique
+
+Au-dela de l'apparence, VLLNT UI privilegie :
+
+- **Type Safety** : TypeScript pour la fiabilite
+- **Accessibilite** : composants compatibles WCAG
+- **Personnalisation** : extension et modification faciles
+- **Standards modernes** : construit sur les technologies web actuelles
+
+## Demarrer
+
+Tous les composants suivent ces principes. Utiliser VLLNT UI, ce n'est pas seulement ajouter des composants : c'est adopter une philosophie de design propre, rapide et intentionnel.
diff --git a/apps/registry/i18n/locales.ts b/apps/registry/i18n/locales.ts
new file mode 100644
index 00000000..f38cb481
--- /dev/null
+++ b/apps/registry/i18n/locales.ts
@@ -0,0 +1,4 @@
+export const locales = ["en", "fr"] as const;
+export const defaultLocale = "en";
+
+export type Locale = (typeof locales)[number];
diff --git a/apps/registry/i18n/request.ts b/apps/registry/i18n/request.ts
new file mode 100644
index 00000000..2532bb17
--- /dev/null
+++ b/apps/registry/i18n/request.ts
@@ -0,0 +1,19 @@
+import { hasLocale } from "next-intl";
+import { getRequestConfig } from "next-intl/server";
+
+import { routing } from "./routing";
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  const requested = await requestLocale;
+  const locale = hasLocale(routing.locales, requested)
+    ? requested
+    : routing.defaultLocale;
+  const messagesModule = (await import(`../messages/${locale}.json`)) as {
+    default: Record<string, unknown>;
+  };
+
+  return {
+    locale,
+    messages: messagesModule.default,
+  };
+});
diff --git a/apps/registry/i18n/routing.ts b/apps/registry/i18n/routing.ts
new file mode 100644
index 00000000..adba5933
--- /dev/null
+++ b/apps/registry/i18n/routing.ts
@@ -0,0 +1,20 @@
+import { createNavigation } from "next-intl/navigation";
+import { defineRouting } from "next-intl/routing";
+
+import { defaultLocale, type Locale, locales } from "./locales";
+
+export const routing = defineRouting({
+  defaultLocale,
+  localePrefix: "as-needed",
+  locales,
+});
+
+/* eslint-disable-next-line @typescript-eslint/naming-convention */
+export const { getPathname, Link, redirect, usePathname, useRouter } =
+  createNavigation(routing);
+
+export function isLocale(value: string): value is Locale {
+  return (routing.locales as readonly string[]).includes(value);
+}
+
+export { type Locale } from "./locales";
diff --git a/apps/registry/lib/component-metadata.json b/apps/registry/lib/component-metadata.json
index bc9df8fa..d0d8f076 100644
--- a/apps/registry/lib/component-metadata.json
+++ b/apps/registry/lib/component-metadata.json
@@ -3,6 +3,9 @@
     "category": "content",
     "defaultStoryId": "content-accordion--default",
     "description": "Collapsible content sections supporting single or multiple open items.",
+    "descriptions": {
+      "en": "Collapsible content sections supporting single or multiple open items."
+    },
     "name": "accordion",
     "stories": [
       {
@@ -16,6 +19,9 @@
     "category": "data",
     "defaultStoryId": "deploymentactivity--default",
     "description": "Contribution-style grid for visualizing operational activity over time.",
+    "descriptions": {
+      "en": "Contribution-style grid for visualizing operational activity over time."
+    },
     "name": "activity-heatmap",
     "stories": [
       {
@@ -33,6 +39,9 @@
     "category": "data",
     "defaultStoryId": "activitylog--default",
     "description": "Paginated activity feed for audit history and analytics changes.",
+    "descriptions": {
+      "en": "Paginated activity feed for audit history and analytics changes."
+    },
     "name": "activity-log",
     "stories": [
       {
@@ -50,6 +59,9 @@
     "category": "ai",
     "defaultStoryId": "ai-agentactivity--default",
     "description": "Visual display of an AI agent's execution chain — steps, tools, decisions, progress.",
+    "descriptions": {
+      "en": "Visual display of an AI agent's execution chain — steps, tools, decisions, progress."
+    },
     "name": "agent-activity",
     "stories": [
       {
@@ -75,6 +87,9 @@
     "category": "ai",
     "defaultStoryId": "generatedcomponent--default",
     "description": "Rendered output area for AI-generated content with toolbar, copy/edit/download/fullscreen actions, and version chips.",
+    "descriptions": {
+      "en": "Rendered output area for AI-generated content with toolbar, copy/edit/download/fullscreen actions, and version chips."
+    },
     "name": "ai-artifact",
     "stories": [
       {
@@ -100,6 +115,9 @@
     "category": "learning",
     "defaultStoryId": "ai-chatinput--default",
     "description": "Prompt composer for conversational interfaces with helper text, toolbar actions, and submit states.",
+    "descriptions": {
+      "en": "Prompt composer for conversational interfaces with helper text, toolbar actions, and submit states."
+    },
     "name": "ai-chat-input",
     "stories": [
       {
@@ -117,6 +135,9 @@
     "category": "learning",
     "defaultStoryId": "ai-messagebubble--default",
     "description": "Chat bubble for assistant, user, tool, and system messages using the current design system surfaces.",
+    "descriptions": {
+      "en": "Chat bubble for assistant, user, tool, and system messages using the current design system surfaces."
+    },
     "name": "ai-message-bubble",
     "stories": [
       {
@@ -138,6 +159,9 @@
     "category": "ai",
     "defaultStoryId": "ai-aisidebar--default",
     "description": "Slide-out AI assistant panel with provider, header / content / footer slots, and a standalone trigger.",
+    "descriptions": {
+      "en": "Slide-out AI assistant panel with provider, header / content / footer slots, and a standalone trigger."
+    },
     "name": "ai-sidebar",
     "stories": [
       {
@@ -159,6 +183,9 @@
     "category": "learning",
     "defaultStoryId": "designingreadableaiconversations--default",
     "description": "Compact source reference card for AI answers with a title, origin label, and optional excerpt.",
+    "descriptions": {
+      "en": "Compact source reference card for AI answers with a title, origin label, and optional excerpt."
+    },
     "name": "ai-source-citation",
     "stories": [
       {
@@ -172,6 +199,9 @@
     "category": "learning",
     "defaultStoryId": "ai-streamingtext--default",
     "description": "Readable text block for partial assistant output with an optional live cursor while tokens stream in.",
+    "descriptions": {
+      "en": "Readable text block for partial assistant output with an optional live cursor while tokens stream in."
+    },
     "name": "ai-streaming-text",
     "stories": [
       {
@@ -189,6 +219,9 @@
     "category": "learning",
     "defaultStoryId": "ai-toolcalldisplay--default",
     "description": "Structured card for tool invocation traces, statuses, serialized input, and returned output.",
+    "descriptions": {
+      "en": "Structured card for tool invocation traces, statuses, serialized input, and returned output."
+    },
     "name": "ai-tool-call-display",
     "stories": [
       {
@@ -206,6 +239,9 @@
     "category": "data",
     "defaultStoryId": "data-alert--default",
     "description": "Displays an alert message to the user.",
+    "descriptions": {
+      "en": "Displays an alert message to the user."
+    },
     "name": "alert",
     "stories": [
       {
@@ -223,6 +259,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-alertdialog--default",
     "description": "Modal dialog for confirming destructive or important actions.",
+    "descriptions": {
+      "en": "Modal dialog for confirming destructive or important actions."
+    },
     "name": "alert-dialog",
     "stories": [
       {
@@ -236,6 +275,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-alertpulse--default",
     "description": "Pulsing ring overlay for alerting canvas objects, with severity tones.",
+    "descriptions": {
+      "en": "Pulsing ring overlay for alerting canvas objects, with severity tones."
+    },
     "name": "alert-pulse",
     "stories": [
       {
@@ -261,6 +303,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-anchorport--default",
     "description": "Port marker for object inputs, outputs, and bidirectional links on the canvas.",
+    "descriptions": {
+      "en": "Port marker for object inputs, outputs, and bidirectional links on the canvas."
+    },
     "name": "anchor-port",
     "stories": [
       {
@@ -274,6 +319,9 @@
     "category": "utility",
     "defaultStoryId": "utility-animatedtext--terminal",
     "description": "Staggered text reveal for headings, pull quotes, and short supporting copy.",
+    "descriptions": {
+      "en": "Staggered text reveal for headings, pull quotes, and short supporting copy."
+    },
     "name": "animated-text",
     "stories": [
       {
@@ -331,6 +379,9 @@
     "category": "learning",
     "defaultStoryId": "learning-annotation--default",
     "description": "Inline highlight with an attached contextual note.",
+    "descriptions": {
+      "en": "Inline highlight with an attached contextual note."
+    },
     "name": "annotation",
     "stories": [
       {
@@ -356,6 +407,9 @@
     "category": "utility",
     "defaultStoryId": "utility-aspectratio--default",
     "description": "Constrains content to a specified aspect ratio.",
+    "descriptions": {
+      "en": "Constrains content to a specified aspect ratio."
+    },
     "name": "aspect-ratio",
     "stories": [
       {
@@ -369,6 +423,9 @@
     "category": "billing",
     "defaultStoryId": "billing-autoreload--default",
     "description": "Toggle + collapsible threshold/amount form for automatic credit reloading with locale-aware currency.",
+    "descriptions": {
+      "en": "Toggle + collapsible threshold/amount form for automatic credit reloading with locale-aware currency."
+    },
     "name": "auto-reload",
     "stories": [
       {
@@ -398,6 +455,9 @@
     "category": "core",
     "defaultStoryId": "core-avatar--default",
     "description": "Displays a user avatar image with fallback initials.",
+    "descriptions": {
+      "en": "Displays a user avatar image with fallback initials."
+    },
     "name": "avatar",
     "stories": [
       {
@@ -411,6 +471,9 @@
     "category": "data",
     "defaultStoryId": "data-avatargroup--default",
     "description": "Overlapping avatar stack for participants, assignees, and collaborative contexts.",
+    "descriptions": {
+      "en": "Overlapping avatar stack for participants, assignees, and collaborative contexts."
+    },
     "name": "avatar-group",
     "stories": [
       {
@@ -428,6 +491,9 @@
     "category": "core",
     "defaultStoryId": "core-badge--default",
     "description": "Small status label with variant styles.",
+    "descriptions": {
+      "en": "Small status label with variant styles."
+    },
     "name": "badge",
     "stories": [
       {
@@ -453,6 +519,9 @@
     "category": "core",
     "defaultStoryId": "core-banner--default",
     "description": "Full-width announcement bar with variants, dismissal, and an optional action slot.",
+    "descriptions": {
+      "en": "Full-width announcement bar with variants, dismissal, and an optional action slot."
+    },
     "name": "banner",
     "stories": [
       {
@@ -494,6 +563,9 @@
     "category": "content",
     "defaultStoryId": "exampleblogpost--default",
     "description": "Card layout for displaying blog post previews.",
+    "descriptions": {
+      "en": "Card layout for displaying blog post previews."
+    },
     "name": "blog-card",
     "stories": [
       {
@@ -507,6 +579,9 @@
     "category": "utility",
     "defaultStoryId": "utility-borderbeam--default",
     "description": "Animated accent beam that travels around the border of a highlighted surface.",
+    "descriptions": {
+      "en": "Animated accent beam that travels around the border of a highlighted surface."
+    },
     "name": "border-beam",
     "stories": [
       {
@@ -524,6 +599,9 @@
     "category": "data",
     "defaultStoryId": "canvas-bottomactivitystrip--default",
     "description": "Slim horizontally-scrolling row of recent canvas events for low-noise live activity.",
+    "descriptions": {
+      "en": "Slim horizontally-scrolling row of recent canvas events for low-noise live activity."
+    },
     "name": "bottom-activity-strip",
     "stories": [
       {
@@ -549,6 +627,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-breadcrumb--default",
     "description": "Navigation breadcrumb trail showing the current page hierarchy.",
+    "descriptions": {
+      "en": "Navigation breadcrumb trail showing the current page hierarchy."
+    },
     "name": "breadcrumb",
     "stories": [
       {
@@ -562,6 +643,9 @@
     "category": "core",
     "defaultStoryId": "core-button--default",
     "description": "Interactive button with multiple variants and sizes.",
+    "descriptions": {
+      "en": "Interactive button with multiple variants and sizes."
+    },
     "name": "button",
     "stories": [
       {
@@ -607,6 +691,9 @@
     "category": "form",
     "defaultStoryId": "form-calendar--default",
     "description": "Date picker calendar for selecting dates.",
+    "descriptions": {
+      "en": "Date picker calendar for selecting dates."
+    },
     "name": "calendar",
     "stories": [
       {
@@ -620,6 +707,9 @@
     "category": "content",
     "defaultStoryId": "content-callout--default",
     "description": "Highlighted content block with variant styles for info, warning, danger, and more.",
+    "descriptions": {
+      "en": "Highlighted content block with variant styles for info, warning, danger, and more."
+    },
     "name": "callout",
     "stories": [
       {
@@ -633,6 +723,9 @@
     "category": "data",
     "defaultStoryId": "data-candlestickchart--default",
     "description": "OHLC financial chart for session-by-session price action.",
+    "descriptions": {
+      "en": "OHLC financial chart for session-by-session price action."
+    },
     "name": "candlestick-chart",
     "stories": [
       {
@@ -650,6 +743,9 @@
     "category": "utility",
     "defaultStoryId": "layout-canvasshell--default",
     "description": "Layout shell for canvas workspaces with top bar, left rail, right dock, and bottom slot regions.",
+    "descriptions": {
+      "en": "Layout shell for canvas workspaces with top bar, left rail, right dock, and bottom slot regions."
+    },
     "name": "canvas-shell",
     "stories": [
       {
@@ -663,6 +759,9 @@
     "category": "utility",
     "defaultStoryId": "layout-canvasview--default",
     "description": "Interactive pan-and-zoom viewport for spatial surfaces with keyboard, wheel, and overlay support.",
+    "descriptions": {
+      "en": "Interactive pan-and-zoom viewport for spatial surfaces with keyboard, wheel, and overlay support."
+    },
     "name": "canvas-view",
     "stories": [
       {
@@ -676,6 +775,9 @@
     "category": "content",
     "defaultStoryId": "content-card--default",
     "description": "Container with header, content, and footer sections.",
+    "descriptions": {
+      "en": "Container with header, content, and footer sections."
+    },
     "name": "card",
     "stories": [
       {
@@ -689,6 +791,9 @@
     "category": "content",
     "defaultStoryId": "content-carousel--default",
     "description": "Scrollable content carousel with navigation controls.",
+    "descriptions": {
+      "en": "Scrollable content carousel with navigation controls."
+    },
     "name": "carousel",
     "stories": [
       {
@@ -702,6 +807,9 @@
     "category": "form",
     "defaultStoryId": "form-categoryfilter--default",
     "description": "Filterable category selection for content lists.",
+    "descriptions": {
+      "en": "Filterable category selection for content lists."
+    },
     "name": "category-filter",
     "stories": [
       {
@@ -715,6 +823,9 @@
     "category": "core",
     "defaultStoryId": "core-checkbox--default",
     "description": "Toggle control for boolean input.",
+    "descriptions": {
+      "en": "Toggle control for boolean input."
+    },
     "name": "checkbox",
     "stories": [
       {
@@ -728,6 +839,9 @@
     "category": "learning",
     "defaultStoryId": "learning-checklist--default",
     "description": "Interactive checklist with progress tracking and toggleable items.",
+    "descriptions": {
+      "en": "Interactive checklist with progress tracking and toggleable items."
+    },
     "name": "checklist",
     "stories": [
       {
@@ -741,6 +855,9 @@
     "category": "data-display",
     "defaultStoryId": "maps-choroplethmap--default",
     "description": "Standalone SVG choropleth — region polygons shaded by data value with tooltip, legend, and accessible data-table fallback.",
+    "descriptions": {
+      "en": "Standalone SVG choropleth — region polygons shaded by data value with tooltip, legend, and accessible data-table fallback."
+    },
     "name": "choropleth-map",
     "stories": [
       {
@@ -766,6 +883,9 @@
     "category": "data-display",
     "defaultStoryId": "thespacerace--default",
     "description": "Media-rich, scroll-driven chronological timeline with alternating cards, image/video/audio media, and a progress strip.",
+    "descriptions": {
+      "en": "Media-rich, scroll-driven chronological timeline with alternating cards, image/video/audio media, and a progress strip."
+    },
     "name": "chronological-timeline",
     "stories": [
       {
@@ -791,6 +911,9 @@
     "category": "educational",
     "defaultStoryId": "educational-civilizationcard--default",
     "description": "Civilization overview with hero band, BCE/CE era timeline, key stats, achievements, and notable leaders.",
+    "descriptions": {
+      "en": "Civilization overview with hero band, BCE/CE era timeline, key stats, achievements, and notable leaders."
+    },
     "name": "civilization-card",
     "stories": [
       {
@@ -820,6 +943,9 @@
     "category": "content",
     "defaultStoryId": "content-codeblock--default",
     "description": "Syntax-highlighted code display with copy support.",
+    "descriptions": {
+      "en": "Syntax-highlighted code display with copy support."
+    },
     "name": "code-block",
     "stories": [
       {
@@ -833,6 +959,9 @@
     "category": "content",
     "defaultStoryId": "content-codeplayground--default",
     "description": "Interactive code editor with live preview.",
+    "descriptions": {
+      "en": "Interactive code editor with live preview."
+    },
     "name": "code-playground",
     "stories": [
       {
@@ -846,6 +975,9 @@
     "category": "content",
     "defaultStoryId": "content-collapsible--default",
     "description": "Expandable and collapsible content section.",
+    "descriptions": {
+      "en": "Expandable and collapsible content section."
+    },
     "name": "collapsible",
     "stories": [
       {
@@ -859,6 +991,9 @@
     "category": "form",
     "defaultStoryId": "form-combobox--default",
     "description": "Searchable select input for choosing from a list of options.",
+    "descriptions": {
+      "en": "Searchable select input for choosing from a list of options."
+    },
     "name": "combobox",
     "stories": [
       {
@@ -876,6 +1011,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-command--default",
     "description": "Command palette with search, groups, and keyboard navigation.",
+    "descriptions": {
+      "en": "Command palette with search, groups, and keyboard navigation."
+    },
     "name": "command",
     "stories": [
       {
@@ -889,6 +1027,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-commentpin--default",
     "description": "Anchored discussion pin rendered at canvas coordinates with author + unread badge.",
+    "descriptions": {
+      "en": "Anchored discussion pin rendered at canvas coordinates with author + unread badge."
+    },
     "name": "comment-pin",
     "stories": [
       {
@@ -914,6 +1055,9 @@
     "category": "data",
     "defaultStoryId": "exampletitle--default",
     "description": "Side-by-side comparison layout for content or features.",
+    "descriptions": {
+      "en": "Side-by-side comparison layout for content or features."
+    },
     "name": "comparison",
     "stories": [
       {
@@ -927,6 +1071,9 @@
     "category": "learning",
     "defaultStoryId": "congratulations--default",
     "description": "Dialog displayed upon completing a task or workflow.",
+    "descriptions": {
+      "en": "Dialog displayed upon completing a task or workflow."
+    },
     "name": "completion-dialog",
     "stories": [
       {
@@ -940,6 +1087,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-connectoredge--default",
     "description": "Curved edge between canvas objects with optional inline label state.",
+    "descriptions": {
+      "en": "Curved edge between canvas objects with optional inline label state."
+    },
     "name": "connector-edge",
     "stories": [
       {
@@ -953,6 +1103,9 @@
     "category": "content",
     "defaultStoryId": "introduction--default",
     "description": "Introductory section for content pages with title and description.",
+    "descriptions": {
+      "en": "Introductory section for content pages with title and description."
+    },
     "name": "content-intro",
     "stories": [
       {
@@ -966,6 +1119,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-contextlens--default",
     "description": "Vignette overlay that dims the canvas outside a circular focus region.",
+    "descriptions": {
+      "en": "Vignette overlay that dims the canvas outside a circular focus region."
+    },
     "name": "context-lens",
     "stories": [
       {
@@ -991,6 +1147,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-contextmenu--default",
     "description": "Right-click context menu with items and submenus.",
+    "descriptions": {
+      "en": "Right-click context menu with items and submenus."
+    },
     "name": "context-menu",
     "stories": [
       {
@@ -1004,6 +1163,9 @@
     "category": "core",
     "defaultStoryId": "core-copybutton--default",
     "description": "Click-to-copy utility with confirmation feedback and a useCopyToClipboard hook.",
+    "descriptions": {
+      "en": "Click-to-copy utility with confirmation feedback and a useCopyToClipboard hook."
+    },
     "name": "copy-button",
     "stories": [
       {
@@ -1029,6 +1191,9 @@
     "category": "data",
     "defaultStoryId": "slatimer--default",
     "description": "Countdown and SLA timer for deadlines, escalations, and response windows.",
+    "descriptions": {
+      "en": "Countdown and SLA timer for deadlines, escalations, and response windows."
+    },
     "name": "countdown-timer",
     "stories": [
       {
@@ -1046,6 +1211,9 @@
     "category": "content",
     "defaultStoryId": "accountbilling-creditbadge--default",
     "description": "Balance status pill for credits, wallet states, and billing health.",
+    "descriptions": {
+      "en": "Balance status pill for credits, wallet states, and billing health."
+    },
     "name": "credit-badge",
     "stories": [
       {
@@ -1063,6 +1231,9 @@
     "category": "data",
     "defaultStoryId": "data-datalist--default",
     "description": "Semantic key-value metadata layout for displaying labels with values.",
+    "descriptions": {
+      "en": "Semantic key-value metadata layout for displaying labels with values."
+    },
     "name": "data-list",
     "stories": [
       {
@@ -1080,6 +1251,9 @@
     "category": "data",
     "defaultStoryId": "data-datatable--default",
     "description": "Enhanced data table with sorting, filtering, selection, and pagination controls.",
+    "descriptions": {
+      "en": "Enhanced data table with sorting, filtering, selection, and pagination controls."
+    },
     "name": "data-table",
     "stories": [
       {
@@ -1093,6 +1267,9 @@
     "category": "form",
     "defaultStoryId": "form-datepicker--default",
     "description": "Single-date picker built with the shared calendar and popover primitives.",
+    "descriptions": {
+      "en": "Single-date picker built with the shared calendar and popover primitives."
+    },
     "name": "date-picker",
     "stories": [
       {
@@ -1110,6 +1287,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-dialog--default",
     "description": "Modal dialog overlay for focused content and actions.",
+    "descriptions": {
+      "en": "Modal dialog overlay for focused content and actions."
+    },
     "name": "dialog",
     "stories": [
       {
@@ -1123,6 +1303,9 @@
     "category": "content",
     "defaultStoryId": "whythinclientsareback--default",
     "description": "Newer/older navigator: links to the previous and next item in an ordered series.",
+    "descriptions": {
+      "en": "Newer/older navigator: links to the previous and next item in an ordered series."
+    },
     "name": "document-sibling-nav",
     "stories": [
       {
@@ -1156,6 +1339,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-drawer--default",
     "description": "Slide-out panel anchored to the screen edge.",
+    "descriptions": {
+      "en": "Slide-out panel anchored to the screen edge."
+    },
     "name": "drawer",
     "stories": [
       {
@@ -1169,6 +1355,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-dropdownmenu--default",
     "description": "Accessible dropdown menu with items, checkboxes, radio groups, and submenus.",
+    "descriptions": {
+      "en": "Accessible dropdown menu with items, checkboxes, radio groups, and submenus."
+    },
     "name": "dropdown-menu",
     "stories": [
       {
@@ -1182,6 +1371,9 @@
     "category": "overlay",
     "defaultStoryId": "canvas-edgelabel--default",
     "description": "Inline edge label for relationship semantics such as streams, handoffs, or policies.",
+    "descriptions": {
+      "en": "Inline edge label for relationship semantics such as streams, handoffs, or policies."
+    },
     "name": "edge-label",
     "stories": [
       {
@@ -1195,6 +1387,9 @@
     "category": "core",
     "defaultStoryId": "noresultsfound--default",
     "description": "Centered placeholder for empty lists, tables, and search results with sm/md/lg sizes.",
+    "descriptions": {
+      "en": "Centered placeholder for empty lists, tables, and search results with sm/md/lg sizes."
+    },
     "name": "empty-state",
     "stories": [
       {
@@ -1220,6 +1415,9 @@
     "category": "educational",
     "defaultStoryId": "educational-eracomparison--default",
     "description": "Side-by-side comparison of historical eras with domain rows, color-themed columns, highlights, and figure chips.",
+    "descriptions": {
+      "en": "Side-by-side comparison of historical eras with domain rows, color-themed columns, highlights, and figure chips."
+    },
     "name": "era-comparison",
     "stories": [
       {
@@ -1241,6 +1439,9 @@
     "category": "learning",
     "defaultStoryId": "reverseastring--default",
     "description": "Interactive exercise block for learning content.",
+    "descriptions": {
+      "en": "Interactive exercise block for learning content."
+    },
     "name": "exercise",
     "stories": [
       {
@@ -1254,6 +1455,9 @@
     "category": "content",
     "defaultStoryId": "content-faq--default",
     "description": "Frequently asked questions section with expandable answers.",
+    "descriptions": {
+      "en": "Frequently asked questions section with expandable answers."
+    },
     "name": "faq",
     "stories": [
       {
@@ -1267,6 +1471,9 @@
     "category": "form",
     "defaultStoryId": "form-fileupload--default",
     "description": "Dropzone-style file picker with previews for selected files.",
+    "descriptions": {
+      "en": "Dropzone-style file picker with previews for selected files."
+    },
     "name": "file-upload",
     "stories": [
       {
@@ -1280,6 +1487,9 @@
     "category": "form",
     "defaultStoryId": "form-filterbar--default",
     "description": "Horizontal bar with filter controls for content lists.",
+    "descriptions": {
+      "en": "Horizontal bar with filter controls for content lists."
+    },
     "name": "filter-bar",
     "stories": [
       {
@@ -1293,6 +1503,9 @@
     "category": "learning",
     "defaultStoryId": "partsofspeech--default",
     "description": "Study card for active recall with prompt and answer states.",
+    "descriptions": {
+      "en": "Study card for active recall with prompt and answer states."
+    },
     "name": "flashcard",
     "stories": [
       {
@@ -1306,6 +1519,9 @@
     "category": "utility",
     "defaultStoryId": "utility-floatingactionbutton--default",
     "description": "Fixed-position action button for primary actions.",
+    "descriptions": {
+      "en": "Fixed-position action button for primary actions."
+    },
     "name": "floating-action-button",
     "stories": [
       {
@@ -1319,6 +1535,9 @@
     "category": "data-display",
     "defaultStoryId": "canvas-floatingtoolbar--default",
     "description": "Compact action bar that floats above a selection — primary / ghost / destructive variants.",
+    "descriptions": {
+      "en": "Compact action bar that floats above a selection — primary / ghost / destructive variants."
+    },
     "name": "floating-toolbar",
     "stories": [
       {
@@ -1340,6 +1559,9 @@
     "category": "data",
     "defaultStoryId": "data-flowdiagram--default",
     "description": "Interactive flow diagram with nodes, edges, and controls.",
+    "descriptions": {
+      "en": "Interactive flow diagram with nodes, edges, and controls."
+    },
     "name": "flow-diagram",
     "stories": [
       {
@@ -1353,6 +1575,9 @@
     "category": "data-display",
     "defaultStoryId": "canvas-followmode--default",
     "description": "Follow-mode chrome — outlines a region with a participant's color and surfaces a stop-following chip.",
+    "descriptions": {
+      "en": "Follow-mode chrome — outlines a region with a participant's color and surfaces a stop-following chip."
+    },
     "name": "follow-mode",
     "stories": [
       {
@@ -1374,6 +1599,9 @@
     "category": "form",
     "defaultStoryId": "core-form--default",
     "description": "Validation wrapper for composing labels, descriptions, controls, and messages.",
+    "descriptions": {
+      "en": "Validation wrapper for composing labels, descriptions, controls, and messages."
+    },
     "name": "form",
     "stories": [
       {
@@ -1391,6 +1619,9 @@
     "category": "data",
     "defaultStoryId": "designsystem--default",
     "description": "Project timeline with task bars, progress overlays, milestones, and a today indicator across day/week/month/quarter scales.",
+    "descriptions": {
+      "en": "Project timeline with task bars, progress overlays, milestones, and a today indicator across day/week/month/quarter scales."
+    },
     "name": "gantt-chart",
     "stories": [
       {
@@ -1416,6 +1647,9 @@
     "category": "data-display",
     "defaultStoryId": "educational-geographyquizmap--default",
     "description": "Interactive identify-mode map quiz — click the correct region per prompt with visual feedback, score, and results panel.",
+    "descriptions": {
+      "en": "Interactive identify-mode map quiz — click the correct region per prompt with visual feedback, score, and results panel."
+    },
     "name": "geography-quiz-map",
     "stories": [
       {
@@ -1437,6 +1671,9 @@
     "category": "data-display",
     "defaultStoryId": "maps-globe3d--default",
     "description": "Standalone SVG pseudo-3D globe — orthographic projection with auto-rotation, drag interaction, lat/lng markers, and great-circle arcs.",
+    "descriptions": {
+      "en": "Standalone SVG pseudo-3D globe — orthographic projection with auto-rotation, drag interaction, lat/lng markers, and great-circle arcs."
+    },
     "name": "globe-3d",
     "stories": [
       {
@@ -1458,6 +1695,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-grouphull--default",
     "description": "Durable boundary wrapper for related runtime objects sharing context or ownership.",
+    "descriptions": {
+      "en": "Durable boundary wrapper for related runtime objects sharing context or ownership."
+    },
     "name": "group-hull",
     "stories": [
       {
@@ -1471,6 +1711,9 @@
     "category": "data-display",
     "defaultStoryId": "canvas-handoffbeacon--default",
     "description": "Attention-routing beacon with pulsing ring and optional source / message card for live canvases.",
+    "descriptions": {
+      "en": "Attention-routing beacon with pulsing ring and optional source / message card for live canvases."
+    },
     "name": "handoff-beacon",
     "stories": [
       {
@@ -1496,6 +1739,9 @@
     "category": "data-display",
     "defaultStoryId": "maps-heatmapoverlay--default",
     "description": "Standalone SVG geographic heat map — radial-gradient blobs with configurable radius, blur, gradient, and opacity.",
+    "descriptions": {
+      "en": "Standalone SVG geographic heat map — radial-gradient blobs with configurable radius, blur, gradient, and opacity."
+    },
     "name": "heat-map-overlay",
     "stories": [
       {
@@ -1525,6 +1771,9 @@
     "category": "data",
     "defaultStoryId": "canvas-heatoverlay--default",
     "description": "Heatmap-style overlay drawing soft radial blobs for canvas activity samples.",
+    "descriptions": {
+      "en": "Heatmap-style overlay drawing soft radial blobs for canvas activity samples."
+    },
     "name": "heat-overlay",
     "stories": [
       {
@@ -1550,6 +1799,9 @@
     "category": "data-display",
     "defaultStoryId": "firstolympics--default",
     "description": "Specialized timeline for historical events spanning centuries or millennia, with era bands, period bars, and BCE/CE point markers.",
+    "descriptions": {
+      "en": "Specialized timeline for historical events spanning centuries or millennia, with era bands, period bars, and BCE/CE point markers."
+    },
     "name": "historic-timeline",
     "stories": [
       {
@@ -1575,6 +1827,9 @@
     "category": "educational",
     "defaultStoryId": "polymath--default",
     "description": "Profile card with portrait, lifespan timeline, fields, works, quote, connections, and an expandable biography section.",
+    "descriptions": {
+      "en": "Profile card with portrait, lifespan timeline, fields, works, quote, connections, and an expandable biography section."
+    },
     "name": "historical-figure-card",
     "stories": [
       {
@@ -1604,6 +1859,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-horizontalscrollrow--default",
     "description": "Horizontal scroll container with snap scrolling, chevron navigation, and hidden scrollbar.",
+    "descriptions": {
+      "en": "Horizontal scroll container with snap scrolling, chevron navigation, and hidden scrollbar."
+    },
     "name": "horizontal-scroll-row",
     "stories": [
       {
@@ -1617,6 +1875,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-hovercard--default",
     "description": "Card that appears on hover for previewing content.",
+    "descriptions": {
+      "en": "Card that appears on hover for previewing content."
+    },
     "name": "hover-card",
     "stories": [
       {
@@ -1630,6 +1891,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-infiniteplane--dot",
     "description": "Tiled pannable backdrop for the canvas with dot or grid pattern that drifts with the viewport.",
+    "descriptions": {
+      "en": "Tiled pannable backdrop for the canvas with dot or grid pattern that drifts with the viewport."
+    },
     "name": "infinite-plane",
     "stories": [
       {
@@ -1655,6 +1919,9 @@
     "category": "form",
     "defaultStoryId": "form-inlineinput--default",
     "description": "Inline text input with keyboard commit and cancel support.",
+    "descriptions": {
+      "en": "Inline text input with keyboard commit and cancel support."
+    },
     "name": "inline-input",
     "stories": [
       {
@@ -1668,6 +1935,9 @@
     "category": "core",
     "defaultStoryId": "core-input--default",
     "description": "Text input field for forms.",
+    "descriptions": {
+      "en": "Text input field for forms."
+    },
     "name": "input",
     "stories": [
       {
@@ -1681,6 +1951,9 @@
     "category": "form",
     "defaultStoryId": "form-inputotp--default",
     "description": "One-time password input with segmented fields.",
+    "descriptions": {
+      "en": "One-time password input with segmented fields."
+    },
     "name": "input-otp",
     "stories": [
       {
@@ -1694,6 +1967,9 @@
     "category": "data-display",
     "defaultStoryId": "v10--default",
     "description": "Zoomable, pannable, multi-track timeline with category filter, today marker, and click-to-select events.",
+    "descriptions": {
+      "en": "Zoomable, pannable, multi-track timeline with category filter, today marker, and click-to-select events."
+    },
     "name": "interactive-timeline",
     "stories": [
       {
@@ -1719,6 +1995,9 @@
     "category": "navigation",
     "defaultStoryId": "canvas-jarvisdock--default",
     "description": "Floating bottom dock with quick-action buttons + a command-palette trigger.",
+    "descriptions": {
+      "en": "Floating bottom dock with quick-action buttons + a command-palette trigger."
+    },
     "name": "jarvis-dock",
     "stories": [
       {
@@ -1744,6 +2023,9 @@
     "category": "core",
     "defaultStoryId": "core-kbd--default",
     "description": "Keyboard key indicator with platform-aware modifier expansion via the shortcut prop.",
+    "descriptions": {
+      "en": "Keyboard key indicator with platform-aware modifier expansion via the shortcut prop."
+    },
     "name": "kbd",
     "stories": [
       {
@@ -1777,6 +2059,9 @@
     "category": "learning",
     "defaultStoryId": "learning-keyconcept--default",
     "description": "Highlighted definition block for key terms and a glossary list.",
+    "descriptions": {
+      "en": "Highlighted definition block for key terms and a glossary list."
+    },
     "name": "key-concept",
     "stories": [
       {
@@ -1790,6 +2075,9 @@
     "category": "learning",
     "defaultStoryId": "learning-keyboardshortcutshelp--default",
     "description": "Displays available keyboard shortcuts to the user.",
+    "descriptions": {
+      "en": "Displays available keyboard shortcuts to the user."
+    },
     "name": "keyboard-shortcuts-help",
     "stories": [
       {
@@ -1803,6 +2091,9 @@
     "category": "educational",
     "defaultStoryId": "checkyourunderstanding--default",
     "description": "Inline knowledge check with multiple-choice / true-false / fill-blank questions, per-answer feedback, and a final score summary.",
+    "descriptions": {
+      "en": "Inline knowledge check with multiple-choice / true-false / fill-blank questions, per-answer feedback, and a final score summary."
+    },
     "name": "knowledge-check",
     "stories": [
       {
@@ -1824,6 +2115,9 @@
     "category": "utility",
     "defaultStoryId": "utility-langprovider--default",
     "description": "Context provider for language and internationalization.",
+    "descriptions": {
+      "en": "Context provider for language and internationalization."
+    },
     "name": "lang-provider",
     "stories": [
       {
@@ -1837,6 +2131,9 @@
     "category": "learning",
     "defaultStoryId": "learning-learningobjectives--default",
     "description": "Lists learning goals for educational content.",
+    "descriptions": {
+      "en": "Lists learning goals for educational content."
+    },
     "name": "learning-objectives",
     "stories": [
       {
@@ -1850,6 +2147,9 @@
     "category": "navigation",
     "defaultStoryId": "layout-leftrail--default",
     "description": "Compact vertical rail for canvas modes, tool actions, and secondary navigation controls.",
+    "descriptions": {
+      "en": "Compact vertical rail for canvas modes, tool actions, and secondary navigation controls."
+    },
     "name": "left-rail",
     "stories": [
       {
@@ -1871,6 +2171,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-livecursor--default",
     "description": "Remote user's cursor rendered at canvas coordinates with name + status chip.",
+    "descriptions": {
+      "en": "Remote user's cursor rendered at canvas coordinates with name + status chip."
+    },
     "name": "live-cursor",
     "stories": [
       {
@@ -1896,6 +2199,9 @@
     "category": "data",
     "defaultStoryId": "latencybreachongateway--default",
     "description": "Rolling activity stream for surfacing incidents, deploys, and operational signals in real time.",
+    "descriptions": {
+      "en": "Rolling activity stream for surfacing incidents, deploys, and operational signals in real time."
+    },
     "name": "live-feed",
     "stories": [
       {
@@ -1913,6 +2219,9 @@
     "category": "data-display",
     "defaultStoryId": "maps-map2d--default",
     "description": "Lightweight 2D map primitive — SVG canvas with equirectangular projection, markers, popups, GeoJSON polygon layers, zoom controls, and an optional backdrop image.",
+    "descriptions": {
+      "en": "Lightweight 2D map primitive — SVG canvas with equirectangular projection, markers, popups, GeoJSON polygon layers, zoom controls, and an optional backdrop image."
+    },
     "name": "map-2d",
     "stories": [
       {
@@ -1938,6 +2247,9 @@
     "category": "data-display",
     "defaultStoryId": "educational-maptimeline--default",
     "description": "Standalone SVG map + time slider — era polygons and year-pinned events appear as the user scrubs the timeline.",
+    "descriptions": {
+      "en": "Standalone SVG map + time slider — era polygons and year-pinned events appear as the user scrubs the timeline."
+    },
     "name": "map-timeline",
     "stories": [
       {
@@ -1959,6 +2271,9 @@
     "category": "data",
     "defaultStoryId": "data-markettreemap--default",
     "description": "Sector-style market heatmap using weighted tiles and signed performance colors.",
+    "descriptions": {
+      "en": "Sector-style market heatmap using weighted tiles and signed performance colors."
+    },
     "name": "market-treemap",
     "stories": [
       {
@@ -1972,6 +2287,9 @@
     "category": "utility",
     "defaultStoryId": "utility-marquee--default",
     "description": "Continuously scrolling content lane for badges, logos, and status chips.",
+    "descriptions": {
+      "en": "Continuously scrolling content lane for badges, logos, and status chips."
+    },
     "name": "marquee",
     "stories": [
       {
@@ -2001,6 +2319,9 @@
     "category": "content",
     "defaultStoryId": "content-mdxcontent--default",
     "description": "Renders MDX content with component mapping.",
+    "descriptions": {
+      "en": "Renders MDX content with component mapping."
+    },
     "name": "mdx-content",
     "stories": [
       {
@@ -2014,6 +2335,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-menubar--default",
     "description": "Horizontal menu bar with dropdown menus.",
+    "descriptions": {
+      "en": "Horizontal menu bar with dropdown menus."
+    },
     "name": "menubar",
     "stories": [
       {
@@ -2027,6 +2351,9 @@
     "category": "data",
     "defaultStoryId": "research2025--default",
     "description": "Compact stack of related metrics pinned to a canvas object's corner.",
+    "descriptions": {
+      "en": "Compact stack of related metrics pinned to a canvas object's corner."
+    },
     "name": "metric-cluster",
     "stories": [
       {
@@ -2052,6 +2379,9 @@
     "category": "data",
     "defaultStoryId": "data-metricgauge--default",
     "description": "Real-time arc and dial display for monitored percentages and utilization.",
+    "descriptions": {
+      "en": "Real-time arc and dial display for monitored percentages and utilization."
+    },
     "name": "metric-gauge",
     "stories": [
       {
@@ -2069,6 +2399,9 @@
     "category": "data",
     "defaultStoryId": "panels-minimappanel--default",
     "description": "Viewport overview panel showing canvas bounds, markers, and the current zoom window.",
+    "descriptions": {
+      "en": "Viewport overview panel showing canvas bounds, markers, and the current zoom window."
+    },
     "name": "mini-map-panel",
     "stories": [
       {
@@ -2082,6 +2415,9 @@
     "category": "ai",
     "defaultStoryId": "ai-modelcomparison--default",
     "description": "Side-by-side comparison of AI model responses with optional blind mode, metadata stats, and a vote bar.",
+    "descriptions": {
+      "en": "Side-by-side comparison of AI model responses with optional blind mode, metadata stats, and a vote bar."
+    },
     "name": "model-comparison",
     "stories": [
       {
@@ -2107,6 +2443,9 @@
     "category": "form",
     "defaultStoryId": "form-modelselector--default",
     "description": "Dropdown selector for choosing AI models.",
+    "descriptions": {
+      "en": "Dropdown selector for choosing AI models."
+    },
     "name": "model-selector",
     "stories": [
       {
@@ -2120,6 +2459,9 @@
     "category": "form",
     "defaultStoryId": "form-multiselect--default",
     "description": "Popover-based multi-selection input with selected-value badges and optional search.",
+    "descriptions": {
+      "en": "Popover-based multi-selection input with selected-value badges and optional search."
+    },
     "name": "multi-select",
     "stories": [
       {
@@ -2141,6 +2483,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-multiselectlasso--default",
     "description": "Selection rectangle overlay for canvas multi-select gestures.",
+    "descriptions": {
+      "en": "Selection rectangle overlay for canvas multi-select gestures."
+    },
     "name": "multi-select-lasso",
     "stories": [
       {
@@ -2166,6 +2511,9 @@
     "category": "navigation",
     "defaultStoryId": "home--default",
     "description": "SaaS-style navigation bar with branding and links.",
+    "descriptions": {
+      "en": "SaaS-style navigation bar with branding and links."
+    },
     "name": "navbar-saas",
     "stories": [
       {
@@ -2179,6 +2527,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-navigationmenu--default",
     "description": "Accessible navigation menu with links and sub-navigation.",
+    "descriptions": {
+      "en": "Accessible navigation menu with links and sub-navigation."
+    },
     "name": "navigation-menu",
     "stories": [
       {
@@ -2192,6 +2543,9 @@
     "category": "form",
     "defaultStoryId": "forms-newslettersignup--default",
     "description": "Email-capture form with idle/sending/sent/error state machine, custom validators, and overridable labels.",
+    "descriptions": {
+      "en": "Email-capture form with idle/sending/sent/error state machine, custom validators, and overridable labels."
+    },
     "name": "newsletter-signup",
     "stories": [
       {
@@ -2221,6 +2575,9 @@
     "category": "form",
     "defaultStoryId": "form-numberinput--default",
     "description": "Numeric input with increment and decrement controls.",
+    "descriptions": {
+      "en": "Numeric input with increment and decrement controls."
+    },
     "name": "number-input",
     "stories": [
       {
@@ -2234,6 +2591,9 @@
     "category": "utility",
     "defaultStoryId": "utility-numberticker--default",
     "description": "Animated number transitions for stats, KPIs, and compact numeric callouts.",
+    "descriptions": {
+      "en": "Animated number transitions for stats, KPIs, and compact numeric callouts."
+    },
     "name": "number-ticker",
     "stories": [
       {
@@ -2251,6 +2611,9 @@
     "category": "content",
     "defaultStoryId": "canvas-objectcard--default",
     "description": "Durable object view for agents, runs, artifacts, and tasks inside the canvas.",
+    "descriptions": {
+      "en": "Durable object view for agents, runs, artifacts, and tasks inside the canvas."
+    },
     "name": "object-card",
     "stories": [
       {
@@ -2264,6 +2627,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-objecthandle--default",
     "description": "Drag/reposition affordance for spatial objects that need a calm grab target.",
+    "descriptions": {
+      "en": "Drag/reposition affordance for spatial objects that need a calm grab target."
+    },
     "name": "object-handle",
     "stories": [
       {
@@ -2277,6 +2643,9 @@
     "category": "content",
     "defaultStoryId": "claude37128kctx--default",
     "description": "Right-dock detail header — kind chip, status dot, title/subtitle, with property-section slots.",
+    "descriptions": {
+      "en": "Right-dock detail header — kind chip, status dot, title/subtitle, with property-section slots."
+    },
     "name": "object-inspector",
     "stories": [
       {
@@ -2302,6 +2671,9 @@
     "category": "data",
     "defaultStoryId": "data-orderbook--default",
     "description": "Level II bid/ask depth ladder with cumulative size bars and spread readout.",
+    "descriptions": {
+      "en": "Level II bid/ask depth ladder with cumulative size bars and spread readout."
+    },
     "name": "order-book",
     "stories": [
       {
@@ -2319,6 +2691,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-pagination--default",
     "description": "Page navigation controls with previous, next, and page links.",
+    "descriptions": {
+      "en": "Page navigation controls with previous, next, and page links."
+    },
     "name": "pagination",
     "stories": [
       {
@@ -2332,6 +2707,9 @@
     "category": "educational",
     "defaultStoryId": "augustusbecomesemperor--default",
     "description": "Multi-track timeline with shared time axis, BCE/CE event markers, and optional era bands for comparative history.",
+    "descriptions": {
+      "en": "Multi-track timeline with shared time axis, BCE/CE event markers, and optional era bands for comparative history."
+    },
     "name": "parallel-timeline",
     "stories": [
       {
@@ -2357,6 +2735,9 @@
     "category": "form",
     "defaultStoryId": "form-passwordinput--default",
     "description": "Password field with a built-in visibility toggle.",
+    "descriptions": {
+      "en": "Password field with a built-in visibility toggle."
+    },
     "name": "password-input",
     "stories": [
       {
@@ -2370,6 +2751,9 @@
     "category": "content",
     "defaultStoryId": "accountbilling-planbadge--default",
     "description": "Subscription tier indicator for pricing, billing, and account summaries.",
+    "descriptions": {
+      "en": "Subscription tier indicator for pricing, billing, and account summaries."
+    },
     "name": "plan-badge",
     "stories": [
       {
@@ -2391,6 +2775,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-playbackghost--default",
     "description": "Translucent overlay marking where a canvas object was at a previous timestamp during playback.",
+    "descriptions": {
+      "en": "Translucent overlay marking where a canvas object was at a previous timestamp during playback."
+    },
     "name": "playback-ghost",
     "stories": [
       {
@@ -2416,6 +2803,9 @@
     "category": "content",
     "defaultStoryId": "canvas-policydeliverypanel--default",
     "description": "Right-dock panel listing policies / guardrails active for the route or run.",
+    "descriptions": {
+      "en": "Right-dock panel listing policies / guardrails active for the route or run."
+    },
     "name": "policy-delivery-panel",
     "stories": [
       {
@@ -2441,6 +2831,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-popover--default",
     "description": "Floating content panel anchored to a trigger element.",
+    "descriptions": {
+      "en": "Floating content panel anchored to a trigger element."
+    },
     "name": "popover",
     "stories": [
       {
@@ -2454,6 +2847,9 @@
     "category": "data",
     "defaultStoryId": "canvas-presencestack--default",
     "description": "Overlapping live-presence avatars with status dots and a sane overflow chip.",
+    "descriptions": {
+      "en": "Overlapping live-presence avatars with status dots and a sane overflow chip."
+    },
     "name": "presence-stack",
     "stories": [
       {
@@ -2479,6 +2875,9 @@
     "category": "data",
     "defaultStoryId": "canvas-presencesyncindicator--live",
     "description": "Compact pill that surfaces live connection + sync health for a collaborative canvas.",
+    "descriptions": {
+      "en": "Compact pill that surfaces live connection + sync health for a collaborative canvas."
+    },
     "name": "presence-sync-indicator",
     "stories": [
       {
@@ -2504,6 +2903,9 @@
     "category": "billing",
     "defaultStoryId": "billing-pricingtable--default",
     "description": "Plan comparison with feature checklist, tier highlighting, CTA, and an optional monthly/annual toggle.",
+    "descriptions": {
+      "en": "Plan comparison with feature checklist, tier highlighting, CTA, and an optional monthly/annual toggle."
+    },
     "name": "pricing-table",
     "stories": [
       {
@@ -2525,6 +2927,9 @@
     "category": "data-display",
     "defaultStoryId": "magnacarta1215--default",
     "description": "Document viewer for historical primary sources with zoom, rotate, region annotations, transcription panel, and metadata footer.",
+    "descriptions": {
+      "en": "Document viewer for historical primary sources with zoom, rotate, region annotations, transcription panel, and metadata footer."
+    },
     "name": "primary-source-viewer",
     "stories": [
       {
@@ -2546,6 +2951,9 @@
     "category": "learning",
     "defaultStoryId": "learning-protip--default",
     "description": "Highlighted tip block with variants for tips, best practices, gotchas, and more.",
+    "descriptions": {
+      "en": "Highlighted tip block with variants for tips, best practices, gotchas, and more."
+    },
     "name": "pro-tip",
     "stories": [
       {
@@ -2559,6 +2967,9 @@
     "category": "learning",
     "defaultStoryId": "learning-profilesection--default",
     "description": "User profile display section with avatar and details.",
+    "descriptions": {
+      "en": "User profile display section with avatar and details."
+    },
     "name": "profile-section",
     "stories": [
       {
@@ -2572,6 +2983,9 @@
     "category": "data",
     "defaultStoryId": "data-progressbar--default",
     "description": "Visual progress indicator with labels and completion state.",
+    "descriptions": {
+      "en": "Visual progress indicator with labels and completion state."
+    },
     "name": "progress-bar",
     "stories": [
       {
@@ -2585,6 +2999,9 @@
     "category": "data",
     "defaultStoryId": "data-progresscard--default",
     "description": "Card displaying progress metrics and status.",
+    "descriptions": {
+      "en": "Card displaying progress metrics and status."
+    },
     "name": "progress-card",
     "stories": [
       {
@@ -2598,6 +3015,9 @@
     "category": "ai",
     "defaultStoryId": "codereview--default",
     "description": "Searchable prompt template gallery with category filter, variable fill-in form, and onSelect.",
+    "descriptions": {
+      "en": "Searchable prompt template gallery with category filter, variable fill-in form, and onSelect."
+    },
     "name": "prompt-templates",
     "stories": [
       {
@@ -2623,6 +3043,9 @@
     "category": "content",
     "defaultStoryId": "layout--default",
     "description": "Compact key/value grid for inspector panels — labels, sublabels, optional collapse.",
+    "descriptions": {
+      "en": "Compact key/value grid for inspector panels — labels, sublabels, optional collapse."
+    },
     "name": "property-section",
     "stories": [
       {
@@ -2648,6 +3071,9 @@
     "category": "learning",
     "defaultStoryId": "learning-quiz--default",
     "description": "Interactive multiple-choice quiz with hints, explanations, and scoring.",
+    "descriptions": {
+      "en": "Interactive multiple-choice quiz with hints, explanations, and scoring."
+    },
     "name": "quiz",
     "stories": [
       {
@@ -2661,6 +3087,9 @@
     "category": "core",
     "defaultStoryId": "core-radiogroup--default",
     "description": "Group of radio buttons for single-selection input.",
+    "descriptions": {
+      "en": "Group of radio buttons for single-selection input."
+    },
     "name": "radio-group",
     "stories": [
       {
@@ -2674,6 +3103,9 @@
     "category": "learning",
     "defaultStoryId": "learning-rating--default",
     "description": "Inline star rating for lightweight learner feedback.",
+    "descriptions": {
+      "en": "Inline star rating for lightweight learner feedback."
+    },
     "name": "rating",
     "stories": [
       {
@@ -2691,6 +3123,9 @@
     "category": "content",
     "defaultStoryId": "canvas-relationshipinspector--default",
     "description": "Right-dock panel listing inbound + outbound edges of the focused canvas object.",
+    "descriptions": {
+      "en": "Right-dock panel listing inbound + outbound edges of the focused canvas object."
+    },
     "name": "relationship-inspector",
     "stories": [
       {
@@ -2716,6 +3151,9 @@
     "category": "utility",
     "defaultStoryId": "utility-resizable--default",
     "description": "Resizable panel layout with draggable handles.",
+    "descriptions": {
+      "en": "Resizable panel layout with draggable handles."
+    },
     "name": "resizable",
     "stories": [
       {
@@ -2729,6 +3167,9 @@
     "category": "navigation",
     "defaultStoryId": "layout-rightdock--default",
     "description": "Context dock for inspectors, summaries, and secondary canvas panels.",
+    "descriptions": {
+      "en": "Context dock for inspectors, summaries, and secondary canvas panels."
+    },
     "name": "right-dock",
     "stories": [
       {
@@ -2742,6 +3183,9 @@
     "category": "content",
     "defaultStoryId": "accountbilling-rolebadge--default",
     "description": "Account role indicator for owners, admins, members, and billing contacts.",
+    "descriptions": {
+      "en": "Account role indicator for owners, admins, members, and billing contacts."
+    },
     "name": "role-badge",
     "stories": [
       {
@@ -2759,6 +3203,9 @@
     "category": "data-display",
     "defaultStoryId": "maps-routemap--default",
     "description": "Standalone SVG map with animated route paths, waypoints, and progress indicator. For trade routes, voyages, migrations, delivery tracking.",
+    "descriptions": {
+      "en": "Standalone SVG map with animated route paths, waypoints, and progress indicator. For trade routes, voyages, migrations, delivery tracking."
+    },
     "name": "route-map",
     "stories": [
       {
@@ -2788,6 +3235,9 @@
     "category": "content",
     "defaultStoryId": "canvas-routingassignmentpanel--default",
     "description": "Right-dock panel listing the agent slots an active route dispatches to.",
+    "descriptions": {
+      "en": "Right-dock panel listing the agent slots an active route dispatches to."
+    },
     "name": "routing-assignment-panel",
     "stories": [
       {
@@ -2813,6 +3263,9 @@
     "category": "data",
     "defaultStoryId": "canvas-runtimeline--default",
     "description": "Multi-lane execution timeline showing run phases over time, with optional cursor.",
+    "descriptions": {
+      "en": "Multi-lane execution timeline showing run phases over time, with optional cursor."
+    },
     "name": "run-timeline",
     "stories": [
       {
@@ -2838,6 +3291,9 @@
     "category": "content",
     "defaultStoryId": "canvas-runtimeoverviewpanel--default",
     "description": "Top-of-dock summary tile grid for runtime health when no canvas object is selected.",
+    "descriptions": {
+      "en": "Top-of-dock summary tile grid for runtime health when no canvas object is selected."
+    },
     "name": "runtime-overview-panel",
     "stories": [
       {
@@ -2863,6 +3319,9 @@
     "category": "form",
     "defaultStoryId": "analytics-scopeselector--default",
     "description": "Multi-level scope picker for nested environments, teams, and targets.",
+    "descriptions": {
+      "en": "Multi-level scope picker for nested environments, teams, and targets."
+    },
     "name": "scope-selector",
     "stories": [
       {
@@ -2880,6 +3339,9 @@
     "category": "utility",
     "defaultStoryId": "utility-scrollarea--default",
     "description": "Custom scrollable area with styled scrollbars.",
+    "descriptions": {
+      "en": "Custom scrollable area with styled scrollbars."
+    },
     "name": "scroll-area",
     "stories": [
       {
@@ -2893,6 +3355,9 @@
     "category": "form",
     "defaultStoryId": "form-searchbar--default",
     "description": "Text search input with icon and clear functionality.",
+    "descriptions": {
+      "en": "Text search input with icon and clear functionality."
+    },
     "name": "search-bar",
     "stories": [
       {
@@ -2906,6 +3371,9 @@
     "category": "learning",
     "defaultStoryId": "exampletitle--default",
     "description": "Full-screen search dialog with keyboard navigation.",
+    "descriptions": {
+      "en": "Full-screen search dialog with keyboard navigation."
+    },
     "name": "search-dialog",
     "stories": [
       {
@@ -2919,6 +3387,9 @@
     "category": "form",
     "defaultStoryId": "form-segmentedcontrol--default",
     "description": "Single-choice segmented selector for switching modes, views, or filters.",
+    "descriptions": {
+      "en": "Single-choice segmented selector for switching modes, views, or filters."
+    },
     "name": "segmented-control",
     "stories": [
       {
@@ -2940,6 +3411,9 @@
     "category": "form",
     "defaultStoryId": "form-select--default",
     "description": "Dropdown select input for choosing from a list of options.",
+    "descriptions": {
+      "en": "Dropdown select input for choosing from a list of options."
+    },
     "name": "select",
     "stories": [
       {
@@ -2953,6 +3427,9 @@
     "category": "data-display",
     "defaultStoryId": "canvas-selectionhalo--default",
     "description": "Local-user selection halo with corner handles + label slot for spatial canvases.",
+    "descriptions": {
+      "en": "Local-user selection halo with corner handles + label slot for spatial canvases."
+    },
     "name": "selection-halo",
     "stories": [
       {
@@ -2974,6 +3451,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-selectionpresence--default",
     "description": "Dashed-border overlay marking what another user has selected on the canvas.",
+    "descriptions": {
+      "en": "Dashed-border overlay marking what another user has selected on the canvas."
+    },
     "name": "selection-presence",
     "stories": [
       {
@@ -2999,6 +3479,9 @@
     "category": "core",
     "defaultStoryId": "core-separator--default",
     "description": "Visual divider between content sections.",
+    "descriptions": {
+      "en": "Visual divider between content sections."
+    },
     "name": "separator",
     "stories": [
       {
@@ -3012,6 +3495,9 @@
     "category": "data",
     "defaultStoryId": "data-severitybadge--default",
     "description": "Operational severity label with tone variants and optional pulse for critical incidents.",
+    "descriptions": {
+      "en": "Operational severity label with tone variants and optional pulse for critical incidents."
+    },
     "name": "severity-badge",
     "stories": [
       {
@@ -3041,6 +3527,9 @@
     "category": "content",
     "defaultStoryId": "content-sharesection--default",
     "description": "Social sharing buttons and link copy section.",
+    "descriptions": {
+      "en": "Social sharing buttons and link copy section."
+    },
     "name": "share-section",
     "stories": [
       {
@@ -3054,6 +3543,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-sheet--default",
     "description": "Slide-over panel from the edge of the screen.",
+    "descriptions": {
+      "en": "Slide-over panel from the edge of the screen."
+    },
     "name": "sheet",
     "stories": [
       {
@@ -3075,6 +3567,9 @@
     "category": "navigation",
     "defaultStoryId": "introduction--default",
     "description": "Collapsible sidebar navigation layout.",
+    "descriptions": {
+      "en": "Collapsible sidebar navigation layout."
+    },
     "name": "sidebar",
     "stories": [
       {
@@ -3088,6 +3583,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-sidebarprovider--default",
     "description": "Context provider for managing sidebar open/close state.",
+    "descriptions": {
+      "en": "Context provider for managing sidebar open/close state."
+    },
     "name": "sidebar-provider",
     "stories": [
       {
@@ -3101,6 +3599,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-sidebartoggle--default",
     "description": "Responsive toggle button for opening and closing the sidebar.",
+    "descriptions": {
+      "en": "Responsive toggle button for opening and closing the sidebar."
+    },
     "name": "sidebar-toggle",
     "stories": [
       {
@@ -3114,6 +3615,9 @@
     "category": "core",
     "defaultStoryId": "core-skeleton--default",
     "description": "Placeholder loading animation for content.",
+    "descriptions": {
+      "en": "Placeholder loading animation for content."
+    },
     "name": "skeleton",
     "stories": [
       {
@@ -3127,6 +3631,9 @@
     "category": "core",
     "defaultStoryId": "core-slider--default",
     "description": "Range slider input for selecting numeric values.",
+    "descriptions": {
+      "en": "Range slider input for selecting numeric values."
+    },
     "name": "slider",
     "stories": [
       {
@@ -3140,6 +3647,9 @@
     "category": "content",
     "defaultStoryId": "introduction--default",
     "description": "Step-through slideshow for presenting content sequentially.",
+    "descriptions": {
+      "en": "Step-through slideshow for presenting content sequentially."
+    },
     "name": "slideshow",
     "stories": [
       {
@@ -3153,6 +3663,9 @@
     "category": "data-display",
     "defaultStoryId": "canvas-snapguides--default",
     "description": "Alignment guide overlay — dashed vertical and horizontal lines that surface during a drag.",
+    "descriptions": {
+      "en": "Alignment guide overlay — dashed vertical and horizontal lines that surface during a drag."
+    },
     "name": "snap-guides",
     "stories": [
       {
@@ -3174,6 +3687,9 @@
     "category": "data",
     "defaultStoryId": "data-sparklinegrid--default",
     "description": "KPI grid of labeled value tiles each paired with a compact sparkline trend.",
+    "descriptions": {
+      "en": "KPI grid of labeled value tiles each paired with a compact sparkline trend."
+    },
     "name": "sparkline-grid",
     "stories": [
       {
@@ -3191,6 +3707,9 @@
     "category": "utility",
     "defaultStoryId": "utility-spinner--default",
     "description": "Animated loading spinner indicator.",
+    "descriptions": {
+      "en": "Animated loading spinner indicator."
+    },
     "name": "spinner",
     "stories": [
       {
@@ -3204,6 +3723,9 @@
     "category": "data",
     "defaultStoryId": "data-statcard--default",
     "description": "Headline KPI card for metrics, trends, and supporting context.",
+    "descriptions": {
+      "en": "Headline KPI card for metrics, trends, and supporting context."
+    },
     "name": "stat-card",
     "stories": [
       {
@@ -3221,6 +3743,9 @@
     "category": "utility",
     "defaultStoryId": "canvas-statebadgeoverlay--default",
     "description": "State chip pinned to a canvas object's corner — idle, queued, running, complete, failed, stopped.",
+    "descriptions": {
+      "en": "State chip pinned to a canvas object's corner — idle, queued, running, complete, failed, stopped."
+    },
     "name": "state-badge-overlay",
     "stories": [
       {
@@ -3246,6 +3771,9 @@
     "category": "data",
     "defaultStoryId": "servicehealth--default",
     "description": "Service health grid for surfacing infrastructure state, queue pressure, and incidents.",
+    "descriptions": {
+      "en": "Service health grid for surfacing infrastructure state, queue pressure, and incidents."
+    },
     "name": "status-board",
     "stories": [
       {
@@ -3263,6 +3791,9 @@
     "category": "data",
     "defaultStoryId": "data-statusindicator--default",
     "description": "Compact status label with tone, variant, and activity dot options.",
+    "descriptions": {
+      "en": "Compact status label with tone, variant, and activity dot options."
+    },
     "name": "status-indicator",
     "stories": [
       {
@@ -3280,6 +3811,9 @@
     "category": "learning",
     "defaultStoryId": "learning-stepbystep--default",
     "description": "Numbered step guide with optional interactive completion tracking.",
+    "descriptions": {
+      "en": "Numbered step guide with optional interactive completion tracking."
+    },
     "name": "step-by-step",
     "stories": [
       {
@@ -3293,6 +3827,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-stepnavigation--default",
     "description": "Navigation controls for stepping through multi-page content.",
+    "descriptions": {
+      "en": "Navigation controls for stepping through multi-page content."
+    },
     "name": "step-navigation",
     "stories": [
       {
@@ -3306,6 +3843,9 @@
     "category": "learning",
     "defaultStoryId": "introduction--default",
     "description": "Sequenced steps with complete, current, and upcoming states.",
+    "descriptions": {
+      "en": "Sequenced steps with complete, current, and upcoming states."
+    },
     "name": "stepper",
     "stories": [
       {
@@ -3323,6 +3863,9 @@
     "category": "data",
     "defaultStoryId": "canvas-stickymetric--default",
     "description": "Pinned metric pill that sticks to a canvas object's corner.",
+    "descriptions": {
+      "en": "Pinned metric pill that sticks to a canvas object's corner."
+    },
     "name": "sticky-metric",
     "stories": [
       {
@@ -3348,6 +3891,9 @@
     "category": "data-display",
     "defaultStoryId": "educational-storymap--default",
     "description": "Standalone SVG scroll-driven narrative map — IntersectionObserver tracks the active chapter and the map shifts to its center + zoom.",
+    "descriptions": {
+      "en": "Standalone SVG scroll-driven narrative map — IntersectionObserver tracks the active chapter and the map shifts to its center + zoom."
+    },
     "name": "story-map",
     "stories": [
       {
@@ -3369,6 +3915,9 @@
     "category": "content",
     "defaultStoryId": "accountbilling-subscriptioncard--default",
     "description": "Subscription status and management card for plan, renewal, and usage details.",
+    "descriptions": {
+      "en": "Subscription status and management card for plan, renewal, and usage details."
+    },
     "name": "subscription-card",
     "stories": [
       {
@@ -3386,6 +3935,9 @@
     "category": "data",
     "defaultStoryId": "data-table--default",
     "description": "Styled data table with header, body, and footer sections.",
+    "descriptions": {
+      "en": "Styled data table with header, body, and footer sections."
+    },
     "name": "table",
     "stories": [
       {
@@ -3399,6 +3951,9 @@
     "category": "utility",
     "defaultStoryId": "utility-tableofcontents--default",
     "description": "Auto-generated table of contents from page headings.",
+    "descriptions": {
+      "en": "Auto-generated table of contents from page headings."
+    },
     "name": "table-of-contents",
     "stories": [
       {
@@ -3412,6 +3967,9 @@
     "category": "utility",
     "defaultStoryId": "introduction--default",
     "description": "Side panel rendering a table of contents for page navigation.",
+    "descriptions": {
+      "en": "Side panel rendering a table of contents for page navigation."
+    },
     "name": "table-of-contents-panel",
     "stories": [
       {
@@ -3425,6 +3983,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-tabs--default",
     "description": "Tabbed content panels with keyboard-accessible tab triggers.",
+    "descriptions": {
+      "en": "Tabbed content panels with keyboard-accessible tab triggers."
+    },
     "name": "tabs",
     "stories": [
       {
@@ -3438,6 +3999,9 @@
     "category": "form",
     "defaultStoryId": "form-tagsinput--default",
     "description": "Keyboard-friendly tag editor for adding and removing string values.",
+    "descriptions": {
+      "en": "Keyboard-friendly tag editor for adding and removing string values."
+    },
     "name": "tags-input",
     "stories": [
       {
@@ -3459,6 +4023,9 @@
     "category": "content",
     "defaultStoryId": "content-terminal--default",
     "description": "Terminal-style display for command output.",
+    "descriptions": {
+      "en": "Terminal-style display for command output."
+    },
     "name": "terminal",
     "stories": [
       {
@@ -3472,6 +4039,9 @@
     "category": "core",
     "defaultStoryId": "core-textarea--default",
     "description": "Multi-line text input field.",
+    "descriptions": {
+      "en": "Multi-line text input field."
+    },
     "name": "textarea",
     "stories": [
       {
@@ -3485,6 +4055,9 @@
     "category": "utility",
     "defaultStoryId": "utility-themeprovider--default",
     "description": "Context provider for light/dark theme switching.",
+    "descriptions": {
+      "en": "Context provider for light/dark theme switching."
+    },
     "name": "theme-provider",
     "stories": [
       {
@@ -3498,6 +4071,9 @@
     "category": "utility",
     "defaultStoryId": "utility-themetoggle--default",
     "description": "Button to toggle between light and dark themes.",
+    "descriptions": {
+      "en": "Button to toggle between light and dark themes."
+    },
     "name": "theme-toggle",
     "stories": [
       {
@@ -3511,6 +4087,9 @@
     "category": "learning",
     "defaultStoryId": "learning-thinkingblock--default",
     "description": "Collapsible block showing AI thinking/reasoning with streaming support.",
+    "descriptions": {
+      "en": "Collapsible block showing AI thinking/reasoning with streaming support."
+    },
     "name": "thinking-block",
     "stories": [
       {
@@ -3524,6 +4103,9 @@
     "category": "utility",
     "defaultStoryId": "research2025--default",
     "description": "Expanded discussion bubble for an anchored canvas comment thread.",
+    "descriptions": {
+      "en": "Expanded discussion bubble for an anchored canvas comment thread."
+    },
     "name": "thread-bubble",
     "stories": [
       {
@@ -3549,6 +4131,9 @@
     "category": "data",
     "defaultStoryId": "canvas-thresholdring--default",
     "description": "Compact ring gauge expressing how close a value is to a threshold.",
+    "descriptions": {
+      "en": "Compact ring gauge expressing how close a value is to a threshold."
+    },
     "name": "threshold-ring",
     "stories": [
       {
@@ -3574,6 +4159,9 @@
     "category": "data",
     "defaultStoryId": "data-tickertape--default",
     "description": "Marquee-style scrolling symbol tape with price and change badges.",
+    "descriptions": {
+      "en": "Marquee-style scrolling symbol tape with price and change badges."
+    },
     "name": "ticker-tape",
     "stories": [
       {
@@ -3591,6 +4179,9 @@
     "category": "content",
     "defaultStoryId": "content-timeline--default",
     "description": "Vertical or horizontal timeline of sequential events with completed/active/upcoming statuses and connector lines.",
+    "descriptions": {
+      "en": "Vertical or horizontal timeline of sequential events with completed/active/upcoming statuses and connector lines."
+    },
     "name": "timeline",
     "stories": [
       {
@@ -3616,6 +4207,9 @@
     "category": "form",
     "defaultStoryId": "canvas-timelinescrubber--default",
     "description": "Range slider for scrubbing through canvas state playback, with optional milestone ticks.",
+    "descriptions": {
+      "en": "Range slider for scrubbing through canvas state playback, with optional milestone ticks."
+    },
     "name": "timeline-scrubber",
     "stories": [
       {
@@ -3641,6 +4235,9 @@
     "category": "content",
     "defaultStoryId": "content-tldrsection--default",
     "description": "Summary section for quick content overview.",
+    "descriptions": {
+      "en": "Summary section for quick content overview."
+    },
     "name": "tldr-section",
     "stories": [
       {
@@ -3654,6 +4251,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-toast--default",
     "description": "Temporary notification messages with action support.",
+    "descriptions": {
+      "en": "Temporary notification messages with action support."
+    },
     "name": "toast",
     "stories": [
       {
@@ -3675,6 +4275,9 @@
     "category": "core",
     "defaultStoryId": "core-toggle--default",
     "description": "Two-state toggle button.",
+    "descriptions": {
+      "en": "Two-state toggle button."
+    },
     "name": "toggle",
     "stories": [
       {
@@ -3700,6 +4303,9 @@
     "category": "core",
     "defaultStoryId": "core-togglegroup--default",
     "description": "Group of toggle buttons for single or multiple selection.",
+    "descriptions": {
+      "en": "Group of toggle buttons for single or multiple selection."
+    },
     "name": "toggle-group",
     "stories": [
       {
@@ -3713,6 +4319,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-tooltip--default",
     "description": "Informational popup displayed on hover or focus.",
+    "descriptions": {
+      "en": "Informational popup displayed on hover or focus."
+    },
     "name": "tooltip",
     "stories": [
       {
@@ -3726,6 +4335,9 @@
     "category": "navigation",
     "defaultStoryId": "layout-topbar--default",
     "description": "Workspace header bar for titles, leading controls, centered navigation, and trailing actions.",
+    "descriptions": {
+      "en": "Workspace header bar for titles, leading controls, centered navigation, and trailing actions."
+    },
     "name": "top-bar",
     "stories": [
       {
@@ -3739,6 +4351,9 @@
     "category": "learning",
     "defaultStoryId": "overview--default",
     "description": "Guided onboarding flow for introducing content or interface patterns.",
+    "descriptions": {
+      "en": "Guided onboarding flow for introducing content or interface patterns."
+    },
     "name": "tour",
     "stories": [
       {
@@ -3752,6 +4367,9 @@
     "category": "billing",
     "defaultStoryId": "billing-transactionlist--default",
     "description": "Chronological credit/debit history with locale-aware currency formatting and a pinned subscription row.",
+    "descriptions": {
+      "en": "Chronological credit/debit history with locale-aware currency formatting and a pinned subscription row."
+    },
     "name": "transaction-list",
     "stories": [
       {
@@ -3777,6 +4395,9 @@
     "category": "data-display",
     "defaultStoryId": "datadisplay-treeview--default",
     "description": "Hierarchical tree component for nested data with controlled state, single/multi-select, and keyboard navigation.",
+    "descriptions": {
+      "en": "Hierarchical tree component for nested data with controlled state, single/multi-select, and keyboard navigation."
+    },
     "name": "tree-view",
     "stories": [
       {
@@ -3802,6 +4423,9 @@
     "category": "learning",
     "defaultStoryId": "exampletitle--default",
     "description": "Card for displaying tutorial previews with metadata.",
+    "descriptions": {
+      "en": "Card for displaying tutorial previews with metadata."
+    },
     "name": "tutorial-card",
     "stories": [
       {
@@ -3815,6 +4439,9 @@
     "category": "learning",
     "defaultStoryId": "nextsteps--default",
     "description": "Completion screen displayed when a tutorial is finished.",
+    "descriptions": {
+      "en": "Completion screen displayed when a tutorial is finished."
+    },
     "name": "tutorial-complete",
     "stories": [
       {
@@ -3828,6 +4455,9 @@
     "category": "learning",
     "defaultStoryId": "learning-tutorialfilters--default",
     "description": "Filter controls for browsing tutorials by category or difficulty.",
+    "descriptions": {
+      "en": "Filter controls for browsing tutorials by category or difficulty."
+    },
     "name": "tutorial-filters",
     "stories": [
       {
@@ -3841,6 +4471,9 @@
     "category": "learning",
     "defaultStoryId": "reactfundamentals--default",
     "description": "Introduction section for tutorial pages with overview and prerequisites.",
+    "descriptions": {
+      "en": "Introduction section for tutorial pages with overview and prerequisites."
+    },
     "name": "tutorial-intro-content",
     "stories": [
       {
@@ -3854,6 +4487,9 @@
     "category": "learning",
     "defaultStoryId": "learning-tutorialmdx--default",
     "description": "MDX renderer tailored for tutorial content with custom components.",
+    "descriptions": {
+      "en": "MDX renderer tailored for tutorial content with custom components."
+    },
     "name": "tutorial-mdx",
     "stories": [
       {
@@ -3867,6 +4503,9 @@
     "category": "data",
     "defaultStoryId": "usagebreakdown--default",
     "description": "Ranked resource consumption list with relative share and trend cues.",
+    "descriptions": {
+      "en": "Ranked resource consumption list with relative share and trend cues."
+    },
     "name": "usage-breakdown",
     "stories": [
       {
@@ -3888,6 +4527,9 @@
     "category": "content",
     "defaultStoryId": "tutorialvideo--default",
     "description": "Responsive video embed for YouTube and other providers.",
+    "descriptions": {
+      "en": "Responsive video embed for YouTube and other providers."
+    },
     "name": "video-embed",
     "stories": [
       {
@@ -3901,6 +4543,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-viewswitcher--default",
     "description": "URL param-based toggle between named views with pill/tab styling.",
+    "descriptions": {
+      "en": "URL param-based toggle between named views with pill/tab styling."
+    },
     "name": "view-switcher",
     "stories": [
       {
@@ -3914,6 +4559,9 @@
     "category": "navigation",
     "defaultStoryId": "canvas-viewportbookmarks--default",
     "description": "Saved-view list for the canvas — pinned spatial locations with optional active state.",
+    "descriptions": {
+      "en": "Saved-view list for the canvas — pinned spatial locations with optional active state."
+    },
     "name": "viewport-bookmarks",
     "stories": [
       {
@@ -3939,6 +4587,9 @@
     "category": "content",
     "defaultStoryId": "accountbilling-walletcard--default",
     "description": "Credit balance display card for available, pending, and refresh details.",
+    "descriptions": {
+      "en": "Credit balance display card for available, pending, and refresh details."
+    },
     "name": "wallet-card",
     "stories": [
       {
@@ -3956,6 +4607,9 @@
     "category": "data",
     "defaultStoryId": "data-watchlist--default",
     "description": "Tracked-symbol list with price, change, and advancing/declining summary.",
+    "descriptions": {
+      "en": "Tracked-symbol list with price, change, and advancing/declining summary."
+    },
     "name": "watchlist",
     "stories": [
       {
@@ -3973,6 +4627,9 @@
     "category": "navigation",
     "defaultStoryId": "navigation-workspaceswitcher--default",
     "description": "Segmented workspace picker for switching between canvas views and operational contexts.",
+    "descriptions": {
+      "en": "Segmented workspace picker for switching between canvas views and operational contexts."
+    },
     "name": "workspace-switcher",
     "stories": [
       {
@@ -3986,6 +4643,9 @@
     "category": "navigation",
     "defaultStoryId": "canvas-worldbreadcrumbs--default",
     "description": "Spatial trail showing the canvas's current location in a hierarchy of worlds, groups, and runs.",
+    "descriptions": {
+      "en": "Spatial trail showing the canvas's current location in a hierarchy of worlds, groups, and runs."
+    },
     "name": "world-breadcrumbs",
     "stories": [
       {
@@ -4011,6 +4671,9 @@
     "category": "data",
     "defaultStoryId": "followthesunhandoff--default",
     "description": "Multi-timezone display for follow-the-sun teams and operational handoffs.",
+    "descriptions": {
+      "en": "Multi-timezone display for follow-the-sun teams and operational handoffs."
+    },
     "name": "world-clock-bar",
     "stories": [
       {
@@ -4028,6 +4691,9 @@
     "category": "overlay",
     "defaultStoryId": "overlay-zoomhud--default",
     "description": "Zoom controls with current percentage, increment buttons, and reset action for canvas views.",
+    "descriptions": {
+      "en": "Zoom controls with current percentage, increment buttons, and reset action for canvas views."
+    },
     "name": "zoom-hud",
     "stories": [
       {
diff --git a/apps/registry/lib/content.ts b/apps/registry/lib/content.ts
index bec50471..13eb9935 100644
--- a/apps/registry/lib/content.ts
+++ b/apps/registry/lib/content.ts
@@ -3,20 +3,43 @@ import path from "node:path";
 
 import matter from "gray-matter";
 
+import { type Locale, routing } from "@/i18n/routing";
+
 import { type PageFrontmatter, pageFrontmatterSchema } from "./schemas";
 
 type PageContent = {
   content: string;
   frontmatter: PageFrontmatter;
+  locale: Locale;
 };
 
 const CONTENT_DIR = path.join(process.cwd(), "content", "pages");
 
-export async function getPageContent(slug: string): Promise<PageContent> {
-  const filePath = path.join(CONTENT_DIR, `${slug}.mdx`);
+async function readLocalizedPage(slug: string, locale: Locale) {
+  const filePath = path.join(CONTENT_DIR, slug, `${locale}.mdx`);
   const raw = await readFile(filePath, "utf8");
-  const { content, data } = matter(raw);
+
+  return { locale, raw };
+}
+
+export async function getPageContent(
+  slug: string,
+  locale: Locale = routing.defaultLocale,
+): Promise<PageContent> {
+  let resolved;
+
+  try {
+    resolved = await readLocalizedPage(slug, locale);
+  } catch (error) {
+    if (locale === routing.defaultLocale) {
+      throw error;
+    }
+
+    resolved = await readLocalizedPage(slug, routing.defaultLocale);
+  }
+
+  const { content, data } = matter(resolved.raw);
   const frontmatter = pageFrontmatterSchema.parse(data);
 
-  return { content, frontmatter };
+  return { content, frontmatter, locale: resolved.locale };
 }
diff --git a/apps/registry/lib/og.ts b/apps/registry/lib/og.ts
index 2dd5ba20..f485717d 100644
--- a/apps/registry/lib/og.ts
+++ b/apps/registry/lib/og.ts
@@ -1,6 +1,9 @@
 import type { Metadata } from "next";
 import { z } from "zod";
 
+import type { Locale } from "@/i18n/routing";
+import { alternateOgLocales, canonical, ogLocale } from "@/lib/seo";
+
 export const OG_IMAGE_WIDTH = 2400;
 export const OG_IMAGE_HEIGHT = 1260;
 
@@ -17,6 +20,11 @@ export const ogImageParametersSchema = z.object({
 export type OGImageParametersInput = z.input<typeof ogImageParametersSchema>;
 export type OGImageParameters = z.infer<typeof ogImageParametersSchema>;
 
+type PageMetadataOptions = {
+  locale?: Locale;
+  pathname?: string;
+};
+
 export function generateOGImageURL(parameters: OGImageParametersInput): string {
   const validated = ogImageParametersSchema.parse(parameters);
 
@@ -33,14 +41,18 @@ export function generateOGImageURL(parameters: OGImageParametersInput): string {
 
 export function generateOGMetadata(
   parameters: OGImageParametersInput,
+  options: PageMetadataOptions = {},
 ): Metadata["openGraph"] {
   const validated = ogImageParametersSchema.parse(parameters);
+  const locale = options.locale ?? "en";
+  const url = canonical(options.pathname ?? "/", locale);
   const ogImageURL = new URL(
     generateOGImageURL(validated),
     SITE_URL,
   ).toString();
 
   return {
+    alternateLocale: alternateOgLocales(locale),
     description: validated.description,
     images: [
       {
@@ -50,10 +62,11 @@ export function generateOGMetadata(
         width: OG_IMAGE_WIDTH,
       },
     ],
+    locale: ogLocale(locale),
     siteName: "VLLNT UI",
     title: validated.title,
     type: "website",
-    url: SITE_URL,
+    url,
   };
 }
 
diff --git a/apps/registry/lib/registry-i18n.ts b/apps/registry/lib/registry-i18n.ts
new file mode 100644
index 00000000..9b60cdcf
--- /dev/null
+++ b/apps/registry/lib/registry-i18n.ts
@@ -0,0 +1,26 @@
+import type { Locale } from "@/i18n/routing";
+import type { RegistryComponent } from "@/types/registry";
+
+type DescribedRegistryItem = {
+  readonly description?: string;
+  readonly descriptions?: Partial<Record<string, string>>;
+};
+
+export function getLocalizedDescription(
+  component: DescribedRegistryItem,
+  locale: Locale,
+): string {
+  return (
+    component.descriptions?.[locale] ??
+    component.descriptions?.en ??
+    component.description ??
+    ""
+  );
+}
+
+export function getDescriptionSourceLocale(
+  component: RegistryComponent,
+  locale: Locale,
+): Locale {
+  return component.descriptions?.[locale] ? locale : "en";
+}
diff --git a/apps/registry/lib/seo.ts b/apps/registry/lib/seo.ts
index 610dd5b5..7692f9f5 100644
--- a/apps/registry/lib/seo.ts
+++ b/apps/registry/lib/seo.ts
@@ -1,9 +1,47 @@
+import { type Locale, routing } from "@/i18n/routing";
+
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
 
-export function canonical(pathname: string): string {
+export function localizePathname(
+  pathname: string,
+  locale: Locale = routing.defaultLocale,
+): string {
   const trimmed = pathname.startsWith("/") ? pathname : `/${pathname}`;
-  if (trimmed === "/") {
-    return SITE_URL;
+  const normalized = trimmed === "/" ? "" : trimmed.replace(/\/$/, "");
+
+  if (locale === routing.defaultLocale) {
+    return normalized || "/";
   }
-  return `${SITE_URL}${trimmed.replace(/\/$/, "")}`;
+
+  return `/${locale}${normalized}`;
+}
+
+export function canonical(
+  pathname: string,
+  locale: Locale = routing.defaultLocale,
+): string {
+  const localized = localizePathname(pathname, locale);
+  return localized === "/" ? SITE_URL : `${SITE_URL}${localized}`;
+}
+
+export function languageAlternates(pathname: string): Record<string, string> {
+  const alternates = Object.fromEntries(
+    routing.locales.map((locale) => [locale, canonical(pathname, locale)]),
+  );
+
+  return {
+    ...alternates,
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    "x-default": canonical(pathname, routing.defaultLocale),
+  };
+}
+
+export function ogLocale(locale: Locale): string {
+  return locale === "fr" ? "fr_FR" : "en_US";
+}
+
+export function alternateOgLocales(locale: Locale): string[] {
+  return routing.locales
+    .filter((entry) => entry !== locale)
+    .map((entry) => ogLocale(entry));
 }
diff --git a/apps/registry/lib/sidebar-sections.ts b/apps/registry/lib/sidebar-sections.ts
index 3113e4a8..1a01c6b9 100644
--- a/apps/registry/lib/sidebar-sections.ts
+++ b/apps/registry/lib/sidebar-sections.ts
@@ -1,3 +1,7 @@
+/* eslint-disable @typescript-eslint/naming-convention, max-lines-per-function */
+
+import { type Locale, routing } from "@/i18n/routing";
+import { localizePathname } from "@/lib/seo";
 import registryData from "@/registry.json";
 import type {
   ComponentCategory,
@@ -7,21 +11,66 @@ import type {
 
 const registry = registryData as Registry;
 
+type SidebarComponent = {
+  readonly category?: ComponentCategory;
+  readonly description?: string;
+  readonly descriptions?: Partial<Record<string, string>>;
+  readonly name: string;
+  readonly title: string;
+};
+
 const components = registry.items
   .filter(
     (item): item is RegistryComponent => item.type === "registry:component",
   )
   .map((item) => ({
     category: item.category,
+    description: item.description,
+    descriptions: item.descriptions,
     name: item.name,
     title: item.title,
   }))
   .sort((a, b) => a.title.localeCompare(b.title));
 
-const categoryLabels: Record<ComponentCategory, string> = {
+const categoryLabels: Record<Locale, Record<ComponentCategory, string>> = {
+  en: {
+    ai: "AI",
+    billing: "Billing",
+    content: "Content",
+    core: "Core",
+    data: "Data",
+    "data-display": "Data display",
+    educational: "Educational",
+    form: "Form",
+    learning: "Learning",
+    navigation: "Navigation",
+    overlay: "Overlay",
+    utility: "Utility",
+  },
+  fr: {
+    ai: "IA",
+    billing: "Facturation",
+    content: "Contenu",
+    core: "Base",
+    data: "Donnees",
+    "data-display": "Affichage donnees",
+    educational: "Education",
+    form: "Formulaires",
+    learning: "Apprentissage",
+    navigation: "Navigation",
+    overlay: "Surcouches",
+    utility: "Utilitaires",
+  },
+};
+
+const fallbackCategoryLabels: Record<ComponentCategory, string> = {
+  ai: "AI",
+  billing: "Billing",
   content: "Content",
   core: "Core",
   data: "Data",
+  "data-display": "Data display",
+  educational: "Educational",
   form: "Form",
   learning: "Learning",
   navigation: "Navigation",
@@ -29,55 +78,100 @@ const categoryLabels: Record<ComponentCategory, string> = {
   utility: "Utility",
 };
 
+const navLabels: Record<
+  Locale,
+  { components: string; getStarted: string; philosophy: string }
+> = {
+  en: {
+    components: "Components",
+    getStarted: "Get Started",
+    philosophy: "Philosophy",
+  },
+  fr: {
+    components: "Composants",
+    getStarted: "Demarrer",
+    philosophy: "Philosophie",
+  },
+};
+
 const categoryOrder: ComponentCategory[] = [
+  "ai",
   "core",
   "form",
   "overlay",
   "navigation",
   "data",
+  "data-display",
   "content",
+  "educational",
   "learning",
+  "billing",
   "utility",
 ];
 
 function groupComponentsByCategory(
-  items: { category?: ComponentCategory; name: string; title: string }[],
+  items: SidebarComponent[],
+  locale: Locale = routing.defaultLocale,
 ) {
   const grouped = items.reduce((accumulator, item) => {
     const category = item.category ?? "utility";
     const existing = accumulator.get(category) ?? [];
     accumulator.set(category, [
       ...existing,
-      { name: item.name, title: item.title },
+      {
+        description: item.description,
+        descriptions: item.descriptions,
+        name: item.name,
+        title: item.title,
+      },
     ]);
     return accumulator;
-  }, new Map<ComponentCategory, { name: string; title: string }[]>());
+  }, new Map<ComponentCategory, SidebarComponent[]>());
 
   return categoryOrder
     .filter((cat) => grouped.has(cat))
     .map((category) => ({
       category,
       items: grouped.get(category) ?? [],
-      label: categoryLabels[category],
+      label:
+        categoryLabels[locale][category] ??
+        fallbackCategoryLabels[category] ??
+        category,
     }));
 }
 
 const groupedComponents = groupComponentsByCategory(components);
 
-export function getSidebarSections(_activeCategory?: ComponentCategory) {
+export function getGroupedComponents(locale: Locale = routing.defaultLocale) {
+  return groupComponentsByCategory(components, locale);
+}
+
+export function getSidebarSections(
+  _activeCategory?: ComponentCategory,
+  locale: Locale = routing.defaultLocale,
+) {
   return [
     {
       items: [
-        { href: "/", title: "Get Started" },
-        { href: "/philosophy", title: "Philosophy" },
-        { href: "/components", title: "Components" },
+        {
+          href: localizePathname("/", locale),
+          title: navLabels[locale].getStarted,
+        },
+        {
+          href: localizePathname("/philosophy", locale),
+          title: navLabels[locale].philosophy,
+        },
+        {
+          href: localizePathname("/components", locale),
+          title: navLabels[locale].components,
+        },
       ],
     },
-    ...groupedComponents.map((group) => ({
+    ...groupComponentsByCategory(components, locale).map((group) => ({
       collapsible: true,
       defaultOpen: true,
       items: group.items.map((item) => ({
-        href: `/components/${item.name}`,
+        href: localizePathname(`/components/${item.name}`, locale),
         title: item.title,
       })),
       title: group.label,
diff --git a/apps/registry/messages/en.json b/apps/registry/messages/en.json
new file mode 100644
index 00000000..96f30615
--- /dev/null
+++ b/apps/registry/messages/en.json
@@ -0,0 +1,152 @@
+{
+  "common": {
+    "backToHome": "Back home",
+    "browseComponents": "Browse all components",
+    "components": "Components",
+    "docs": "Docs",
+    "getStarted": "Get Started",
+    "github": "GitHub",
+    "home": "Home",
+    "locale": "Language",
+    "philosophy": "Philosophy",
+    "readDocs": "Read the docs",
+    "requestComponent": "Request a component"
+  },
+  "header": {
+    "githubLabel": "VLLNT UI on GitHub",
+    "navComponents": "Components",
+    "navGetStarted": "Get Started",
+    "navPhilosophy": "Philosophy",
+    "searchButton": "Search components...",
+    "searchEmpty": "No components found.",
+    "searchGroup": "Components",
+    "searchPlaceholder": "Search components..."
+  },
+  "footer": {
+    "builtWith": "VLLNT UI · MIT licensed · Built with Radix UI, Tailwind CSS, and CVA",
+    "community": "Community",
+    "discussions": "Discussions",
+    "legal": "Legal",
+    "library": "Library",
+    "maintainedBy": "Maintained by",
+    "registryJson": "Registry JSON",
+    "reportBug": "Report a bug",
+    "resources": "Resources",
+    "sponsor": "Sponsor",
+    "storybook": "Storybook"
+  },
+  "pages": {
+    "components": {
+      "description": "Explore all {count} components available in the library.",
+      "noPreview": "No preview",
+      "stories": "{count, plural, one {# story} other {# stories}}",
+      "title": "Components"
+    },
+    "docs": {
+      "description": "Learn how to use VLLNT UI components in your projects.",
+      "title": "Documentation"
+    },
+    "home": {
+      "description": "Install any of {count} accessible React components with the shadcn CLI. Built on Radix UI, Tailwind CSS, and CVA. Every component is a machine-readable JSON descriptor agents can consume directly. v{version}, MIT licensed.",
+      "title": "VLLNT UI - {count} agent-first React components"
+    },
+    "notFound": {
+      "description": "That route does not exist. Try one of the popular components below, or jump back to the index.",
+      "popular": "Popular components",
+      "title": "Page not found"
+    },
+    "philosophy": {
+      "description": "The principles that guide VLLNT UI design and development.",
+      "title": "Philosophy"
+    },
+    "report": {
+      "description": "Found something broken? Fill out the fields and we'll open a prefilled GitHub issue with the right labels and template.",
+      "metaDescription": "Report a bug in VLLNT UI. The form opens a prefilled GitHub issue - no backend.",
+      "title": "Report a bug"
+    },
+    "requestComponent": {
+      "description": "Don't see what you need? Fill out the fields and we'll open a prefilled GitHub issue with the right labels and template.",
+      "metaDescription": "Request a new VLLNT UI component. The form opens a prefilled GitHub issue - no backend.",
+      "title": "Request a component"
+    },
+    "component": {
+      "code": "Code",
+      "dependencies": "Dependencies",
+      "installation": "Installation",
+      "reportBug": "Report a bug",
+      "storybook": "Storybook",
+      "storybookDescription": "Explore all variants, controls, and accessibility checks in the interactive Storybook playground.",
+      "storiesAvailable": "{count, plural, one {# story available:} other {# stories available:}}",
+      "viewInStorybook": "View in Storybook"
+    }
+  },
+  "landing": {
+    "agent": {
+      "description": "Every component ships as a machine-readable JSON descriptor with name, version, stability, accessibility schema, usage examples, and prop definitions. Agents discover the registry through three surfaces.",
+      "eyebrow": "Agent-first",
+      "llmsDescription": "Concise index per the llmstxt.org spec: sections, links, descriptions.",
+      "llmsFullDescription": "Full registry context in one fetch: docs plus per-component descriptors.",
+      "mcpDescription": "Streamable HTTP MCP server. Tools: search_components, get_component, list_categories.",
+      "open": "Open",
+      "title": "Built so AI coding agents can use it directly."
+    },
+    "community": {
+      "description": "MIT licensed. No tracking. No backend. Issues, ideas, and pull requests welcome.",
+      "openStorybook": "Open Storybook",
+      "requestComponent": "Request a component",
+      "starGithub": "Star on GitHub",
+      "title": "Build with the community."
+    },
+    "featured": {
+      "description": "A few favourites. Browse all {count} from",
+      "title": "Featured components"
+    },
+    "hero": {
+      "browseComponents": "Browse {count} components",
+      "description": "Built on Radix UI, Tailwind CSS, and CVA. Every component is also a machine-readable JSON descriptor: agents read the registry directly without scraping HTML.",
+      "github": "GitHub",
+      "kicker": "v{version} - MIT",
+      "readDocs": "Read the docs",
+      "rscCompatible": "RSC compatible",
+      "subtitle": "Copy, paste, ship.",
+      "tailwindReady": "Tailwind v4 ready",
+      "title": "{count} agent-first React components."
+    },
+    "stats": {
+      "categories": "Categories",
+      "components": "Components",
+      "lastBuild": "Last build",
+      "libraryVersion": "Library version"
+    }
+  },
+  "forms": {
+    "report": {
+      "actualLabel": "Actual behavior",
+      "actualPlaceholder": "What actually happened. Include console output or screenshots if useful.",
+      "componentLabel": "Component (optional)",
+      "componentPlaceholder": "e.g. button, combobox, ai-chat-input",
+      "expectedLabel": "Expected behavior",
+      "expectedPlaceholder": "What you expected to happen.",
+      "note": "Submitting opens a new GitHub issue tab. Nothing is sent to a server.",
+      "reproLabel": "Reproduction",
+      "reproPlaceholder": "Minimal repo / sandbox link / runnable snippet.",
+      "submit": "Open prefilled GitHub issue",
+      "summaryLabel": "One-line summary",
+      "summaryPlaceholder": "Concise headline for the issue title."
+    },
+    "requestComponent": {
+      "nameLabel": "Component name",
+      "namePlaceholder": "e.g. ToastStack",
+      "note": "Submitting opens a new GitHub issue tab. Nothing is sent to a server.",
+      "problemLabel": "What problem does it solve?",
+      "problemPlaceholder": "The user-facing need, not the implementation.",
+      "referenceLabel": "References / prior art (optional)",
+      "referencePlaceholder": "Links, screenshots, design references...",
+      "similarLabel": "Similar to (optional)",
+      "similarPlaceholder": "shadcn Toast, Radix Toast, etc.",
+      "submit": "Open prefilled GitHub issue",
+      "useCaseLabel": "Use case",
+      "useCasePlaceholder": "The concrete scenario where you'd reach for this."
+    }
+  }
+}
diff --git a/apps/registry/messages/fr.json b/apps/registry/messages/fr.json
new file mode 100644
index 00000000..ce20ba32
--- /dev/null
+++ b/apps/registry/messages/fr.json
@@ -0,0 +1,152 @@
+{
+  "common": {
+    "backToHome": "Retour a l'accueil",
+    "browseComponents": "Parcourir les composants",
+    "components": "Composants",
+    "docs": "Documentation",
+    "getStarted": "Demarrer",
+    "github": "GitHub",
+    "home": "Accueil",
+    "locale": "Langue",
+    "philosophy": "Philosophie",
+    "readDocs": "Lire la documentation",
+    "requestComponent": "Demander un composant"
+  },
+  "header": {
+    "githubLabel": "VLLNT UI sur GitHub",
+    "navComponents": "Composants",
+    "navGetStarted": "Demarrer",
+    "navPhilosophy": "Philosophie",
+    "searchButton": "Rechercher des composants...",
+    "searchEmpty": "Aucun composant trouve.",
+    "searchGroup": "Composants",
+    "searchPlaceholder": "Rechercher des composants..."
+  },
+  "footer": {
+    "builtWith": "VLLNT UI · licence MIT · Construit avec Radix UI, Tailwind CSS et CVA",
+    "community": "Communaute",
+    "discussions": "Discussions",
+    "legal": "Legal",
+    "library": "Bibliotheque",
+    "maintainedBy": "Maintenu par",
+    "registryJson": "JSON du registre",
+    "reportBug": "Signaler un bug",
+    "resources": "Ressources",
+    "sponsor": "Sponsoriser",
+    "storybook": "Storybook"
+  },
+  "pages": {
+    "components": {
+      "description": "Explorez les {count} composants disponibles dans la bibliotheque.",
+      "noPreview": "Aucun apercu",
+      "stories": "{count, plural, one {# story} other {# stories}}",
+      "title": "Composants"
+    },
+    "docs": {
+      "description": "Apprenez a utiliser les composants VLLNT UI dans vos projets.",
+      "title": "Documentation"
+    },
+    "home": {
+      "description": "Installez n'importe lequel des {count} composants React accessibles avec la CLI shadcn. Construit sur Radix UI, Tailwind CSS et CVA. Chaque composant est un descripteur JSON lisible par les agents. v{version}, licence MIT.",
+      "title": "VLLNT UI - {count} composants React agent-first"
+    },
+    "notFound": {
+      "description": "Cette route n'existe pas. Essayez l'un des composants populaires ci-dessous ou retournez a l'index.",
+      "popular": "Composants populaires",
+      "title": "Page introuvable"
+    },
+    "philosophy": {
+      "description": "Les principes qui guident la conception et le developpement de VLLNT UI.",
+      "title": "Philosophie"
+    },
+    "report": {
+      "description": "Vous avez trouve quelque chose de casse ? Remplissez les champs et nous ouvrirons une issue GitHub pre-remplie avec les bons labels et le bon template.",
+      "metaDescription": "Signalez un bug dans VLLNT UI. Le formulaire ouvre une issue GitHub pre-remplie, sans backend.",
+      "title": "Signaler un bug"
+    },
+    "requestComponent": {
+      "description": "Vous ne trouvez pas ce dont vous avez besoin ? Remplissez les champs et nous ouvrirons une issue GitHub pre-remplie avec les bons labels et le bon template.",
+      "metaDescription": "Demandez un nouveau composant VLLNT UI. Le formulaire ouvre une issue GitHub pre-remplie, sans backend.",
+      "title": "Demander un composant"
+    },
+    "component": {
+      "code": "Code",
+      "dependencies": "Dependances",
+      "installation": "Installation",
+      "reportBug": "Signaler un bug",
+      "storybook": "Storybook",
+      "storybookDescription": "Explorez les variantes, controles et verifications d'accessibilite dans le playground Storybook interactif.",
+      "storiesAvailable": "{count, plural, one {# story disponible :} other {# stories disponibles :}}",
+      "viewInStorybook": "Voir dans Storybook"
+    }
+  },
+  "landing": {
+    "agent": {
+      "description": "Chaque composant est publie comme descripteur JSON lisible par machine avec nom, version, stabilite, schema d'accessibilite, exemples d'usage et definitions de props. Les agents decouvrent le registre via trois surfaces.",
+      "eyebrow": "Agent-first",
+      "llmsDescription": "Index concis selon la specification llmstxt.org : sections, liens et descriptions.",
+      "llmsFullDescription": "Contexte complet du registre en une requete : docs et descripteurs par composant.",
+      "mcpDescription": "Serveur HTTP MCP streamable. Outils : search_components, get_component, list_categories.",
+      "open": "Ouvrir",
+      "title": "Concu pour que les agents de code l'utilisent directement."
+    },
+    "community": {
+      "description": "Licence MIT. Pas de tracking. Pas de backend. Issues, idees et pull requests sont bienvenues.",
+      "openStorybook": "Ouvrir Storybook",
+      "requestComponent": "Demander un composant",
+      "starGithub": "Star sur GitHub",
+      "title": "Construisez avec la communaute."
+    },
+    "featured": {
+      "description": "Quelques favoris. Parcourez les {count} depuis",
+      "title": "Composants en avant"
+    },
+    "hero": {
+      "browseComponents": "Parcourir {count} composants",
+      "description": "Construit sur Radix UI, Tailwind CSS et CVA. Chaque composant est aussi un descripteur JSON lisible par machine : les agents lisent le registre directement sans scraper le HTML.",
+      "github": "GitHub",
+      "kicker": "v{version} - MIT",
+      "readDocs": "Lire la documentation",
+      "rscCompatible": "Compatible RSC",
+      "subtitle": "Copiez, collez, livrez.",
+      "tailwindReady": "Pret pour Tailwind v4",
+      "title": "{count} composants React agent-first."
+    },
+    "stats": {
+      "categories": "Categories",
+      "components": "Composants",
+      "lastBuild": "Dernier build",
+      "libraryVersion": "Version library"
+    }
+  },
+  "forms": {
+    "report": {
+      "actualLabel": "Comportement actuel",
+      "actualPlaceholder": "Ce qui s'est produit. Ajoutez console ou captures si utile.",
+      "componentLabel": "Composant (optionnel)",
+      "componentPlaceholder": "ex. button, combobox, ai-chat-input",
+      "expectedLabel": "Comportement attendu",
+      "expectedPlaceholder": "Ce que vous attendiez.",
+      "note": "La soumission ouvre un nouvel onglet GitHub. Rien n'est envoye a un serveur.",
+      "reproLabel": "Reproduction",
+      "reproPlaceholder": "Depot minimal / lien sandbox / snippet executable.",
+      "submit": "Ouvrir une issue GitHub pre-remplie",
+      "summaryLabel": "Resume en une ligne",
+      "summaryPlaceholder": "Titre concis pour l'issue."
+    },
+    "requestComponent": {
+      "nameLabel": "Nom du composant",
+      "namePlaceholder": "ex. ToastStack",
+      "note": "La soumission ouvre un nouvel onglet GitHub. Rien n'est envoye a un serveur.",
+      "problemLabel": "Quel probleme resout-il ?",
+      "problemPlaceholder": "Le besoin utilisateur, pas l'implementation.",
+      "referenceLabel": "References / inspirations (optionnel)",
+      "referencePlaceholder": "Liens, captures, references design...",
+      "similarLabel": "Similaire a (optionnel)",
+      "similarPlaceholder": "shadcn Toast, Radix Toast, etc.",
+      "submit": "Ouvrir une issue GitHub pre-remplie",
+      "useCaseLabel": "Cas d'usage",
+      "useCasePlaceholder": "Le scenario concret ou vous utiliseriez ce composant."
+    }
+  }
+}
diff --git a/apps/registry/next.config.mjs b/apps/registry/next.config.mjs
index b1d3d69a..73f3c76e 100644
--- a/apps/registry/next.config.mjs
+++ b/apps/registry/next.config.mjs
@@ -1,4 +1,7 @@
 import createMDX from '@next/mdx'
+import createNextIntlPlugin from 'next-intl/plugin'
+
+const withNextIntl = createNextIntlPlugin()
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
@@ -21,5 +24,4 @@ const withMDX = createMDX({
 })
 
 // Combine MDX and Next.js config
-export default withMDX(nextConfig)
-
+export default withNextIntl(withMDX(nextConfig))
diff --git a/apps/registry/package.json b/apps/registry/package.json
index e00e1b04..5400016e 100644
--- a/apps/registry/package.json
+++ b/apps/registry/package.json
@@ -10,6 +10,7 @@
     "start": "next start",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "check:translations": "tsx scripts/check-page-translations.ts",
     "registry:build": "tsx scripts/inline-component-source.ts && shadcn build && tsx scripts/stamp-registry-metadata.ts && tsx scripts/generate-component-metadata.ts",
     "registry:sync-shims": "tsx scripts/inline-component-source.ts",
     "sync-storybook": "tsx scripts/generate-component-metadata.ts"
@@ -25,6 +26,7 @@
     "gray-matter": "^4.0.3",
     "lucide-react": "^0.468.0",
     "next": "16.1.6",
+    "next-intl": "^4.11.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-markdown": "^10.1.0",
diff --git a/apps/registry/proxy.ts b/apps/registry/proxy.ts
new file mode 100644
index 00000000..952028e3
--- /dev/null
+++ b/apps/registry/proxy.ts
@@ -0,0 +1,9 @@
+import createMiddleware from "next-intl/middleware";
+
+import { routing } from "./i18n/routing";
+
+export default createMiddleware(routing);
+
+export const config = {
+  matcher: "/((?!api(?:/|$)|mcp(?:/|$)|r(?:/|$)|_next|_vercel|.*\\..*).*)",
+};
diff --git a/apps/registry/registry.json b/apps/registry/registry.json
index 029360c6..7edec4d4 100644
--- a/apps/registry/registry.json
+++ b/apps/registry/registry.json
@@ -20,7 +20,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Collapsible content sections supporting single or multiple open items."
+      }
     },
     {
       "name": "activity-heatmap",
@@ -39,7 +42,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Contribution-style grid for visualizing operational activity over time."
+      }
     },
     {
       "name": "activity-log",
@@ -58,7 +64,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Paginated activity feed for audit history and analytics changes."
+      }
     },
     {
       "name": "agent-activity",
@@ -78,7 +87,10 @@
       ],
       "category": "ai",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Visual display of an AI agent's execution chain — steps, tools, decisions, progress."
+      }
     },
     {
       "name": "ai-artifact",
@@ -98,7 +110,10 @@
       ],
       "category": "ai",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Rendered output area for AI-generated content with toolbar, copy/edit/download/fullscreen actions, and version chips."
+      }
     },
     {
       "name": "ai-chat-input",
@@ -118,7 +133,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Prompt composer for conversational interfaces with helper text, toolbar actions, and submit states."
+      }
     },
     {
       "name": "ai-message-bubble",
@@ -138,7 +156,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Chat bubble for assistant, user, tool, and system messages using the current design system surfaces."
+      }
     },
     {
       "name": "ai-sidebar",
@@ -158,7 +179,10 @@
       ],
       "category": "ai",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Slide-out AI assistant panel with provider, header / content / footer slots, and a standalone trigger."
+      }
     },
     {
       "name": "ai-source-citation",
@@ -178,7 +202,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact source reference card for AI answers with a title, origin label, and optional excerpt."
+      }
     },
     {
       "name": "ai-streaming-text",
@@ -197,7 +224,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Readable text block for partial assistant output with an optional live cursor while tokens stream in."
+      }
     },
     {
       "name": "ai-tool-call-display",
@@ -218,7 +248,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Structured card for tool invocation traces, statuses, serialized input, and returned output."
+      }
     },
     {
       "name": "alert",
@@ -237,7 +270,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Displays an alert message to the user."
+      }
     },
     {
       "name": "alert-dialog",
@@ -256,7 +292,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Modal dialog for confirming destructive or important actions."
+      }
     },
     {
       "name": "alert-pulse",
@@ -275,7 +314,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Pulsing ring overlay for alerting canvas objects, with severity tones."
+      }
     },
     {
       "name": "anchor-port",
@@ -294,7 +336,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Port marker for object inputs, outputs, and bidirectional links on the canvas."
+      }
     },
     {
       "name": "animated-text",
@@ -313,7 +358,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Staggered text reveal for headings, pull quotes, and short supporting copy."
+      }
     },
     {
       "name": "annotation",
@@ -332,7 +380,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Inline highlight with an attached contextual note."
+      }
     },
     {
       "name": "area-chart",
@@ -366,7 +417,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Constrains content to a specified aspect ratio."
+      }
     },
     {
       "name": "auto-reload",
@@ -385,7 +439,10 @@
       ],
       "category": "billing",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Toggle + collapsible threshold/amount form for automatic credit reloading with locale-aware currency."
+      }
     },
     {
       "name": "avatar",
@@ -404,7 +461,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Displays a user avatar image with fallback initials."
+      }
     },
     {
       "name": "avatar-group",
@@ -423,7 +483,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Overlapping avatar stack for participants, assignees, and collaborative contexts."
+      }
     },
     {
       "name": "badge",
@@ -442,7 +505,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Small status label with variant styles."
+      }
     },
     {
       "name": "banner",
@@ -464,7 +530,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Full-width announcement bar with variants, dismissal, and an optional action slot."
+      }
     },
     {
       "name": "bar-chart",
@@ -498,7 +567,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Card layout for displaying blog post previews."
+      }
     },
     {
       "name": "border-beam",
@@ -517,7 +589,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Animated accent beam that travels around the border of a highlighted surface."
+      }
     },
     {
       "name": "bottom-activity-strip",
@@ -536,7 +611,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Slim horizontally-scrolling row of recent canvas events for low-noise live activity."
+      }
     },
     {
       "name": "breadcrumb",
@@ -555,7 +633,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Navigation breadcrumb trail showing the current page hierarchy."
+      }
     },
     {
       "name": "button",
@@ -637,7 +718,10 @@
           "required": false,
           "description": "All native <button> attributes are forwarded."
         }
-      ]
+      ],
+      "descriptions": {
+        "en": "Interactive button with multiple variants and sizes."
+      }
     },
     {
       "name": "calendar",
@@ -656,7 +740,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Date picker calendar for selecting dates."
+      }
     },
     {
       "name": "callout",
@@ -675,7 +762,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Highlighted content block with variant styles for info, warning, danger, and more."
+      }
     },
     {
       "name": "candlestick-chart",
@@ -694,7 +784,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "OHLC financial chart for session-by-session price action."
+      }
     },
     {
       "name": "canvas-shell",
@@ -713,7 +806,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Layout shell for canvas workspaces with top bar, left rail, right dock, and bottom slot regions."
+      }
     },
     {
       "name": "canvas-view",
@@ -732,7 +828,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive pan-and-zoom viewport for spatial surfaces with keyboard, wheel, and overlay support."
+      }
     },
     {
       "name": "card",
@@ -751,7 +850,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Container with header, content, and footer sections."
+      }
     },
     {
       "name": "carousel",
@@ -770,7 +872,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Scrollable content carousel with navigation controls."
+      }
     },
     {
       "name": "category-filter",
@@ -789,7 +894,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Filterable category selection for content lists."
+      }
     },
     {
       "name": "checkbox",
@@ -808,7 +916,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Toggle control for boolean input."
+      }
     },
     {
       "name": "checklist",
@@ -827,7 +938,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive checklist with progress tracking and toggleable items."
+      }
     },
     {
       "name": "choropleth-map",
@@ -846,7 +960,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Standalone SVG choropleth — region polygons shaded by data value with tooltip, legend, and accessible data-table fallback."
+      }
     },
     {
       "name": "chronological-timeline",
@@ -865,7 +982,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Media-rich, scroll-driven chronological timeline with alternating cards, image/video/audio media, and a progress strip."
+      }
     },
     {
       "name": "civilization-card",
@@ -885,7 +1005,10 @@
       ],
       "category": "educational",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Civilization overview with hero band, BCE/CE era timeline, key stats, achievements, and notable leaders."
+      }
     },
     {
       "name": "code-block",
@@ -904,7 +1027,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Syntax-highlighted code display with copy support."
+      }
     },
     {
       "name": "code-playground",
@@ -923,7 +1049,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive code editor with live preview."
+      }
     },
     {
       "name": "collapsible",
@@ -942,7 +1071,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Expandable and collapsible content section."
+      }
     },
     {
       "name": "combobox",
@@ -1066,7 +1198,10 @@
           "required": false,
           "description": "Class applied to the inner Command element."
         }
-      ]
+      ],
+      "descriptions": {
+        "en": "Searchable select input for choosing from a list of options."
+      }
     },
     {
       "name": "command",
@@ -1085,7 +1220,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Command palette with search, groups, and keyboard navigation."
+      }
     },
     {
       "name": "comment-pin",
@@ -1104,7 +1242,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Anchored discussion pin rendered at canvas coordinates with author + unread badge."
+      }
     },
     {
       "name": "comparison",
@@ -1123,7 +1264,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Side-by-side comparison layout for content or features."
+      }
     },
     {
       "name": "completion-dialog",
@@ -1142,7 +1286,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Dialog displayed upon completing a task or workflow."
+      }
     },
     {
       "name": "connector-edge",
@@ -1161,7 +1308,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Curved edge between canvas objects with optional inline label state."
+      }
     },
     {
       "name": "content-intro",
@@ -1180,7 +1330,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Introductory section for content pages with title and description."
+      }
     },
     {
       "name": "context-lens",
@@ -1199,7 +1352,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Vignette overlay that dims the canvas outside a circular focus region."
+      }
     },
     {
       "name": "context-menu",
@@ -1218,7 +1374,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Right-click context menu with items and submenus."
+      }
     },
     {
       "name": "copy-button",
@@ -1238,7 +1397,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Click-to-copy utility with confirmation feedback and a useCopyToClipboard hook."
+      }
     },
     {
       "name": "countdown-timer",
@@ -1257,7 +1419,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Countdown and SLA timer for deadlines, escalations, and response windows."
+      }
     },
     {
       "name": "credit-badge",
@@ -1276,7 +1441,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Balance status pill for credits, wallet states, and billing health."
+      }
     },
     {
       "name": "data-list",
@@ -1295,7 +1463,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Semantic key-value metadata layout for displaying labels with values."
+      }
     },
     {
       "name": "data-table",
@@ -1315,7 +1486,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Enhanced data table with sorting, filtering, selection, and pagination controls."
+      }
     },
     {
       "name": "date-picker",
@@ -1334,7 +1508,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Single-date picker built with the shared calendar and popover primitives."
+      }
     },
     {
       "name": "dialog",
@@ -1373,6 +1550,9 @@
         ],
         "focusManagement": "auto",
         "notes": "Built on Radix Dialog: focus trap + restore on close + scroll lock are automatic."
+      },
+      "descriptions": {
+        "en": "Modal dialog overlay for focused content and actions."
       }
     },
     {
@@ -1393,7 +1573,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Newer/older navigator: links to the previous and next item in an ordered series."
+      }
     },
     {
       "name": "drawer",
@@ -1412,7 +1595,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Slide-out panel anchored to the screen edge."
+      }
     },
     {
       "name": "dropdown-menu",
@@ -1431,7 +1617,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Accessible dropdown menu with items, checkboxes, radio groups, and submenus."
+      }
     },
     {
       "name": "edge-label",
@@ -1450,7 +1639,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Inline edge label for relationship semantics such as streams, handoffs, or policies."
+      }
     },
     {
       "name": "empty-state",
@@ -1478,7 +1670,10 @@
           "code": "import { Button, EmptyState } from \"@vllnt/ui\";\nimport { Inbox } from \"lucide-react\";\n\nexport function Demo() {\n  return (\n    <EmptyState\n      icon={<Inbox className=\"h-8 w-8\" />}\n      title=\"No tickets yet\"\n      description=\"Create your first support ticket to start tracking conversations.\"\n      action={<Button>Create ticket</Button>}\n    />\n  );\n}\n",
           "framework": "react"
         }
-      ]
+      ],
+      "descriptions": {
+        "en": "Centered placeholder for empty lists, tables, and search results with sm/md/lg sizes."
+      }
     },
     {
       "name": "era-comparison",
@@ -1497,7 +1692,10 @@
       ],
       "category": "educational",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Side-by-side comparison of historical eras with domain rows, color-themed columns, highlights, and figure chips."
+      }
     },
     {
       "name": "exercise",
@@ -1516,7 +1714,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive exercise block for learning content."
+      }
     },
     {
       "name": "faq",
@@ -1535,7 +1736,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Frequently asked questions section with expandable answers."
+      }
     },
     {
       "name": "file-upload",
@@ -1554,7 +1758,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Dropzone-style file picker with previews for selected files."
+      }
     },
     {
       "name": "filter-bar",
@@ -1573,7 +1780,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Horizontal bar with filter controls for content lists."
+      }
     },
     {
       "name": "flashcard",
@@ -1592,7 +1802,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Study card for active recall with prompt and answer states."
+      }
     },
     {
       "name": "floating-action-button",
@@ -1611,7 +1824,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Fixed-position action button for primary actions."
+      }
     },
     {
       "name": "floating-toolbar",
@@ -1630,7 +1846,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact action bar that floats above a selection — primary / ghost / destructive variants."
+      }
     },
     {
       "name": "flow-diagram",
@@ -1649,7 +1868,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive flow diagram with nodes, edges, and controls."
+      }
     },
     {
       "name": "follow-mode",
@@ -1668,7 +1890,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Follow-mode chrome — outlines a region with a participant's color and surfaces a stop-following chip."
+      }
     },
     {
       "name": "form",
@@ -1687,7 +1912,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Validation wrapper for composing labels, descriptions, controls, and messages."
+      }
     },
     {
       "name": "gantt-chart",
@@ -1706,7 +1934,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Project timeline with task bars, progress overlays, milestones, and a today indicator across day/week/month/quarter scales."
+      }
     },
     {
       "name": "geography-quiz-map",
@@ -1725,7 +1956,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive identify-mode map quiz — click the correct region per prompt with visual feedback, score, and results panel."
+      }
     },
     {
       "name": "globe-3d",
@@ -1744,7 +1978,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Standalone SVG pseudo-3D globe — orthographic projection with auto-rotation, drag interaction, lat/lng markers, and great-circle arcs."
+      }
     },
     {
       "name": "group-hull",
@@ -1763,7 +2000,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Durable boundary wrapper for related runtime objects sharing context or ownership."
+      }
     },
     {
       "name": "handoff-beacon",
@@ -1782,7 +2022,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Attention-routing beacon with pulsing ring and optional source / message card for live canvases."
+      }
     },
     {
       "name": "heat-map-overlay",
@@ -1801,7 +2044,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Standalone SVG geographic heat map — radial-gradient blobs with configurable radius, blur, gradient, and opacity."
+      }
     },
     {
       "name": "heat-overlay",
@@ -1820,7 +2066,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Heatmap-style overlay drawing soft radial blobs for canvas activity samples."
+      }
     },
     {
       "name": "historic-timeline",
@@ -1839,7 +2088,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Specialized timeline for historical events spanning centuries or millennia, with era bands, period bars, and BCE/CE point markers."
+      }
     },
     {
       "name": "historical-figure-card",
@@ -1859,7 +2111,10 @@
       ],
       "category": "educational",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Profile card with portrait, lifespan timeline, fields, works, quote, connections, and an expandable biography section."
+      }
     },
     {
       "name": "horizontal-scroll-row",
@@ -1879,7 +2134,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Horizontal scroll container with snap scrolling, chevron navigation, and hidden scrollbar."
+      }
     },
     {
       "name": "hover-card",
@@ -1898,7 +2156,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Card that appears on hover for previewing content."
+      }
     },
     {
       "name": "infinite-plane",
@@ -1917,7 +2178,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Tiled pannable backdrop for the canvas with dot or grid pattern that drifts with the viewport."
+      }
     },
     {
       "name": "inline-input",
@@ -1936,7 +2200,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Inline text input with keyboard commit and cancel support."
+      }
     },
     {
       "name": "input",
@@ -1955,7 +2222,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Text input field for forms."
+      }
     },
     {
       "name": "input-otp",
@@ -1974,7 +2244,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "One-time password input with segmented fields."
+      }
     },
     {
       "name": "interactive-timeline",
@@ -1993,7 +2266,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Zoomable, pannable, multi-track timeline with category filter, today marker, and click-to-select events."
+      }
     },
     {
       "name": "jarvis-dock",
@@ -2012,7 +2288,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Floating bottom dock with quick-action buttons + a command-palette trigger."
+      }
     },
     {
       "name": "kbd",
@@ -2032,7 +2311,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Keyboard key indicator with platform-aware modifier expansion via the shortcut prop."
+      }
     },
     {
       "name": "key-concept",
@@ -2051,7 +2333,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Highlighted definition block for key terms and a glossary list."
+      }
     },
     {
       "name": "keyboard-shortcuts-help",
@@ -2070,7 +2355,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Displays available keyboard shortcuts to the user."
+      }
     },
     {
       "name": "knowledge-check",
@@ -2090,7 +2378,10 @@
       ],
       "category": "educational",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Inline knowledge check with multiple-choice / true-false / fill-blank questions, per-answer feedback, and a final score summary."
+      }
     },
     {
       "name": "lang-provider",
@@ -2109,7 +2400,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Context provider for language and internationalization."
+      }
     },
     {
       "name": "learning-objectives",
@@ -2128,7 +2422,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Lists learning goals for educational content."
+      }
     },
     {
       "name": "left-rail",
@@ -2147,7 +2444,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact vertical rail for canvas modes, tool actions, and secondary navigation controls."
+      }
     },
     {
       "name": "line-chart",
@@ -2181,7 +2481,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Remote user's cursor rendered at canvas coordinates with name + status chip."
+      }
     },
     {
       "name": "live-feed",
@@ -2200,7 +2503,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Rolling activity stream for surfacing incidents, deploys, and operational signals in real time."
+      }
     },
     {
       "name": "map-2d",
@@ -2219,7 +2525,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Lightweight 2D map primitive — SVG canvas with equirectangular projection, markers, popups, GeoJSON polygon layers, zoom controls, and an optional backdrop image."
+      }
     },
     {
       "name": "map-timeline",
@@ -2238,7 +2547,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Standalone SVG map + time slider — era polygons and year-pinned events appear as the user scrubs the timeline."
+      }
     },
     {
       "name": "market-treemap",
@@ -2257,7 +2569,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Sector-style market heatmap using weighted tiles and signed performance colors."
+      }
     },
     {
       "name": "marquee",
@@ -2276,7 +2591,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Continuously scrolling content lane for badges, logos, and status chips."
+      }
     },
     {
       "name": "mdx-content",
@@ -2295,7 +2613,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Renders MDX content with component mapping."
+      }
     },
     {
       "name": "menubar",
@@ -2314,7 +2635,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Horizontal menu bar with dropdown menus."
+      }
     },
     {
       "name": "metric-cluster",
@@ -2333,7 +2657,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact stack of related metrics pinned to a canvas object's corner."
+      }
     },
     {
       "name": "metric-gauge",
@@ -2352,7 +2679,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Real-time arc and dial display for monitored percentages and utilization."
+      }
     },
     {
       "name": "mini-map-panel",
@@ -2371,7 +2701,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Viewport overview panel showing canvas bounds, markers, and the current zoom window."
+      }
     },
     {
       "name": "model-comparison",
@@ -2391,7 +2724,10 @@
       ],
       "category": "ai",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Side-by-side comparison of AI model responses with optional blind mode, metadata stats, and a vote bar."
+      }
     },
     {
       "name": "model-selector",
@@ -2410,7 +2746,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Dropdown selector for choosing AI models."
+      }
     },
     {
       "name": "multi-select",
@@ -2429,7 +2768,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Popover-based multi-selection input with selected-value badges and optional search."
+      }
     },
     {
       "name": "multi-select-lasso",
@@ -2448,7 +2790,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Selection rectangle overlay for canvas multi-select gestures."
+      }
     },
     {
       "name": "navbar-saas",
@@ -2467,7 +2812,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "SaaS-style navigation bar with branding and links."
+      }
     },
     {
       "name": "navigation-menu",
@@ -2486,7 +2834,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Accessible navigation menu with links and sub-navigation."
+      }
     },
     {
       "name": "newsletter-signup",
@@ -2506,7 +2857,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Email-capture form with idle/sending/sent/error state machine, custom validators, and overridable labels."
+      }
     },
     {
       "name": "number-input",
@@ -2525,7 +2879,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Numeric input with increment and decrement controls."
+      }
     },
     {
       "name": "number-ticker",
@@ -2544,7 +2901,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Animated number transitions for stats, KPIs, and compact numeric callouts."
+      }
     },
     {
       "name": "object-card",
@@ -2563,7 +2923,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Durable object view for agents, runs, artifacts, and tasks inside the canvas."
+      }
     },
     {
       "name": "object-handle",
@@ -2582,7 +2945,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Drag/reposition affordance for spatial objects that need a calm grab target."
+      }
     },
     {
       "name": "object-inspector",
@@ -2601,7 +2967,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Right-dock detail header — kind chip, status dot, title/subtitle, with property-section slots."
+      }
     },
     {
       "name": "order-book",
@@ -2620,7 +2989,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Level II bid/ask depth ladder with cumulative size bars and spread readout."
+      }
     },
     {
       "name": "pagination",
@@ -2639,7 +3011,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Page navigation controls with previous, next, and page links."
+      }
     },
     {
       "name": "parallel-timeline",
@@ -2658,7 +3033,10 @@
       ],
       "category": "educational",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Multi-track timeline with shared time axis, BCE/CE event markers, and optional era bands for comparative history."
+      }
     },
     {
       "name": "password-input",
@@ -2677,7 +3055,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Password field with a built-in visibility toggle."
+      }
     },
     {
       "name": "plan-badge",
@@ -2696,7 +3077,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Subscription tier indicator for pricing, billing, and account summaries."
+      }
     },
     {
       "name": "playback-ghost",
@@ -2715,7 +3099,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Translucent overlay marking where a canvas object was at a previous timestamp during playback."
+      }
     },
     {
       "name": "policy-delivery-panel",
@@ -2734,7 +3121,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Right-dock panel listing policies / guardrails active for the route or run."
+      }
     },
     {
       "name": "popover",
@@ -2753,7 +3143,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Floating content panel anchored to a trigger element."
+      }
     },
     {
       "name": "presence-stack",
@@ -2772,7 +3165,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Overlapping live-presence avatars with status dots and a sane overflow chip."
+      }
     },
     {
       "name": "presence-sync-indicator",
@@ -2791,7 +3187,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact pill that surfaces live connection + sync health for a collaborative canvas."
+      }
     },
     {
       "name": "pricing-table",
@@ -2811,7 +3210,10 @@
       ],
       "category": "billing",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Plan comparison with feature checklist, tier highlighting, CTA, and an optional monthly/annual toggle."
+      }
     },
     {
       "name": "primary-source-viewer",
@@ -2830,7 +3232,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Document viewer for historical primary sources with zoom, rotate, region annotations, transcription panel, and metadata footer."
+      }
     },
     {
       "name": "pro-tip",
@@ -2849,7 +3254,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Highlighted tip block with variants for tips, best practices, gotchas, and more."
+      }
     },
     {
       "name": "profile-section",
@@ -2868,7 +3276,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "User profile display section with avatar and details."
+      }
     },
     {
       "name": "progress-bar",
@@ -2887,7 +3298,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Visual progress indicator with labels and completion state."
+      }
     },
     {
       "name": "progress-card",
@@ -2906,7 +3320,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Card displaying progress metrics and status."
+      }
     },
     {
       "name": "prompt-templates",
@@ -2926,7 +3343,10 @@
       ],
       "category": "ai",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Searchable prompt template gallery with category filter, variable fill-in form, and onSelect."
+      }
     },
     {
       "name": "property-section",
@@ -2945,7 +3365,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact key/value grid for inspector panels — labels, sublabels, optional collapse."
+      }
     },
     {
       "name": "quiz",
@@ -2964,7 +3387,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Interactive multiple-choice quiz with hints, explanations, and scoring."
+      }
     },
     {
       "name": "radio-group",
@@ -2983,7 +3409,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Group of radio buttons for single-selection input."
+      }
     },
     {
       "name": "rating",
@@ -3002,7 +3431,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Inline star rating for lightweight learner feedback."
+      }
     },
     {
       "name": "relationship-inspector",
@@ -3021,7 +3453,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Right-dock panel listing inbound + outbound edges of the focused canvas object."
+      }
     },
     {
       "name": "resizable",
@@ -3040,7 +3475,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Resizable panel layout with draggable handles."
+      }
     },
     {
       "name": "right-dock",
@@ -3059,7 +3497,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Context dock for inspectors, summaries, and secondary canvas panels."
+      }
     },
     {
       "name": "role-badge",
@@ -3078,7 +3519,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Account role indicator for owners, admins, members, and billing contacts."
+      }
     },
     {
       "name": "route-map",
@@ -3097,7 +3541,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Standalone SVG map with animated route paths, waypoints, and progress indicator. For trade routes, voyages, migrations, delivery tracking."
+      }
     },
     {
       "name": "routing-assignment-panel",
@@ -3116,7 +3563,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Right-dock panel listing the agent slots an active route dispatches to."
+      }
     },
     {
       "name": "run-timeline",
@@ -3135,7 +3585,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Multi-lane execution timeline showing run phases over time, with optional cursor."
+      }
     },
     {
       "name": "runtime-overview-panel",
@@ -3154,7 +3607,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Top-of-dock summary tile grid for runtime health when no canvas object is selected."
+      }
     },
     {
       "name": "scope-selector",
@@ -3173,7 +3629,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Multi-level scope picker for nested environments, teams, and targets."
+      }
     },
     {
       "name": "scroll-area",
@@ -3192,7 +3651,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Custom scrollable area with styled scrollbars."
+      }
     },
     {
       "name": "search-bar",
@@ -3211,7 +3673,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Text search input with icon and clear functionality."
+      }
     },
     {
       "name": "search-dialog",
@@ -3230,7 +3695,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Full-screen search dialog with keyboard navigation."
+      }
     },
     {
       "name": "segmented-control",
@@ -3249,7 +3717,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Single-choice segmented selector for switching modes, views, or filters."
+      }
     },
     {
       "name": "select",
@@ -3268,7 +3739,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Dropdown select input for choosing from a list of options."
+      }
     },
     {
       "name": "selection-halo",
@@ -3287,7 +3761,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Local-user selection halo with corner handles + label slot for spatial canvases."
+      }
     },
     {
       "name": "selection-presence",
@@ -3306,7 +3783,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Dashed-border overlay marking what another user has selected on the canvas."
+      }
     },
     {
       "name": "separator",
@@ -3325,7 +3805,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Visual divider between content sections."
+      }
     },
     {
       "name": "severity-badge",
@@ -3344,7 +3827,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Operational severity label with tone variants and optional pulse for critical incidents."
+      }
     },
     {
       "name": "share-section",
@@ -3363,7 +3849,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Social sharing buttons and link copy section."
+      }
     },
     {
       "name": "sheet",
@@ -3382,7 +3871,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Slide-over panel from the edge of the screen."
+      }
     },
     {
       "name": "sidebar",
@@ -3401,7 +3893,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Collapsible sidebar navigation layout."
+      }
     },
     {
       "name": "sidebar-provider",
@@ -3420,7 +3915,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Context provider for managing sidebar open/close state."
+      }
     },
     {
       "name": "sidebar-toggle",
@@ -3440,7 +3938,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Responsive toggle button for opening and closing the sidebar."
+      }
     },
     {
       "name": "skeleton",
@@ -3459,7 +3960,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Placeholder loading animation for content."
+      }
     },
     {
       "name": "slider",
@@ -3478,7 +3982,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Range slider input for selecting numeric values."
+      }
     },
     {
       "name": "slideshow",
@@ -3497,7 +4004,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Step-through slideshow for presenting content sequentially."
+      }
     },
     {
       "name": "snap-guides",
@@ -3516,7 +4026,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Alignment guide overlay — dashed vertical and horizontal lines that surface during a drag."
+      }
     },
     {
       "name": "sparkline-grid",
@@ -3535,7 +4048,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "KPI grid of labeled value tiles each paired with a compact sparkline trend."
+      }
     },
     {
       "name": "spinner",
@@ -3554,7 +4070,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Animated loading spinner indicator."
+      }
     },
     {
       "name": "stat-card",
@@ -3573,7 +4092,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Headline KPI card for metrics, trends, and supporting context."
+      }
     },
     {
       "name": "state-badge-overlay",
@@ -3592,7 +4114,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "State chip pinned to a canvas object's corner — idle, queued, running, complete, failed, stopped."
+      }
     },
     {
       "name": "status-board",
@@ -3611,7 +4136,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Service health grid for surfacing infrastructure state, queue pressure, and incidents."
+      }
     },
     {
       "name": "status-indicator",
@@ -3630,7 +4158,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact status label with tone, variant, and activity dot options."
+      }
     },
     {
       "name": "step-by-step",
@@ -3649,7 +4180,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Numbered step guide with optional interactive completion tracking."
+      }
     },
     {
       "name": "step-navigation",
@@ -3668,7 +4202,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Navigation controls for stepping through multi-page content."
+      }
     },
     {
       "name": "stepper",
@@ -3687,7 +4224,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Sequenced steps with complete, current, and upcoming states."
+      }
     },
     {
       "name": "sticky-metric",
@@ -3706,7 +4246,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Pinned metric pill that sticks to a canvas object's corner."
+      }
     },
     {
       "name": "story-map",
@@ -3725,7 +4268,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Standalone SVG scroll-driven narrative map — IntersectionObserver tracks the active chapter and the map shifts to its center + zoom."
+      }
     },
     {
       "name": "subscription-card",
@@ -3744,7 +4290,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Subscription status and management card for plan, renewal, and usage details."
+      }
     },
     {
       "name": "table",
@@ -3763,7 +4312,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Styled data table with header, body, and footer sections."
+      }
     },
     {
       "name": "table-of-contents",
@@ -3782,7 +4334,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Auto-generated table of contents from page headings."
+      }
     },
     {
       "name": "table-of-contents-panel",
@@ -3801,7 +4356,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Side panel rendering a table of contents for page navigation."
+      }
     },
     {
       "name": "tabs",
@@ -3820,7 +4378,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Tabbed content panels with keyboard-accessible tab triggers."
+      }
     },
     {
       "name": "tags-input",
@@ -3839,7 +4400,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Keyboard-friendly tag editor for adding and removing string values."
+      }
     },
     {
       "name": "terminal",
@@ -3858,7 +4422,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Terminal-style display for command output."
+      }
     },
     {
       "name": "textarea",
@@ -3877,7 +4444,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Multi-line text input field."
+      }
     },
     {
       "name": "theme-provider",
@@ -3896,7 +4466,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Context provider for light/dark theme switching."
+      }
     },
     {
       "name": "theme-toggle",
@@ -3915,7 +4488,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Button to toggle between light and dark themes."
+      }
     },
     {
       "name": "thinking-block",
@@ -3935,7 +4511,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Collapsible block showing AI thinking/reasoning with streaming support."
+      }
     },
     {
       "name": "thread-bubble",
@@ -3954,7 +4533,10 @@
       ],
       "category": "utility",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Expanded discussion bubble for an anchored canvas comment thread."
+      }
     },
     {
       "name": "threshold-ring",
@@ -3973,7 +4555,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Compact ring gauge expressing how close a value is to a threshold."
+      }
     },
     {
       "name": "ticker-tape",
@@ -3992,7 +4577,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Marquee-style scrolling symbol tape with price and change badges."
+      }
     },
     {
       "name": "timeline",
@@ -4012,7 +4600,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Vertical or horizontal timeline of sequential events with completed/active/upcoming statuses and connector lines."
+      }
     },
     {
       "name": "timeline-scrubber",
@@ -4031,7 +4622,10 @@
       ],
       "category": "form",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Range slider for scrubbing through canvas state playback, with optional milestone ticks."
+      }
     },
     {
       "name": "tldr-section",
@@ -4050,7 +4644,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Summary section for quick content overview."
+      }
     },
     {
       "name": "toast",
@@ -4069,7 +4666,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Temporary notification messages with action support."
+      }
     },
     {
       "name": "toggle",
@@ -4088,7 +4688,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Two-state toggle button."
+      }
     },
     {
       "name": "toggle-group",
@@ -4107,7 +4710,10 @@
       ],
       "category": "core",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Group of toggle buttons for single or multiple selection."
+      }
     },
     {
       "name": "tooltip",
@@ -4126,7 +4732,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Informational popup displayed on hover or focus."
+      }
     },
     {
       "name": "top-bar",
@@ -4145,7 +4754,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Workspace header bar for titles, leading controls, centered navigation, and trailing actions."
+      }
     },
     {
       "name": "tour",
@@ -4164,7 +4776,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Guided onboarding flow for introducing content or interface patterns."
+      }
     },
     {
       "name": "transaction-list",
@@ -4183,7 +4798,10 @@
       ],
       "category": "billing",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Chronological credit/debit history with locale-aware currency formatting and a pinned subscription row."
+      }
     },
     {
       "name": "tree-view",
@@ -4202,7 +4820,10 @@
       ],
       "category": "data-display",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Hierarchical tree component for nested data with controlled state, single/multi-select, and keyboard navigation."
+      }
     },
     {
       "name": "tutorial-card",
@@ -4221,7 +4842,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Card for displaying tutorial previews with metadata."
+      }
     },
     {
       "name": "tutorial-complete",
@@ -4240,7 +4864,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Completion screen displayed when a tutorial is finished."
+      }
     },
     {
       "name": "tutorial-filters",
@@ -4259,7 +4886,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Filter controls for browsing tutorials by category or difficulty."
+      }
     },
     {
       "name": "tutorial-intro-content",
@@ -4278,7 +4908,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Introduction section for tutorial pages with overview and prerequisites."
+      }
     },
     {
       "name": "tutorial-mdx",
@@ -4297,7 +4930,10 @@
       ],
       "category": "learning",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "MDX renderer tailored for tutorial content with custom components."
+      }
     },
     {
       "name": "usage-breakdown",
@@ -4316,7 +4952,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Ranked resource consumption list with relative share and trend cues."
+      }
     },
     {
       "name": "video-embed",
@@ -4335,7 +4974,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Responsive video embed for YouTube and other providers."
+      }
     },
     {
       "name": "view-switcher",
@@ -4354,7 +4996,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "URL param-based toggle between named views with pill/tab styling."
+      }
     },
     {
       "name": "viewport-bookmarks",
@@ -4373,7 +5018,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Saved-view list for the canvas — pinned spatial locations with optional active state."
+      }
     },
     {
       "name": "wallet-card",
@@ -4392,7 +5040,10 @@
       ],
       "category": "content",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Credit balance display card for available, pending, and refresh details."
+      }
     },
     {
       "name": "watchlist",
@@ -4411,7 +5062,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Tracked-symbol list with price, change, and advancing/declining summary."
+      }
     },
     {
       "name": "workspace-switcher",
@@ -4430,7 +5084,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Segmented workspace picker for switching between canvas views and operational contexts."
+      }
     },
     {
       "name": "world-breadcrumbs",
@@ -4449,7 +5106,10 @@
       ],
       "category": "navigation",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Spatial trail showing the canvas's current location in a hierarchy of worlds, groups, and runs."
+      }
     },
     {
       "name": "world-clock-bar",
@@ -4468,7 +5128,10 @@
       ],
       "category": "data",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Multi-timezone display for follow-the-sun teams and operational handoffs."
+      }
     },
     {
       "name": "zoom-hud",
@@ -4488,7 +5151,10 @@
       ],
       "category": "overlay",
       "version": "0.2.1",
-      "stability": "stable"
+      "stability": "stable",
+      "descriptions": {
+        "en": "Zoom controls with current percentage, increment buttons, and reset action for canvas views."
+      }
     }
   ],
   "version": "0.2.1",
diff --git a/apps/registry/scripts/check-page-translations.ts b/apps/registry/scripts/check-page-translations.ts
new file mode 100644
index 00000000..9b6d08b8
--- /dev/null
+++ b/apps/registry/scripts/check-page-translations.ts
@@ -0,0 +1,46 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { defaultLocale, locales } from "../i18n/locales";
+
+const pagesDirectory = join(process.cwd(), "content", "pages");
+
+const slugs = readdirSync(pagesDirectory).filter((entry) => {
+  const fullPath = join(pagesDirectory, entry);
+  return statSync(fullPath).isDirectory();
+});
+
+let missingDefault = 0;
+let warnings = 0;
+
+for (const slug of slugs) {
+  const defaultPath = join(pagesDirectory, slug, `${defaultLocale}.mdx`);
+  if (!existsSync(defaultPath) || readFileSync(defaultPath, "utf8").trim() === "") {
+    console.error(`Missing required ${defaultLocale} MDX for ${slug}`);
+    missingDefault += 1;
+    continue;
+  }
+
+  for (const locale of locales) {
+    if (locale === defaultLocale) continue;
+
+    const translatedPath = join(pagesDirectory, slug, `${locale}.mdx`);
+    if (
+      !existsSync(translatedPath) ||
+      readFileSync(translatedPath, "utf8").trim() === ""
+    ) {
+      console.warn(
+        `Missing ${locale} MDX for ${slug}; ${defaultLocale} fallback will be used.`,
+      );
+      warnings += 1;
+    }
+  }
+}
+
+if (warnings > 0) {
+  console.warn(`${warnings} non-default translation warning(s).`);
+}
+
+if (missingDefault > 0) {
+  process.exitCode = 1;
+}
diff --git a/apps/registry/scripts/generate-component-metadata.ts b/apps/registry/scripts/generate-component-metadata.ts
index 7bc1fc85..f45768fa 100644
--- a/apps/registry/scripts/generate-component-metadata.ts
+++ b/apps/registry/scripts/generate-component-metadata.ts
@@ -31,6 +31,7 @@ const scriptDirectory = dirname(fileURLToPath(import.meta.url));
 type RegistryItem = {
   category?: string;
   description?: string;
+  descriptions?: Partial<Record<string, string>>;
   files: { path: string; type: string }[];
   name: string;
   title?: string;
@@ -50,6 +51,7 @@ type ComponentMetadata = {
   category: string;
   defaultStoryId: string;
   description: string;
+  descriptions?: Partial<Record<string, string>>;
   name: string;
   stories: StoryEntry[];
   title: string;
@@ -175,6 +177,7 @@ for (const item of registry.items) {
     category: item.category ?? "utility",
     defaultStoryId: entries.defaultStoryId,
     description: item.description ?? "",
+    descriptions: item.descriptions,
     name: item.name,
     stories: entries.stories,
     title: item.title ?? item.name,
diff --git a/apps/registry/scripts/inline-component-source.ts b/apps/registry/scripts/inline-component-source.ts
index 3d7acfcc..35423e62 100644
--- a/apps/registry/scripts/inline-component-source.ts
+++ b/apps/registry/scripts/inline-component-source.ts
@@ -100,6 +100,7 @@ type RegistryItem = {
   category?: string;
   dependencies?: string[];
   description?: string;
+  descriptions?: Partial<Record<string, string>>;
   examples?: UsageExample[];
   files: RegistryFile[];
   name: string;
@@ -230,6 +231,13 @@ for (const item of registry.items) {
   // No transitive registry pulls — @vllnt/ui covers all internals
   item.registryDependencies = [];
 
+  // Keep the canonical English description while making room for additive
+  // locale overlays such as /r/<name>.fr.json.
+  item.descriptions = {
+    ...(item.descriptions ?? {}),
+    en: item.description ?? item.descriptions?.en ?? "",
+  };
+
   // Ensure @vllnt/ui is in npm dependencies (preserve any other declared deps)
   const otherDeps = (item.dependencies ?? []).filter(
     (dep) => !dep.startsWith(`${PACKAGE_NAME}@`) && dep !== PACKAGE_NAME,
diff --git a/apps/registry/scripts/stamp-registry-metadata.ts b/apps/registry/scripts/stamp-registry-metadata.ts
index e04ea959..5790dee6 100644
--- a/apps/registry/scripts/stamp-registry-metadata.ts
+++ b/apps/registry/scripts/stamp-registry-metadata.ts
@@ -57,6 +57,7 @@ type RegistryItem = {
   examples?: UsageExample[];
   name: string;
   props?: PropDefinition[];
+  descriptions?: Partial<Record<string, string>>;
   version?: string;
   stability?: Stability;
   replacedBy?: string;
@@ -102,6 +103,11 @@ for (const item of registry.items) {
   } else {
     delete data.props;
   }
+  if (item.descriptions && Object.keys(item.descriptions).length > 0) {
+    data.descriptions = item.descriptions;
+  } else {
+    delete data.descriptions;
+  }
 
   writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
   stampedCount += 1;
diff --git a/apps/registry/types/registry.ts b/apps/registry/types/registry.ts
index b28e2856..63bec133 100644
--- a/apps/registry/types/registry.ts
+++ b/apps/registry/types/registry.ts
@@ -4,9 +4,13 @@ export type RegistryFile = {
 };
 
 export type ComponentCategory =
+  | "ai"
+  | "billing"
   | "content"
   | "core"
   | "data"
+  | "data-display"
+  | "educational"
   | "form"
   | "learning"
   | "navigation"
@@ -50,6 +54,7 @@ export type RegistryComponent = {
   category?: ComponentCategory;
   dependencies?: string[];
   description?: string;
+  descriptions?: Partial<Record<string, string>>;
   examples?: UsageExample[];
   files: RegistryFile[];
   name: string;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 40e57535..d456990d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -56,6 +56,9 @@ importers:
       next:
         specifier: '>=16.1.6'
         version: 16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      next-intl:
+        specifier: ^4.11.2
+        version: 4.11.2(next@16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)(typescript@5.9.3)
       react:
         specifier: ^19.2.0
         version: 19.2.4
@@ -1200,6 +1203,18 @@ packages:
   '@floating-ui/utils@0.2.10':
     resolution: {integrity: sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==}
 
+  '@formatjs/fast-memoize@3.1.5':
+    resolution: {integrity: sha512-KLi3fan6WnCHmigd9pmEEN8Hid0v4wiFBW576M/d07KMWYecf1CvyMI3n34vCmHT4AoVqG2n702kiHbXjzZX2A==}
+
+  '@formatjs/icu-messageformat-parser@3.5.8':
+    resolution: {integrity: sha512-uZLvzLFN7iV2l8cbDdROwgKGtdELeLI4bpnsuz1DnyscHDxn8TdDE0anHzcfjtWK66XYCllGLV3Mi3CYcEPg/g==}
+
+  '@formatjs/icu-skeleton-parser@2.1.8':
+    resolution: {integrity: sha512-iX5i0O15gPf69l1WqmLFYwn7wq53lauvytvWFnHamIfX/5Ta56gpFj6fdeHRcKTV58IhrKv8QOvWfTYZYm7f+g==}
+
+  '@formatjs/intl-localematcher@0.8.7':
+    resolution: {integrity: sha512-1R/ljfRKG1fUhKG4F0lUmrEKPkr/PlHqbgQ8xeYQYYunXu5/0+vbQeeVgGAgydp13Tq+S1X5Qjn6L90hijXjHg==}
+
   '@github-ui/storybook-addon-performance-panel@1.1.4':
     resolution: {integrity: sha512-clVeSoS1BM2z+nHffOXpnA1J034XALEDfJez6yg7TS7Clfn8eBjgw5FwLjfMvM+kWeG2nwfP6LujRMvJDqj+yg==}
     peerDependencies:
@@ -1676,6 +1691,88 @@ packages:
   '@open-draft/until@2.1.0':
     resolution: {integrity: sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg==}
 
+  '@parcel/watcher-android-arm64@2.5.6':
+    resolution: {integrity: sha512-YQxSS34tPF/6ZG7r/Ih9xy+kP/WwediEUsqmtf0cuCV5TPPKw/PQHRhueUo6JdeFJaqV3pyjm0GdYjZotbRt/A==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  '@parcel/watcher-darwin-arm64@2.5.6':
+    resolution: {integrity: sha512-Z2ZdrnwyXvvvdtRHLmM4knydIdU9adO3D4n/0cVipF3rRiwP+3/sfzpAwA/qKFL6i1ModaabkU7IbpeMBgiVEA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@parcel/watcher-darwin-x64@2.5.6':
+    resolution: {integrity: sha512-HgvOf3W9dhithcwOWX9uDZyn1lW9R+7tPZ4sug+NGrGIo4Rk1hAXLEbcH1TQSqxts0NYXXlOWqVpvS1SFS4fRg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@parcel/watcher-freebsd-x64@2.5.6':
+    resolution: {integrity: sha512-vJVi8yd/qzJxEKHkeemh7w3YAn6RJCtYlE4HPMoVnCpIXEzSrxErBW5SJBgKLbXU3WdIpkjBTeUNtyBVn8TRng==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@parcel/watcher-linux-arm-glibc@2.5.6':
+    resolution: {integrity: sha512-9JiYfB6h6BgV50CCfasfLf/uvOcJskMSwcdH1PHH9rvS1IrNy8zad6IUVPVUfmXr+u+Km9IxcfMLzgdOudz9EQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@parcel/watcher-linux-arm-musl@2.5.6':
+    resolution: {integrity: sha512-Ve3gUCG57nuUUSyjBq/MAM0CzArtuIOxsBdQ+ftz6ho8n7s1i9E1Nmk/xmP323r2YL0SONs1EuwqBp2u1k5fxg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  '@parcel/watcher-linux-arm64-glibc@2.5.6':
+    resolution: {integrity: sha512-f2g/DT3NhGPdBmMWYoxixqYr3v/UXcmLOYy16Bx0TM20Tchduwr4EaCbmxh1321TABqPGDpS8D/ggOTaljijOA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@parcel/watcher-linux-arm64-musl@2.5.6':
+    resolution: {integrity: sha512-qb6naMDGlbCwdhLj6hgoVKJl2odL34z2sqkC7Z6kzir8b5W65WYDpLB6R06KabvZdgoHI/zxke4b3zR0wAbDTA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@parcel/watcher-linux-x64-glibc@2.5.6':
+    resolution: {integrity: sha512-kbT5wvNQlx7NaGjzPFu8nVIW1rWqV780O7ZtkjuWaPUgpv2NMFpjYERVi0UYj1msZNyCzGlaCWEtzc+exjMGbQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@parcel/watcher-linux-x64-musl@2.5.6':
+    resolution: {integrity: sha512-1JRFeC+h7RdXwldHzTsmdtYR/Ku8SylLgTU/reMuqdVD7CtLwf0VR1FqeprZ0eHQkO0vqsbvFLXUmYm/uNKJBg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  '@parcel/watcher-win32-arm64@2.5.6':
+    resolution: {integrity: sha512-3ukyebjc6eGlw9yRt678DxVF7rjXatWiHvTXqphZLvo7aC5NdEgFufVwjFfY51ijYEWpXbqF5jtrK275z52D4Q==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@parcel/watcher-win32-ia32@2.5.6':
+    resolution: {integrity: sha512-k35yLp1ZMwwee3Ez/pxBi5cf4AoBKYXj00CZ80jUz5h8prpiaQsiRPKQMxoLstNuqe2vR4RNPEAEcjEFzhEz/g==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@parcel/watcher-win32-x64@2.5.6':
+    resolution: {integrity: sha512-hbQlYcCq5dlAX9Qx+kFb0FHue6vbjlf0FrNzSKdYK2APUf7tGfGxQCk2ihEREmbR6ZMc0MVAD5RIX/41gpUzTw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  '@parcel/watcher@2.5.6':
+    resolution: {integrity: sha512-tmmZ3lQxAe/k/+rNnXQRawJ4NjxO2hqiOLTHvWchtGZULp4RyFeh6aU4XdOYBFe2KE1oShQTv4AblOs2iOrNnQ==}
+    engines: {node: '>= 10.0.0'}
+
   '@pkgjs/parseargs@0.11.0':
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
@@ -2434,6 +2531,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@schummar/icu-type-parser@1.21.5':
+    resolution: {integrity: sha512-bXHSaW5jRTmke9Vd0h5P7BtWZG9Znqb8gSDxZnxaGSJnGwPLDPfS+3g0BKzeWqzgZPsIVZkM7m2tbo18cm5HBw==}
+
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
@@ -4845,6 +4945,9 @@ packages:
     resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
     engines: {node: '>=0.10.0'}
 
+  icu-minify@4.11.2:
+    resolution: {integrity: sha512-vZRLaDpZiFNBXZ1tUtekAf4WXl/Tow/BoWx8MWQqQpGckXf11opUXYzG+mXUj+OsDuv9Zz+etLfUWwxaMnYnzw==}
+
   ignore@5.3.2:
     resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
     engines: {node: '>= 4'}
@@ -4897,6 +5000,9 @@ packages:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
 
+  intl-messageformat@11.2.5:
+    resolution: {integrity: sha512-zaROHiUsnlSFXVypU54AsQuAm3DLmmSH8KfDhiUuG1XZ9NTQ4o3xlxIJYVNmeWAklyp3CWg0lhexNUnee8PsYQ==}
+
   ip-address@10.0.1:
     resolution: {integrity: sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==}
     engines: {node: '>= 12'}
@@ -5780,6 +5886,19 @@ packages:
   neo-async@2.6.2:
     resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==}
 
+  next-intl-swc-plugin-extractor@4.11.2:
+    resolution: {integrity: sha512-1TQGAjkrV6wl4gqwabCFLAAvkAvaBs87ByitYlu01bzWpD/pT/am1JYmpQCIdAMzzpF0hLtj3/xSgVWHjj9fmw==}
+
+  next-intl@4.11.2:
+    resolution: {integrity: sha512-96GZVgiGF5zzEbKaml3lLVRVR9jIZiLsZCeezjq3RMcW4wrWr4v85SZm++/uutsS9IqsJ7rMM5KGYXqvVS8c/Q==}
+    peerDependencies:
+      next: '>=16.1.6'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || >=19.0.0-rc <19.0.0 || ^19.0.0
+      typescript: '*'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   next-themes@0.4.6:
     resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
     peerDependencies:
@@ -5811,6 +5930,9 @@ packages:
     resolution: {integrity: sha512-3yZ1vfGKOcv0dyyhUeqA0Qa6RsQ4SfUnL6o2IWR4sVg8kdnJo48XTWbMLdtnfiZTbCUdsMttNwyJcihEdGCZBw==}
     engines: {node: '>=16', npm: '>=8'}
 
+  node-addon-api@7.1.1:
+    resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
+
   node-domexception@1.0.0:
     resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
     engines: {node: '>=10.5.0'}
@@ -6080,6 +6202,9 @@ packages:
     resolution: {integrity: sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==}
     engines: {node: '>=4'}
 
+  po-parser@2.1.1:
+    resolution: {integrity: sha512-ECF4zHLbUItpUgE3OTtLKlPjeBN+fKEczj2zYjDfCGOzicNs0GK3Vg2IoAYwx7LH/XYw43fZQP6xnZ4TkNxSLQ==}
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -6128,6 +6253,10 @@ packages:
     resolution: {integrity: sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==}
     engines: {node: '>=4'}
 
+  postcss-selector-parser@7.1.1:
+    resolution: {integrity: sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==}
+    engines: {node: '>=4'}
+
   postcss-value-parser@4.2.0:
     resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
 
@@ -6139,6 +6268,10 @@ packages:
     resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  powershell-utils@0.1.0:
+    resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
+    engines: {node: '>=20'}
+
   prelude-ls@1.2.1:
     resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
     engines: {node: '>= 0.8.0'}
@@ -7124,6 +7257,11 @@ packages:
       '@types/react':
         optional: true
 
+  use-intl@4.11.2:
+    resolution: {integrity: sha512-JsheePHtkp39cDLbIbFr5Ta8jcPJM8g0qc5AVlTwsCtg/G98hqcCdFtEuDbZadK+8qSor6VLFTSNsUyZ0Zietw==}
+    peerDependencies:
+      react: ^17.0.0 || ^18.0.0 || >=19.0.0-rc <19.0.0 || ^19.0.0
+
   use-sidecar@1.1.3:
     resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==}
     engines: {node: '>=10'}
@@ -7144,6 +7282,7 @@ packages:
 
   uuid@8.3.2:
     resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   v8-to-istanbul@9.3.0:
@@ -7420,6 +7559,10 @@ packages:
     resolution: {integrity: sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==}
     engines: {node: '>=18'}
 
+  wsl-utils@0.3.1:
+    resolution: {integrity: sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg==}
+    engines: {node: '>=20'}
+
   xml-name-validator@5.0.0:
     resolution: {integrity: sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==}
     engines: {node: '>=18'}
@@ -8197,6 +8340,18 @@ snapshots:
 
   '@floating-ui/utils@0.2.10': {}
 
+  '@formatjs/fast-memoize@3.1.5': {}
+
+  '@formatjs/icu-messageformat-parser@3.5.8':
+    dependencies:
+      '@formatjs/icu-skeleton-parser': 2.1.8
+
+  '@formatjs/icu-skeleton-parser@2.1.8': {}
+
+  '@formatjs/intl-localematcher@0.8.7':
+    dependencies:
+      '@formatjs/fast-memoize': 3.1.5
+
   '@github-ui/storybook-addon-performance-panel@1.1.4(@storybook/icons@2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@storybook/react@10.2.17(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.17(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3))(react@19.2.4)(storybook@10.2.17(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))':
     dependencies:
       '@storybook/icons': 2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -8734,6 +8889,66 @@ snapshots:
 
   '@open-draft/until@2.1.0': {}
 
+  '@parcel/watcher-android-arm64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-darwin-arm64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-darwin-x64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-freebsd-x64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm-glibc@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm-musl@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm64-glibc@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-arm64-musl@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-x64-glibc@2.5.6':
+    optional: true
+
+  '@parcel/watcher-linux-x64-musl@2.5.6':
+    optional: true
+
+  '@parcel/watcher-win32-arm64@2.5.6':
+    optional: true
+
+  '@parcel/watcher-win32-ia32@2.5.6':
+    optional: true
+
+  '@parcel/watcher-win32-x64@2.5.6':
+    optional: true
+
+  '@parcel/watcher@2.5.6':
+    dependencies:
+      detect-libc: 2.1.2
+      is-glob: 4.0.3
+      node-addon-api: 7.1.1
+      picomatch: 4.0.3
+    optionalDependencies:
+      '@parcel/watcher-android-arm64': 2.5.6
+      '@parcel/watcher-darwin-arm64': 2.5.6
+      '@parcel/watcher-darwin-x64': 2.5.6
+      '@parcel/watcher-freebsd-x64': 2.5.6
+      '@parcel/watcher-linux-arm-glibc': 2.5.6
+      '@parcel/watcher-linux-arm-musl': 2.5.6
+      '@parcel/watcher-linux-arm64-glibc': 2.5.6
+      '@parcel/watcher-linux-arm64-musl': 2.5.6
+      '@parcel/watcher-linux-x64-glibc': 2.5.6
+      '@parcel/watcher-linux-x64-musl': 2.5.6
+      '@parcel/watcher-win32-arm64': 2.5.6
+      '@parcel/watcher-win32-ia32': 2.5.6
+      '@parcel/watcher-win32-x64': 2.5.6
+
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
@@ -9493,6 +9708,8 @@ snapshots:
   '@rollup/rollup-win32-x64-msvc@4.59.0':
     optional: true
 
+  '@schummar/icu-type-parser@1.21.5': {}
+
   '@sec-ant/readable-stream@0.4.1': {}
 
   '@sideway/address@4.1.5':
@@ -11062,8 +11279,7 @@ snapshots:
 
   dequal@2.0.3: {}
 
-  detect-libc@2.1.2:
-    optional: true
+  detect-libc@2.1.2: {}
 
   detect-newline@3.1.0: {}
 
@@ -12240,6 +12456,10 @@ snapshots:
     dependencies:
       safer-buffer: 2.1.2
 
+  icu-minify@4.11.2:
+    dependencies:
+      '@formatjs/icu-messageformat-parser': 3.5.8
+
   ignore@5.3.2: {}
 
   ignore@7.0.5: {}
@@ -12282,6 +12502,11 @@ snapshots:
       hasown: 2.0.2
       side-channel: 1.1.0
 
+  intl-messageformat@11.2.5:
+    dependencies:
+      '@formatjs/fast-memoize': 3.1.5
+      '@formatjs/icu-messageformat-parser': 3.5.8
+
   ip-address@10.0.1: {}
 
   ipaddr.js@1.9.1: {}
@@ -13617,6 +13842,25 @@ snapshots:
 
   neo-async@2.6.2: {}
 
+  next-intl-swc-plugin-extractor@4.11.2: {}
+
+  next-intl@4.11.2(next@16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)(typescript@5.9.3):
+    dependencies:
+      '@formatjs/intl-localematcher': 0.8.7
+      '@parcel/watcher': 2.5.6
+      '@swc/core': 1.15.18
+      icu-minify: 4.11.2
+      negotiator: 1.0.0
+      next: 16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      next-intl-swc-plugin-extractor: 4.11.2
+      po-parser: 2.1.1
+      react: 19.2.4
+      use-intl: 4.11.2(react@19.2.4)
+    optionalDependencies:
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - '@swc/helpers'
+
   next-themes@0.4.6(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       react: 19.2.4
@@ -13648,6 +13892,8 @@ snapshots:
 
   no-cliches@0.3.6: {}
 
+  node-addon-api@7.1.1: {}
+
   node-domexception@1.0.0: {}
 
   node-fetch@3.3.2:
@@ -13935,6 +14181,8 @@ snapshots:
 
   pluralize@8.0.0: {}
 
+  po-parser@2.1.1: {}
+
   possible-typed-array-names@1.1.0: {}
 
   postcss-import@15.1.0(postcss@8.5.6):
@@ -13972,6 +14220,11 @@ snapshots:
       cssesc: 3.0.0
       util-deprecate: 1.0.2
 
+  postcss-selector-parser@7.1.1:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
   postcss-value-parser@4.2.0: {}
 
   postcss@8.4.31:
@@ -13986,6 +14239,8 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  powershell-utils@0.1.0: {}
+
   prelude-ls@1.2.1: {}
 
   prettier-linter-helpers@1.0.1:
@@ -14519,6 +14774,7 @@ snapshots:
       node-fetch: 3.3.2
       ora: 8.2.0
       postcss: 8.5.6
+      postcss-selector-parser: 7.1.1
       prompts: 2.4.2
       recast: 0.23.11
       stringify-object: 5.0.0
@@ -15245,6 +15501,14 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.13
 
+  use-intl@4.11.2(react@19.2.4):
+    dependencies:
+      '@formatjs/fast-memoize': 3.1.5
+      '@schummar/icu-type-parser': 1.21.5
+      icu-minify: 4.11.2
+      intl-messageformat: 11.2.5
+      react: 19.2.4
+
   use-sidecar@1.1.3(@types/react@19.2.13)(react@19.2.4):
     dependencies:
       detect-node-es: 1.1.0
@@ -15515,6 +15779,11 @@ snapshots:
     dependencies:
       is-wsl: 3.1.1
 
+  wsl-utils@0.3.1:
+    dependencies:
+      is-wsl: 3.1.1
+      powershell-utils: 0.1.0
+
   xml-name-validator@5.0.0: {}
 
   xml@1.0.1: {}

From d66a08c69581cfc3ff69cd0213461890be0c4bc9 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 14 May 2026 16:04:30 +0200
Subject: [PATCH 2/2] fix(registry): localize comparison routes

---
 apps/registry/app/[locale]/vs/page.tsx        |  86 +++--
 apps/registry/app/[locale]/vs/shadcn/page.tsx | 294 ++++++++++++++----
 2 files changed, 302 insertions(+), 78 deletions(-)

diff --git a/apps/registry/app/[locale]/vs/page.tsx b/apps/registry/app/[locale]/vs/page.tsx
index d4180fb2..82907a24 100644
--- a/apps/registry/app/[locale]/vs/page.tsx
+++ b/apps/registry/app/[locale]/vs/page.tsx
@@ -10,26 +10,14 @@ type Props = {
   params: Promise<{ locale: Locale }>;
 };
 
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { locale } = await params;
-
-  return {
-    alternates: {
-      canonical: canonical("/vs", locale),
-      languages: languageAlternates("/vs"),
-    },
-    description:
-      "Honest, evidence-based comparison of VLLNT UI vs shadcn/ui, Radix UI, HeadlessUI, and NextUI.",
-    title: "VLLNT UI vs · Comparisons",
-  };
-}
-
-const COMPARISONS: readonly {
+type Comparison = {
   readonly available: boolean;
   readonly name: string;
   readonly slug: string;
   readonly tagline: string;
-}[] = [
+};
+
+const ENGLISH_COMPARISONS: readonly Comparison[] = [
   {
     available: true,
     name: "shadcn/ui",
@@ -57,24 +45,77 @@ const COMPARISONS: readonly {
   },
 ];
 
+const FRENCH_COMPARISONS: readonly Comparison[] = [
+  {
+    available: true,
+    name: "shadcn/ui",
+    slug: "shadcn",
+    tagline:
+      "Le plus proche parent. Même format de registre, avec un nombre de composants et une surface agent différents.",
+  },
+  {
+    available: false,
+    name: "Radix UI",
+    slug: "radix",
+    tagline:
+      "Primitives accessibles — VLLNT UI est construit au-dessus d’elles.",
+  },
+  {
+    available: false,
+    name: "HeadlessUI",
+    slug: "headless-ui",
+    tagline: "Primitives de Tailwind Labs — un écosystème différent.",
+  },
+  {
+    available: false,
+    name: "NextUI",
+    slug: "nextui",
+    tagline: "Bibliothèque de composants avec son propre langage visuel.",
+  },
+];
+
+function getComparisons(locale: Locale): readonly Comparison[] {
+  return locale === "fr" ? FRENCH_COMPARISONS : ENGLISH_COMPARISONS;
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const isFrench = locale === "fr";
+
+  return {
+    alternates: {
+      canonical: canonical("/vs", locale),
+      languages: languageAlternates("/vs"),
+    },
+    description: isFrench
+      ? "Comparaison honnête et factuelle de VLLNT UI face à shadcn/ui, Radix UI, HeadlessUI et NextUI."
+      : "Honest, evidence-based comparison of VLLNT UI vs shadcn/ui, Radix UI, HeadlessUI, and NextUI.",
+    title: isFrench ? "VLLNT UI face aux autres" : "VLLNT UI vs · Comparisons",
+  };
+}
+
 export default async function VsIndexPage({ params }: Props) {
   const { locale } = await params;
   setRequestLocale(locale);
+  const isFrench = locale === "fr";
+  const comparisons = getComparisons(locale);
 
   return (
     <>
       <Sidebar sections={getSidebarSections(undefined, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto max-w-3xl px-4 py-16 lg:px-8">
-          <h1 className="text-4xl font-semibold mb-3">VLLNT UI vs the rest</h1>
+          <h1 className="text-4xl font-semibold mb-3">
+            {isFrench ? "VLLNT UI face aux autres" : "VLLNT UI vs the rest"}
+          </h1>
           <p className="text-muted-foreground text-lg mb-10">
-            Honest comparisons. We call out where alternatives are stronger,
-            where VLLNT UI fits better, and where the gap is small enough to not
-            matter.
+            {isFrench
+              ? "Des comparaisons honnêtes. Nous indiquons où les alternatives sont plus fortes, où VLLNT UI s’intègre mieux et où l’écart est trop faible pour compter."
+              : "Honest comparisons. We call out where alternatives are stronger, where VLLNT UI fits better, and where the gap is small enough to not matter."}
           </p>
 
           <ul className="space-y-3">
-            {COMPARISONS.map((entry) =>
+            {comparisons.map((entry) =>
               entry.available ? (
                 <li key={entry.slug}>
                   <Link
@@ -98,7 +139,8 @@ export default async function VsIndexPage({ params }: Props) {
                     VLLNT UI vs {entry.name}
                   </p>
                   <p className="mt-1 text-sm text-muted-foreground">
-                    {entry.tagline}. Page coming soon.
+                    {entry.tagline}.{" "}
+                    {isFrench ? "Page à venir." : "Page coming soon."}
                   </p>
                 </li>
               ),
diff --git a/apps/registry/app/[locale]/vs/shadcn/page.tsx b/apps/registry/app/[locale]/vs/shadcn/page.tsx
index 52945497..7c25e849 100644
--- a/apps/registry/app/[locale]/vs/shadcn/page.tsx
+++ b/apps/registry/app/[locale]/vs/shadcn/page.tsx
@@ -11,20 +11,6 @@ type Props = {
   params: Promise<{ locale: Locale }>;
 };
 
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { locale } = await params;
-
-  return {
-    alternates: {
-      canonical: canonical("/vs/shadcn", locale),
-      languages: languageAlternates("/vs/shadcn"),
-    },
-    description:
-      "VLLNT UI vs shadcn/ui - registry format, component count, agent surface, theming, accessibility. Honest comparison.",
-    title: "VLLNT UI vs shadcn/ui",
-  };
-}
-
 type Row = {
   readonly attribute: string;
   readonly shadcn: string;
@@ -32,13 +18,122 @@ type Row = {
   readonly winner?: "even" | "shadcn" | "vllnt";
 };
 
-export default async function VsShadcnPage({ params }: Props) {
-  const { locale } = await params;
-  setRequestLocale(locale);
-  const componentCount = getComponentCount();
-  const version = getLibraryVersion();
+function getRows(locale: Locale, componentCount: number): readonly Row[] {
+  if (locale === "fr") {
+    return [
+      {
+        attribute: "Nombre de composants",
+        shadcn: "~50 composants",
+        vllnt: `${componentCount} composants`,
+        winner: "vllnt",
+      },
+      {
+        attribute: "Modèle d’installation",
+        shadcn: "CLI shadcn connecté à ui.shadcn.com/r",
+        vllnt: "CLI shadcn connecté à /r/<name>.json",
+        winner: "even",
+      },
+      {
+        attribute: "Vous possédez le code source après installation",
+        shadcn: "Oui",
+        vllnt: "Oui",
+        winner: "even",
+      },
+      {
+        attribute: "Résolution des composants frères",
+        shadcn: "Tout le code source est inclus dans chaque composant",
+        vllnt:
+          "Hybride : source feuille + dépendance paire @vllnt/ui pour les composants frères",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Index agent /llms.txt",
+        shadcn: "Non",
+        vllnt: "Oui — conforme à llmstxt.org",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Serveur MCP",
+        shadcn: "Non",
+        vllnt: "Oui — ui.vllnt.ai/mcp (outils search/get/list)",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Schéma a11y par composant dans le JSON",
+        shadcn: "Non",
+        vllnt: "Oui — clavier, rôles ARIA, modèle de focus",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Exemples par composant dans le JSON",
+        shadcn: "Non",
+        vllnt: "Oui — code structuré en données, lisible par les agents",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Schéma de props par composant dans le JSON",
+        shadcn: "Non",
+        vllnt: "Oui — format inspiré de TSDoc",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Version + stabilité par composant",
+        shadcn: "Non",
+        vllnt: "Oui (stable / beta / experimental / deprecated)",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Theming",
+        shadcn: "Variables CSS",
+        vllnt: "Variables CSS + design tokens (DESIGN.md)",
+        winner: "vllnt",
+      },
+      {
+        attribute: "Primitives d’accessibilité",
+        shadcn: "Radix UI",
+        vllnt: "Radix UI",
+        winner: "even",
+      },
+      {
+        attribute: "Système de variantes",
+        shadcn: "CVA",
+        vllnt: "CVA",
+        winner: "even",
+      },
+      {
+        attribute: "Taille de communauté",
+        shadcn: "Massive — des millions d’installations",
+        vllnt: "Plus petite, en croissance",
+        winner: "shadcn",
+      },
+      {
+        attribute: "Reconnaissance du namespace",
+        shadcn: "shadcn (standard du secteur)",
+        vllnt: "@vllnt/ui (plus récent)",
+        winner: "shadcn",
+      },
+      {
+        attribute: "Tutoriels + contenu",
+        shadcn: "Très riche — innombrables vidéos, articles et cours",
+        vllnt: "Limité (projet jeune)",
+        winner: "shadcn",
+      },
+      {
+        attribute: "Templates / starters",
+        shadcn: "Nombreux templates officiels et communautaires",
+        vllnt: "À venir",
+        winner: "shadcn",
+      },
+      {
+        attribute: "Licence",
+        shadcn: "MIT",
+        vllnt: "MIT",
+        winner: "even",
+      },
+    ];
+  }
 
-  const rows: readonly Row[] = [
+  return [
     {
       attribute: "Component count",
       shadcn: "~50 components",
@@ -148,6 +243,31 @@ export default async function VsShadcnPage({ params }: Props) {
       winner: "even",
     },
   ];
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const isFrench = locale === "fr";
+
+  return {
+    alternates: {
+      canonical: canonical("/vs/shadcn", locale),
+      languages: languageAlternates("/vs/shadcn"),
+    },
+    description: isFrench
+      ? "VLLNT UI face à shadcn/ui : format de registre, nombre de composants, surface agent, theming et accessibilité. Comparaison honnête."
+      : "VLLNT UI vs shadcn/ui - registry format, component count, agent surface, theming, accessibility. Honest comparison.",
+    title: isFrench ? "VLLNT UI face à shadcn/ui" : "VLLNT UI vs shadcn/ui",
+  };
+}
+
+export default async function VsShadcnPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  const isFrench = locale === "fr";
+  const componentCount = getComponentCount();
+  const version = getLibraryVersion();
+  const rows = getRows(locale, componentCount);
 
   return (
     <>
@@ -155,33 +275,64 @@ export default async function VsShadcnPage({ params }: Props) {
       <main className="flex-1 overflow-y-auto bg-background">
         <div className="container mx-auto max-w-4xl px-4 py-16 lg:px-8">
           <p className="text-sm uppercase tracking-wide text-muted-foreground">
-            Comparison · v{version}
+            {isFrench
+              ? `Comparaison · v${version}`
+              : `Comparison · v${version}`}
           </p>
-          <h1 className="mt-2 text-4xl font-semibold">VLLNT UI vs shadcn/ui</h1>
+          <h1 className="mt-2 text-4xl font-semibold">
+            {isFrench ? "VLLNT UI face à shadcn/ui" : "VLLNT UI vs shadcn/ui"}
+          </h1>
 
           <div className="prose prose-lg dark:prose-invert mt-6 max-w-none">
-            <h2>TLDR</h2>
-            <p>
-              shadcn/ui is the industry standard. VLLNT UI is a younger sibling
-              that takes the same registry idea further: more components, an
-              agent-first surface (<code>/llms.txt</code>, <code>/mcp</code>,
-              richer JSON descriptors), and a hybrid install model that dedupes
-              shared primitives via <code>@vllnt/ui</code>.
-            </p>
-            <p>
-              If you want maximum community signal and the largest pool of
-              third-party tutorials and templates, shadcn/ui wins. If you want
-              the broadest curated component set and a registry that AI agents
-              can read directly, VLLNT UI wins.
-            </p>
+            <h2>{isFrench ? "Résumé" : "TLDR"}</h2>
+            {isFrench ? (
+              <>
+                <p>
+                  shadcn/ui est le standard du secteur. VLLNT UI est un parent
+                  plus jeune qui pousse la même idée de registre plus loin :
+                  plus de composants, une surface pensée pour les agents
+                  (/llms.txt, /mcp, des descripteurs JSON plus riches) et un
+                  modèle d’installation hybride qui déduplique les primitives
+                  partagées via @vllnt/ui.
+                </p>
+                <p>
+                  Si vous cherchez le maximum de signal communautaire et le plus
+                  grand nombre de tutoriels et templates tiers, shadcn/ui gagne.
+                  Si vous voulez le catalogue de composants le plus large et un
+                  registre directement lisible par des agents IA, VLLNT UI
+                  gagne.
+                </p>
+              </>
+            ) : (
+              <>
+                <p>
+                  shadcn/ui is the industry standard. VLLNT UI is a younger
+                  sibling that takes the same registry idea further: more
+                  components, an agent-first surface (<code>/llms.txt</code>,{" "}
+                  <code>/mcp</code>, richer JSON descriptors), and a hybrid
+                  install model that dedupes shared primitives via{" "}
+                  <code>@vllnt/ui</code>.
+                </p>
+                <p>
+                  If you want maximum community signal and the largest pool of
+                  third-party tutorials and templates, shadcn/ui wins. If you
+                  want the broadest curated component set and a registry that AI
+                  agents can read directly, VLLNT UI wins.
+                </p>
+              </>
+            )}
           </div>
 
-          <h2 className="mt-12 text-2xl font-semibold">Side-by-side</h2>
+          <h2 className="mt-12 text-2xl font-semibold">
+            {isFrench ? "Côte à côte" : "Side-by-side"}
+          </h2>
           <div className="mt-4 overflow-x-auto rounded-lg border border-border">
             <table className="w-full text-sm">
               <thead className="bg-muted">
                 <tr>
-                  <th className="p-3 text-left font-semibold">Attribute</th>
+                  <th className="p-3 text-left font-semibold">
+                    {isFrench ? "Critère" : "Attribute"}
+                  </th>
                   <th className="p-3 text-left font-semibold">VLLNT UI</th>
                   <th className="p-3 text-left font-semibold">shadcn/ui</th>
                 </tr>
@@ -211,24 +362,55 @@ export default async function VsShadcnPage({ params }: Props) {
           </div>
 
           <div className="prose prose-lg dark:prose-invert mt-12 max-w-none">
-            <h2>When to pick which</h2>
-            <p>
-              <strong>Pick shadcn/ui</strong> when you want the most-validated
-              choice, need a large pool of tutorials, or are building something
-              that benefits from being &ldquo;just shadcn&rdquo;.
-            </p>
-            <p>
-              <strong>Pick VLLNT UI</strong> when you need components beyond the
-              shadcn core (timelines, maps, AI compounds, runtime overlays,
-              canvas primitives), when AI agents are part of your authoring
-              flow, or when you want the registry data structured enough to
-              query programmatically.
-            </p>
-            <p>
-              The honest answer: many projects use both. shadcn/ui as the
-              baseline, VLLNT UI for the families shadcn doesn&rsquo;t cover.
-              Same install model: they coexist cleanly.
-            </p>
+            <h2>
+              {isFrench
+                ? "Quand choisir l’un ou l’autre"
+                : "When to pick which"}
+            </h2>
+            {isFrench ? (
+              <>
+                <p>
+                  <strong>Choisissez shadcn/ui</strong> si vous voulez l’option
+                  la plus éprouvée, si vous avez besoin d’un grand volume de
+                  tutoriels, ou si votre projet gagne à rester « juste shadcn ».
+                </p>
+                <p>
+                  <strong>Choisissez VLLNT UI</strong> si vous avez besoin de
+                  composants au-delà du cœur shadcn (timelines, cartes,
+                  composants IA, overlays runtime, primitives canvas), si les
+                  agents IA font partie de votre flux d’authoring, ou si vous
+                  voulez des données de registre assez structurées pour être
+                  interrogées par programme.
+                </p>
+                <p>
+                  La réponse honnête : beaucoup de projets utilisent les deux.
+                  shadcn/ui comme base, VLLNT UI pour les familles que shadcn ne
+                  couvre pas. Même modèle d’installation : ils coexistent
+                  proprement.
+                </p>
+              </>
+            ) : (
+              <>
+                <p>
+                  <strong>Pick shadcn/ui</strong> when you want the
+                  most-validated choice, need a large pool of tutorials, or are
+                  building something that benefits from being &ldquo;just
+                  shadcn&rdquo;.
+                </p>
+                <p>
+                  <strong>Pick VLLNT UI</strong> when you need components beyond
+                  the shadcn core (timelines, maps, AI compounds, runtime
+                  overlays, canvas primitives), when AI agents are part of your
+                  authoring flow, or when you want the registry data structured
+                  enough to query programmatically.
+                </p>
+                <p>
+                  The honest answer: many projects use both. shadcn/ui as the
+                  baseline, VLLNT UI for the families shadcn doesn&rsquo;t
+                  cover. Same install model: they coexist cleanly.
+                </p>
+              </>
+            )}
           </div>
         </div>
       </main>