hd-garden 0.6.1 → 0.8.0

package/app/components/GardenDocsNav.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import Link from "next/link";
+import { BookOpenText, CaretRight, List, X } from "@phosphor-icons/react";
+import {
+  COMPONENT_BADGE,
+  groupHandbookDocs,
+  HANDBOOK_SECTIONS,
+  HANDBOOK_UI,
+  NAV_SHORT_TITLE,
+  handbookPath,
+  sectionTitle,
+  type GardenDocNavItem,
+  type HandbookLang,
+} from "../lib/garden-docs-meta";
+import { siteHref } from "../lib/site-href";
+
+export function GardenDocsNav({
+  docs,
+  currentPath = "",
+  lang = "zh",
+}: {
+  docs: GardenDocNavItem[];
+  currentPath?: string;
+  lang?: HandbookLang;
+}) {
+  const t = HANDBOOK_UI[lang];
+  const groups = groupHandbookDocs(docs);
+  const currentDoc = docs.find((doc) => doc.path === currentPath);
+  const currentSection = groups.find((group) =>
+    group.items.some((item) => item.path === currentPath),
+  );
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const drawerId = useId();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const restoreFocusRef = useRef(false);
+
+  const closeMobile = useCallback((restoreFocus = false) => {
+    restoreFocusRef.current = restoreFocus;
+    setMobileOpen(false);
+  }, []);
+
+  useEffect(() => {
+    if (mobileOpen || !restoreFocusRef.current) return;
+    restoreFocusRef.current = false;
+    triggerRef.current?.focus({ preventScroll: true });
+  }, [mobileOpen]);
+
+  useEffect(() => {
+    if (!mobileOpen) return;
+    const query = window.matchMedia("(max-width: 1080px)");
+    if (!query.matches) return;
+    const previousOverflow = document.body.style.overflow;
+    const focusFrame = window.requestAnimationFrame(() => {
+      closeRef.current?.focus({ preventScroll: true });
+    });
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") closeMobile(true);
+    };
+    const onChange = () => {
+      if (!query.matches) setMobileOpen(false);
+    };
+    document.body.style.overflow = "hidden";
+    window.addEventListener("keydown", onKeyDown);
+    query.addEventListener("change", onChange);
+    return () => {
+      window.cancelAnimationFrame(focusFrame);
+      document.body.style.overflow = previousOverflow;
+      window.removeEventListener("keydown", onKeyDown);
+      query.removeEventListener("change", onChange);
+    };
+  }, [closeMobile, mobileOpen]);
+
+  const isOverview = currentPath === "";
+
+  return (
+    <>
+      <div className="gdoc-mobile-bar" aria-label={t.mobileBar}>
+        <button
+          ref={triggerRef}
+          type="button"
+          className="gdoc-mobile-trigger"
+          aria-controls={drawerId}
+          aria-expanded={mobileOpen}
+          onClick={() => setMobileOpen(true)}
+        >
+          <List size={16} weight="bold" aria-hidden="true" />
+          <span>{t.sidebarShort}</span>
+        </button>
+        <a
+          className="gdoc-nojs-trigger"
+          id={`${drawerId}-open`}
+          href={`#${drawerId}`}
+          aria-label={t.openSidebar}
+        >
+          <List size={16} weight="bold" aria-hidden="true" />
+          <span>{t.sidebarShort}</span>
+        </a>
+        <div className="gdoc-mobile-crumb" aria-hidden="true">
+          <span>{sectionTitle(currentSection, lang) ?? t.name}</span>
+          <CaretRight size={12} />
+          <strong>{currentDoc ? (lang === "en" ? currentDoc.navTitle ?? currentDoc.title : NAV_SHORT_TITLE[currentDoc.path] ?? currentDoc.title) : t.overviewHint}</strong>
+        </div>
+      </div>
+
+      <button
+        type="button"
+        className="gdoc-backdrop"
+        aria-label={t.closeSidebar}
+        tabIndex={mobileOpen ? 0 : -1}
+        data-open={mobileOpen}
+        onClick={() => closeMobile(true)}
+      />
+
+      <aside
+        id={drawerId}
+        className="gdoc-sidebar"
+        aria-label={t.sidebar}
+        data-open={mobileOpen}
+      >
+        <div className="gdoc-sidebar-head">
+          <Link
+            href={siteHref(handbookPath(lang))}
+            className="gdoc-overview-link"
+            aria-current={isOverview ? "page" : undefined}
+            onClick={() => closeMobile(false)}
+          >
+            <span className="gdoc-overview-mark">
+              <BookOpenText size={16} weight="duotone" aria-hidden="true" />
+              <span>{t.name}</span>
+            </span>
+            <small>{t.overviewHint}</small>
+          </Link>
+          <button
+            ref={closeRef}
+            type="button"
+            className="gdoc-mobile-close"
+            aria-label={t.closeSidebar}
+            onClick={() => closeMobile(true)}
+          >
+            <X size={17} aria-hidden="true" />
+          </button>
+          <a
+            className="gdoc-nojs-close"
+            href={`#${drawerId}-open`}
+            aria-label={t.closeSidebar}
+          >
+            <X size={17} aria-hidden="true" />
+          </a>
+        </div>
+
+        <nav className="gdoc-nav" aria-label={t.chapters}>
+          {groups.map((group) => (
+            <div key={group.id} className="gdoc-nav-group">
+              <h2 className="gdoc-nav-group-head">{sectionTitle(HANDBOOK_SECTIONS.find((sec) => sec.id === group.id), lang) ?? group.title}</h2>
+              <ol className="gdoc-nav-list">
+                {group.items.map((item) => {
+                  const active = item.path === currentPath;
+                  const badge = COMPONENT_BADGE[item.path];
+                  const label = lang === "en" ? item.navTitle ?? item.title : NAV_SHORT_TITLE[item.path] ?? item.title;
+                  return (
+                    <li key={item.path} className={active ? "is-active" : undefined}>
+                      <Link
+                        href={siteHref(handbookPath(lang, item.path))}
+                        aria-current={active ? "page" : undefined}
+                        onClick={() => closeMobile(false)}
+                      >
+                        {badge ? (
+                          <>
+                            <code className="gdoc-comp-pill">{badge}</code>
+                            <span className="gdoc-comp-label">{label}</span>
+                          </>
+                        ) : (
+                          <span>{label}</span>
+                        )}
+                      </Link>
+                    </li>
+                  );
+                })}
+              </ol>
+            </div>
+          ))}
+        </nav>
+      </aside>
+    </>
+  );
+}

package/app/components/HandbookLangRedirect.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { useEffect } from "react";
+import { HANDBOOK_LANG_KEY, type HandbookLang } from "../lib/garden-docs-meta";
+import { swapHandbookLang } from "../lib/handbook-path";
+
+/**
+ * First visit: follow the browser language. Afterwards: follow the reader's
+ * saved choice (set by the 中 / EN switch). Only moves to a page that exists,
+ * which the hreflang link in <head> tells us.
+ */
+export function HandbookLangRedirect({ lang }: { lang: HandbookLang }) {
+  useEffect(() => {
+    let saved: string | null = null;
+    try {
+      saved = localStorage.getItem(HANDBOOK_LANG_KEY);
+    } catch {}
+    const wanted: HandbookLang = saved === "en" || saved === "zh"
+      ? saved
+      : /^en\b/i.test(navigator.language || "") ? "en" : "zh";
+    if (wanted === lang) return;
+    const link = document.querySelector<HTMLLinkElement>(`link[rel="alternate"][hreflang="${wanted === "en" ? "en" : "zh-CN"}"]`);
+    if (!link?.href) return;
+    // The hreflang link says the page exists; the address comes from this one,
+    // so the origin and any basePath stay as they are.
+    const pathname = swapHandbookLang(location.pathname, wanted);
+    if (pathname && pathname !== location.pathname) location.replace(pathname + location.search + location.hash);
+  }, [lang]);
+  return null;
+}

package/app/components/HandbookLangSwitch.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import { usePathname } from "next/navigation";
+import { HANDBOOK_LANG_KEY, handbookBase, type HandbookLang } from "../lib/garden-docs-meta";
+import { siteHref } from "../lib/site-href";
+import { swapHandbookLang } from "../lib/handbook-path";
+
+const noSubscribe = () => () => {};
+
+/** The counterpart page from the hreflang link in <head>, on this origin. */
+function counterpartHref(target: HandbookLang) {
+  const link = document.querySelector<HTMLLinkElement>(`link[rel="alternate"][hreflang="${target === "en" ? "en" : "zh-CN"}"]`);
+  if (link?.href) return swapHandbookLang(location.pathname, target);
+  return target === "zh" ? siteHref(`${handbookBase("zh")}/`) : null;
+}
+
+/** 「中 / EN」 in the top bar on handbook pages. Goes to the counterpart page. */
+export function HandbookLangSwitch() {
+  const pathname = usePathname() ?? "";
+  const lang: HandbookLang = /\/garden\/en(\/|$)/.test(pathname) ? "en" : "zh";
+  const target: HandbookLang = lang === "en" ? "zh" : "en";
+  const href = useSyncExternalStore(
+    noSubscribe,
+    () => counterpartHref(target),
+    () => null,
+  );
+
+  const remember = () => {
+    try {
+      localStorage.setItem(HANDBOOK_LANG_KEY, target);
+    } catch {}
+  };
+  const label = (
+    <>
+      <span aria-current={lang === "zh" ? "true" : undefined}>中</span>
+      <span aria-hidden="true"> / </span>
+      <span aria-current={lang === "en" ? "true" : undefined}>EN</span>
+    </>
+  );
+  if (!href) {
+    return <span className="sh-lang is-disabled" title="No English version of this page yet">{label}</span>;
+  }
+  return (
+    <a className="sh-lang" href={href} hrefLang={target === "en" ? "en" : "zh-CN"} lang={target === "en" ? "en" : undefined} onClick={remember} aria-label={target === "en" ? "Read in English" : "Switch to Chinese"}>
+      {label}
+    </a>
+  );
+}

package/app/components/HandbookView.tsx

@@ -0,0 +1,187 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
+import { ArticleMeasure } from "./ArticleMeasure";
+import { ArticleReferences } from "./ArticleReferences";
+import { ArticleTitle } from "./ArticleTitle";
+import { GardenDocsNav } from "./GardenDocsNav";
+import { HandbookLangRedirect } from "./HandbookLangRedirect";
+import { MarkdownArticle } from "./MarkdownArticle";
+import { TableOfContents } from "./TableOfContents";
+import { extractHeadings, handbookDocs, handbookIndexDoc, hasHandbookPage, type GardenDocEntry } from "../lib/content";
+import { pageAlternates } from "../lib/page-alternates";
+import { absoluteUrl, getSiteUrl } from "../lib/site";
+import { siteHref } from "../lib/site-href";
+import {
+  COMPONENT_BADGE,
+  HANDBOOK_SECTIONS,
+  HANDBOOK_UI,
+  handbookPath,
+  orderedHandbookDocs,
+  sectionTitle,
+  toHandbookNavItems,
+  type HandbookLang,
+} from "../lib/garden-docs-meta";
+import { siteConfig } from "../site.config";
+
+const other = (lang: HandbookLang): HandbookLang => (lang === "en" ? "zh" : "en");
+const hreflang = (lang: HandbookLang) => (lang === "en" ? "en" : "zh-CN");
+
+/** canonical + hreflang links; the counterpart is listed only when it exists. */
+export function handbookLanguages(lang: HandbookLang, docPath: string) {
+  if (!hasHandbookPage(other(lang), docPath)) return undefined;
+  const zh = siteHref(handbookPath("zh", docPath));
+  const en = siteHref(handbookPath("en", docPath));
+  return { "zh-CN": zh, en, "x-default": zh };
+}
+
+export const handbookAlternates = (lang: HandbookLang, docPath: string) =>
+  pageAlternates(handbookPath(lang, docPath), handbookLanguages(lang, docPath));
+
+export async function handbookDocMetadata(lang: HandbookLang, doc: GardenDocEntry | undefined) {
+  if (!doc) return {};
+  const t = HANDBOOK_UI[lang];
+  const baseUrl = await getSiteUrl();
+  const pathname = siteHref(handbookPath(lang, doc.path));
+  return {
+    title: `${doc.title} · ${t.name}`,
+    description: doc.description,
+    alternates: handbookAlternates(lang, doc.path),
+    openGraph: {
+      type: "article",
+      url: absoluteUrl(pathname, baseUrl),
+      title: `${doc.title} · ${t.name}`,
+      description: doc.description,
+      locale: lang === "en" ? "en_US" : "zh_CN",
+    },
+  } satisfies Metadata;
+}
+
+export function HandbookOverview({ lang }: { lang: HandbookLang }) {
+  const t = HANDBOOK_UI[lang];
+  const docs = handbookDocs(lang);
+  const indexDoc = handbookIndexDoc(lang);
+  const navItems = toHandbookNavItems(docs);
+  const firstDoc = orderedHandbookDocs(docs)[0] ?? null;
+  const content = indexDoc?.content ?? "";
+  const headings = extractHeadings(content);
+  // The site config title/subtitle is written in the site's own language.
+  const configured = lang === "zh" ? siteConfig.pages.garden : { title: "", subtitle: "" };
+  const title = configured.title?.trim() || indexDoc?.title || t.name;
+  const subtitle = configured.subtitle?.trim() || indexDoc?.description || "";
+
+  return (
+    <main className="column-reading-page garden-doc-page" lang={hreflang(lang)}>
+      <HandbookLangRedirect lang={lang} />
+      <GardenDocsNav docs={navItems} currentPath="" lang={lang} />
+
+      <article className="article-column garden-doc-article h-entry">
+        <header className="gdoc-article-head">
+          <div className="gdoc-eyebrow">
+            <span>{t.name}</span>
+            <span aria-hidden="true">/</span>
+            <span>{t.overview}</span>
+          </div>
+          <ArticleTitle title={title} />
+          {subtitle ? <p className="gdoc-article-deck p-summary">{subtitle}</p> : null}
+        </header>
+
+        <ArticleMeasure />
+
+        <div className="e-content">
+          <MarkdownArticle content={content} lang={lang} />
+        </div>
+
+        <ArticleReferences references={indexDoc?.references} />
+
+        {firstDoc ? (
+          <nav className="gdoc-pager" aria-label={t.pager}>
+            <Link href={siteHref(handbookPath(lang, firstDoc.path))} className="gdoc-pager-card is-next">
+              <span className="gdoc-pager-dir">
+                {t.next}
+                <ArrowRight size={14} aria-hidden="true" />
+              </span>
+              <strong>{firstDoc.title}</strong>
+            </Link>
+          </nav>
+        ) : null}
+      </article>
+
+      <TableOfContents headings={headings} label={t.toc} lang={lang} />
+    </main>
+  );
+}
+
+export function HandbookDoc({ lang, doc }: { lang: HandbookLang; doc: GardenDocEntry }) {
+  const t = HANDBOOK_UI[lang];
+  const docs = handbookDocs(lang);
+  const ordered = orderedHandbookDocs(docs);
+  const navItems = toHandbookNavItems(docs);
+  const index = ordered.findIndex((item) => item.path === doc.path);
+  const prev = index > 0 ? ordered[index - 1] : null;
+  const next = index >= 0 && index < ordered.length - 1 ? ordered[index + 1] : null;
+  const headings = extractHeadings(doc.content);
+  const sectionMeta = HANDBOOK_SECTIONS.find((sec) => sec.id === doc.section);
+  const componentBadge = COMPONENT_BADGE[doc.path];
+
+  return (
+    <main className="column-reading-page garden-doc-page" lang={hreflang(lang)}>
+      <HandbookLangRedirect lang={lang} />
+      <GardenDocsNav docs={navItems} currentPath={doc.path} lang={lang} />
+
+      <article className="article-column garden-doc-article h-entry">
+        <header className="gdoc-article-head">
+          <div className="gdoc-eyebrow">
+            <Link href={siteHref(handbookPath(lang))} className="gdoc-eyebrow-root">
+              {t.name}
+            </Link>
+            <span aria-hidden="true">/</span>
+            <span>{sectionTitle(sectionMeta, lang) ?? doc.sectionTitle ?? t.guide}</span>
+            {componentBadge ? <code className="gdoc-eyebrow-fence">{`garden ${componentBadge}`}</code> : null}
+          </div>
+          <ArticleTitle title={doc.title} />
+          {doc.description ? <p className="gdoc-article-deck p-summary">{doc.description}</p> : null}
+        </header>
+
+        <ArticleMeasure />
+
+        <div className="e-content">
+          <MarkdownArticle content={doc.content} lang={lang} />
+        </div>
+
+        <ArticleReferences references={doc.references} />
+
+        <nav className="gdoc-pager" aria-label={t.pager}>
+          {prev ? (
+            <Link href={siteHref(handbookPath(lang, prev.path))} className="gdoc-pager-card is-prev">
+              <span className="gdoc-pager-dir">
+                <ArrowLeft size={14} aria-hidden="true" />
+                {t.prev}
+              </span>
+              <strong>{prev.title}</strong>
+            </Link>
+          ) : (
+            <Link href={siteHref(handbookPath(lang))} className="gdoc-pager-card is-prev">
+              <span className="gdoc-pager-dir">
+                <ArrowLeft size={14} aria-hidden="true" />
+                {t.backToOverview}
+              </span>
+              <strong>{t.overviewDocTitle}</strong>
+            </Link>
+          )}
+          {next ? (
+            <Link href={siteHref(handbookPath(lang, next.path))} className="gdoc-pager-card is-next">
+              <span className="gdoc-pager-dir">
+                {t.next}
+                <ArrowRight size={14} aria-hidden="true" />
+              </span>
+              <strong>{next.title}</strong>
+            </Link>
+          ) : null}
+        </nav>
+      </article>
+
+      <TableOfContents headings={headings} label={t.toc} lang={lang} />
+    </main>
+  );
+}

package/app/components/MarkdownArticle.tsx

@@ -1,3 +1,5 @@
+import { UiLangProvider } from "./UiLang";
+import { ui, type UiLang } from "../lib/i18n";
 import { markdownPlugins } from "../lib/markdown-plugins";
 import { remarkA2 } from "../lib/remark-a2.mjs";
 import { remarkLinkCard } from "../lib/remark-link-card.mjs";
@@ -8,7 +10,7 @@ import {
   type HTMLAttributes,
   type ReactNode,
 } from "react";
-import { articleHeadingBase, articleUsesHeadingNumbers, displayHeadingLevel, splitHeadingNumber } from "../lib/content";
+import { articleHeadingBase, autoNumbersHeadings, displayHeadingLevel, splitHeadingNumber } from "../lib/content";
 import Link from "next/link";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
@@ -28,7 +30,7 @@ import { imageDimensions, lookupImageSize } from "../../ui/garden/image-dims.mjs
 import { siteConfig, siteLinks } from "@garden/site-config";
 import { articleLink, sameSiteMatcher } from "../../ui/garden/same-site.mjs";
 import { columnRedirects, internalLinkResolver, readRedirects } from "../../ui/garden/internal-links.mjs";
-import { columnHref, columns, postHref, posts, thoughts } from "../lib/content";
+import { columnHref, columns, gardenDocHref, gardenDocs, gardenDocsEn, postHref, posts, thoughts } from "../lib/content";
 import { LinkCardRefresh } from "./LinkCardRefresh";
 import { linkHost } from "../../scripts/link-meta-core.mjs";
 import { cardDate } from "../../ui/garden/card-refresh.mjs";
@@ -46,10 +48,12 @@ const internalRoute = internalLinkResolver({
     ...columnRedirects({ columns: [...new Set(columns.map((entry) => entry.column).filter(Boolean))].map((slug) => ({ slug })) }),
   ],
   routes: [
-    "/", "/blog", "/columns", "/thoughts", "/tags", "/about",
+    "/", "/blog", "/columns", "/thoughts", "/tags", "/about", "/garden", "/garden/en",
     ...posts.map(postHref),
     ...columns.map(columnHref),
     ...thoughts.map((thought) => `/thoughts/${thought.slug}`),
+    ...gardenDocs.map(gardenDocHref),
+    ...gardenDocsEn.map((doc) => siteHref(`/garden/en/${doc.path}`)),
   ],
   basePath: siteLinks?.basePath ?? "",
   // Same shape as every other address in the site (the slash follows trailingSlash).
@@ -207,11 +211,12 @@ const headingText = (children: ReactNode) => {
   return parts.join("");
 };
 
-export function MarkdownArticle({ content }: { content: string }) {
+export function MarkdownArticle({ content, numbering, lang }: { content: string; numbering?: boolean; lang?: UiLang }) {
+  const t = ui(lang);
   // Optional layer 2: a Worker that refreshes card text. Without it, cards stay as built.
   const cardWorker = content.includes("{card}") ? siteConfig.linkPreview?.worker : undefined;
   const numbers = { h2: 0, h3: 0 };
-  const numberedArticle = articleUsesHeadingNumbers(content);
+  const autoNumber = autoNumbersHeadings(content, numbering);
   const headingBase = articleHeadingBase(content);
   const section = (depth: 2 | 3, children: ReactNode) => {
     const raw = headingText(children).trim();
@@ -222,7 +227,7 @@ export function MarkdownArticle({ content }: { content: string }) {
       const prefix = raw.slice(0, raw.length - split.text.length);
       return { no: split.no, children: stripPrefix(children, prefix) };
     }
-    if (numberedArticle) return { no: "", children };
+    if (!autoNumber) return { no: "", children };
     if (depth === 2) { numbers.h2 += 1; numbers.h3 = 0; return { no: String(numbers.h2), children }; }
     numbers.h3 += 1;
     return { no: numbers.h2 ? `${numbers.h2}.${numbers.h3}` : String(numbers.h3), children };
@@ -247,7 +252,7 @@ export function MarkdownArticle({ content }: { content: string }) {
     "garden-block": (props: { dataPayload?: string; "data-payload"?: string }) => {
       const payload = props.dataPayload ?? props["data-payload"];
       const block = readGardenPayload(payload);
-      if (block?.name === "file" && !block.error) return <GardenFile props={(block.props ?? {}) as Record<string, unknown>} />;
+      if (block?.name === "file" && !block.error) return <GardenFile props={(block.props ?? {}) as Record<string, unknown>} lang={lang} />;
       return <GardenBlock dataPayload={payload} />;
     },
     "garden-codediff": (props: {
@@ -265,6 +270,7 @@ export function MarkdownArticle({ content }: { content: string }) {
     ),
   };
   return (
+    <UiLangProvider lang={lang}>
     <div className="markdown-body prose">
       <ReactMarkdown
         remarkPlugins={[...markdownPlugins, [remarkLinkCard, { sameSite }], [remarkA2, { imageSize: (src: string) => lookupImageSize(imageSizes, src) }]]}
@@ -319,7 +325,7 @@ export function MarkdownArticle({ content }: { content: string }) {
             return <MarkdownImage {...props} {...dims} style={{ ...props.style, ...dims.style }} />;
           },
           table: ({ children, ...props }) => (
-            <div className="table-wrap" role="region" aria-label="表格，可横向滚动" tabIndex={0}>
+            <div className="table-wrap" role="region" aria-label={t.tableScroll} tabIndex={0}>
               <table {...props}>{children}</table>
             </div>
           ),
@@ -355,5 +361,6 @@ export function MarkdownArticle({ content }: { content: string }) {
       </ReactMarkdown>
       {cardWorker ? <LinkCardRefresh endpoint={cardWorker} /> : null}
     </div>
+    </UiLangProvider>
   );
 }

package/app/components/MarkdownImage.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useUi } from "./UiLang";
 import { useEffect, useState, type ComponentPropsWithoutRef } from "react";
 
 // react-markdown also hands over its syntax-tree `node`; it must not reach the DOM.
@@ -8,7 +9,8 @@ type MarkdownImageProps = ComponentPropsWithoutRef<"img"> & { node?: unknown };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export function MarkdownImage({ alt = "", src, node, style, ...props }: MarkdownImageProps) {
   const [open, setOpen] = useState(false);
-  const description = alt || "查看原图";
+  const t = useUi();
+  const description = alt || t.viewImage;
 
   useEffect(() => {
     if (!open) return undefined;
@@ -33,7 +35,7 @@ export function MarkdownImage({ alt = "", src, node, style, ...props }: Markdown
         type="button"
         className="markdown-image-trigger"
         onClick={() => setOpen(true)}
-        aria-label={`放大查看：${description}`}
+        aria-label={t.zoomImage(description)}
       >
         {/* Native images preserve Typora-authored relative paths. */}
         {/* eslint-disable-next-line @next/next/no-img-element */}
@@ -56,9 +58,9 @@ export function MarkdownImage({ alt = "", src, node, style, ...props }: Markdown
               type="button"
               className="markdown-image-lightbox-close"
               onClick={() => setOpen(false)}
-              aria-label="关闭图片预览"
+              aria-label={t.closeImage}
             >
-              关闭
+              {t.close.trim()}
             </button>
           </div>
         </div>

package/app/components/SiteChrome.tsx

@@ -1,18 +1,27 @@
 "use client";
 
 import { usePathname } from "next/navigation";
+import { routeLang, ui } from "../lib/i18n";
 import { SiteFooter } from "./SiteFooter";
 import { SiteHeader } from "./SiteHeader";
 
 export function SiteChrome({ children }: { children: React.ReactNode }) {
   const pathname = usePathname();
-  if (pathname?.startsWith("/admin")) return <>{children}</>;
+  const lang = routeLang(pathname);
+  // The skip link follows the route language too (/garden/en/ is English).
+  const skip = (
+    <a className="skip-link" href="#main-content">
+      {ui(lang).skipToContent}
+    </a>
+  );
+  if (pathname?.startsWith("/admin")) return <>{skip}{children}</>;
 
   return (
     <>
+      {skip}
       <SiteHeader />
       <div id="main-content">{children}</div>
-      <SiteFooter />
+      <SiteFooter docs={pathname?.startsWith("/garden") ?? false} lang={lang} />
     </>
   );
 }

package/app/components/SiteFooter.tsx

@@ -1,13 +1,22 @@
 import { GithubLogo, Rss } from "@phosphor-icons/react/ssr";
 import { githubUrl, siteConfig } from "../site.config";
+import { ui, type UiLang } from "../lib/i18n";
 
-export function SiteFooter() {
+/** On the Garden docs pages the footer carries no site-owner line. */
+export function SiteFooter({ docs = false, lang }: { docs?: boolean; lang?: UiLang }) {
+  const t = ui(lang);
   return (
     <footer className="sh-footer">
       <div className="sh-foot">
         <p>
-          © {new Date().getFullYear()} {siteConfig.author.name} · {siteConfig.footer}
-          <span className="footer-framework"> · 基于 <a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a> 构建</span>
+          {docs ? (
+            <span className="footer-framework">{t.builtWith[0]}<a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a>{t.builtWith[1]}</span>
+          ) : (
+            <>
+              © {new Date().getFullYear()} {siteConfig.author.name} · {siteConfig.footer}
+              <span className="footer-framework"> · {t.builtWith[0]}<a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a>{t.builtWith[1]}</span>
+            </>
+          )}
         </p>
         <div className="sh-foot-links">
           <a href={githubUrl} rel="me">