feat(web): add local GT catalog pipeline for website and docs

Keep the dictionary runtime as the one i18n path and give updated English marketing/docs copy a fail-closed, lockfile-pinned translation lane. Do not wrap the TUI, completions, or /translate.

Author: Hmbown

docs/LOCALIZATION.md

@@ -81,6 +81,17 @@ locale, Chinese included.** `web/app/[locale]/page.tsx`,
 `getChrome(locale)`. `web/lib/i18n/dictionaries/zh/` now exists (it used to
 be inline TSX), and nav/footer link sets are generated once in
 `web/lib/i18n/links.ts` so every locale gets the identical route shape.
+
+**Website/docs translation pipeline (General Translation CLI, 2026-08-28).**
+Runtime stays the dictionaries above — do not add `gt-next` beside them.
+`web/gt-catalog/[locale].json` is the local JSON interchange (`en` + live
+`zh` first). `npm run i18n:gt -- export` writes catalogs from dictionaries;
+`check` (hooked from `check:locales`) requires them to match; `import`
+writes reviewed JSON back to website dictionary TS only. `translate` is
+fail-closed unless BYOK `GT_API_KEY` and `GT_PROJECT_ID` are set in the
+environment — never commit those values, never point this config at
+`crates/tui/locales`, and never wrap model completions. `gt generate` is
+not used: it is a framework JSX scanner, not a JSON-catalog tool.
 Reference shape: **`ChromeDict` 52 keys, `HomeDict` 62 keys.** Bilingual
 secondary nav labels, the masthead seal and issue line, the ticker live
 label, and the per-locale `Intl` date tag are dictionary values — no locale

web/.env.example

@@ -25,3 +25,10 @@ MAINTAINER_GITHUB_PAT=
 # Set to 1 once the Gitee mirror at gitee.com/Hmbown/...
 # exists. Until then leave blank to hide Gitee links.
 NEXT_PUBLIC_GITEE_ENABLED=
+
+# Optional BYOK for website/docs machine translation via the General
+# Translation CLI (`npm run i18n:gt -- translate`). Never commit values.
+# Check/export/import are local and do not need these. Runtime does not
+# call GT. Fail-closed without both. Never wrap model completions.
+# GT_API_KEY=
+# GT_PROJECT_ID=

web/AGENTS.md

@@ -12,7 +12,10 @@ site.
 - Localization migrations are one-way. New or touched pages use the shared
   dictionary/content spine; do not add page-local language booleans, `isZh`
   copy forks, or hard-coded translated page clones. A compatibility exception
-  must name the external contract that still requires it.
+  must name the external contract that still requires it. Website/docs
+  machine translation uses `npm run i18n:gt` (local JSON catalogs into the
+  same dictionaries). Do not add `gt-next` beside that path, and do not
+  point GT at TUI locale packs.
 - Real-session media is owned by `lib/media-manifest.ts`. `pending` is the
   truthful state until the complete asset set passes manifest tests.
 - `AGENT.md` (singular) documents maintainer-owned community automation. Do not

web/gt-catalog/en.json

@@ -0,0 +1,9 @@
+{
+  "defaultLocale": "en",
+  "locales": ["zh"],
+  "files": {
+    "json": {
+      "include": ["gt-catalog/[locale].json"]
+    }
+  }
+}

web/gt-catalog/zh.json

@@ -0,0 +1,45 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { getChrome, getDocsGuide, getHome } from "./dictionaries";
+
+const webRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+function runGtSite(command: string, extraEnv: NodeJS.ProcessEnv = {}) {
+  return spawnSync(process.execPath, [join(webRoot, "scripts", "gt-site.mjs"), command], {
+    cwd: webRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      GT_API_KEY: "",
+      GT_PROJECT_ID: "",
+      ...extraEnv,
+    },
+  });
+}
+
+describe("website GT catalog pipeline", () => {
+  it("keeps local catalogs in sync with the dictionary runtime", () => {
+    const check = runGtSite("check");
+    expect(check.status, check.stderr || check.stdout).toBe(0);
+    expect(check.stdout).toContain("TUI packs untouched");
+
+    const zh = JSON.parse(readFileSync(join(webRoot, "gt-catalog", "zh.json"), "utf8"));
+    expect(zh.chrome.navDocs).toBe(getChrome("zh").navDocs);
+    expect(zh.home.kicker).toBe(getHome("zh").kicker);
+    expect(zh["docs-guide"].overviewTitle).toBe(getDocsGuide("zh").overviewTitle);
+
+    const config = readFileSync(join(webRoot, "gt.config.json"), "utf8");
+    expect(config).toContain("gt-catalog/[locale].json");
+    expect(config).not.toContain("crates/tui");
+    expect(config).not.toContain("prompts/text.rs");
+  });
+
+  it("fails closed when translate is asked to call the GT API without BYOK env", () => {
+    const translate = runGtSite("translate");
+    expect(translate.status).not.toBe(0);
+    expect(`${translate.stderr}${translate.stdout}`).toMatch(/fail-closed|GT_API_KEY/);
+  });
+});