feat(i18n-isr): persist bot-path auto-translations to registry backend

[snomiao]

Summary

After the bot path's OpenAI auto-translation succeeds, fire-and-forget a POST /nodes/{id}/translations to the registry backend so subsequent ISR builds (and the human path) read the stored translation instead of re-calling OpenAI.

Unblocks #258.

Why this PR exists

Today (after #257), the bot path generates translations via OpenAI every time the ISR cache cold-misses. Without persistence:

• OpenAI gets called once per (node, locale, region) per hour — paid every cycle, not once.
• The human path (/nodes/[id]) never sees the auto-translation because nothing writes it back.

This PR persists the result, which:

• Bounds OpenAI cost to one call per (node, locale) for the entire history of the translation (until a publisher overrides via PR feat: add node translation editor for i18n management #179 or the source changes).
• Eventually converges the human and bot paths — humans see a Japanese meta description once a bot has crawled.
• Costs the request ~0ms (fire-and-forget; awaited would re-introduce the blocking-render problem the bot/human split was designed to avoid).

Dependencies

• Backend: Comfy-Org/cloud#3641 attaches APISecretMiddleware to POST /nodes/{id}/translations. Without it the backend returns 401 and the persistence step silently warns + no-ops; the page still renders the OpenAI translation.
• Base branch: this PR is stacked on sno-i18n-isr (PR feat: ISR with auto-translated content i18n for node pages #257). Once feat: ISR with auto-translated content i18n for node pages #257 merges, rebase onto main.

Operational config

• New env: COMFY_REGISTRY_ADMIN_SECRET — server-only (NOT NEXT_PUBLIC_*). Same value as backend's AdminAPISecret. Add to Vercel project env (production + preview as desired).
• Without the env set, the persistence call no-ops — safe to deploy before the backend lands.

Changes

• src/hooks/i18n/persistNodeTranslation.ts — new helper. Validates content source is "auto", uses 10s AbortController timeout, logs but never throws.
• src/hooks/i18n/nodeStaticProps.ts — call persistNodeTranslation (fire-and-forget) when blocking: true and the loader generated a new "auto" translation. Awaiting is deliberately avoided.
• .env — placeholder for COMFY_REGISTRY_ADMIN_SECRET matching the existing GITHUB_CLIENT_ID pattern.
• docs/i18n-isr-implementation.md — Key Decisions §4a documents the persistence path and the dependency on the backend PR.

Test plan

• With COMFY_REGISTRY_ADMIN_SECRET unset: no behavior change, no warnings (Decision: silently no-op).
• With COMFY_REGISTRY_ADMIN_SECRET set but backend unupdated: persistence call returns 401, warning logged, page still renders translated content.
• After backend PR lands: first bot hit on a fresh (node, locale) writes node.translations[locale]; second hit returns source: "stored" (no OpenAI call); human path on the same (node, locale) now also returns the translated description.
• Confirm fire-and-forget — TTFB on bot ISR cold miss does not regress vs. PR feat: ISR with auto-translated content i18n for node pages #257.

Out of scope

• Migrating from shared secret to a scoped GCP service account / Workload Identity Federation. Acceptable follow-up once write path is stable.
• Backfilling existing translations — relies on natural crawl traffic to populate. A one-off backfill cron is a separate PR if desired.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
registry-web	Ready	Preview, Comment	May 12, 2026 3:47am