[8/N] fix(zh): rewrite content and explanatory pages / 重写内容与说明页面中文文案

[edwingao28]

Part of #823 / 属于 #823 路线图的一部分

What changed

• Rewrite and audit the Simplified Chinese About, Glossary, API, Land Acknowledgement, Blog chrome, and explanatory-page surfaces against their English sources.
• Correct protected inline code, metadata/tag parity, terminology, links, and factual scope without changing English content.
• Refine the About introduction, FAQ answers, and closed-loop concurrency explanation so they are faithful and read as natural Chinese technical prose.
• Cover all 31 English/Chinese Blog pairs and all 118 English/Chinese Glossary entries with stable desktop/mobile click journeys.
• Keep Blog TOC and heading-link localization in this page-owned branch, including accessibility and analytics coverage.
• Remove two inline Cypress timeout overrides that violated the repository testing rules.

Scope boundary

Full article-by-article Chinese editorial rewrites remain on hold. This PR only fixes high-confidence protected-content and fidelity regressions in existing article translations.

Validation

• Final-head focused content tests: 174/174 passed.
• Final-head lint, format, and diff checks passed locally.
• The prior pushed head passed all public CI and Chrome/Firefox content journeys; GitHub CI is rerunning on the final pushed head after the copy-only refinements and master sync.
• Current journey coverage includes 31 Blog pairs and 118 Glossary entries at 1440px and 375/390px widths.

This PR is Draft for the Chinese maintainer's rendered-page and sentence-by-sentence review before merge.

中文说明

• 对照英文来源，重写并审核 About、Glossary、API、Land Acknowledgement、Blog 界面以及说明类页面的简体中文文案。
• 修正受保护的 inline code、metadata／tag 配对、术语、链接和事实范围，英文内容保持不变。
• 优化 About 页面介绍、常见问题和闭环并发说明，使其准确保留原意，并符合自然的中文技术表达。
• 为全部 31 对中英文 Blog 和 118 对中英文 Glossary 词条提供稳定的桌面端／移动端点击链路。
• Blog TOC 与标题链接的中文化继续由本页面分支负责，并补齐无障碍和 analytics 测试。
• 移除两处不符合仓库测试规范的 Cypress 内联超时设置。

范围边界

逐篇文章的完整中文编辑重写继续暂缓。本 PR 只修正现有文章翻译中高置信度的受保护内容和语义保真问题。

验证结果

• 最终提交的内容专项测试：174/174 通过。
• 最终提交的 lint、格式和 diff 检查均在本地通过。
• 上一个远端提交已通过全部公开 CI 以及 Chrome／Firefox 内容链路测试；完成文案修订并同步 master 后，GitHub CI 正在针对最终提交重新运行。
• 当前链路测试覆盖 31 对 Blog 和 118 对 Glossary 词条，并包含 1440px 与 375/390px 视口。

本 PR 保持 Draft，等待中文维护者在合并前完成真实页面和逐句人工审核。

---

Note

Medium Risk
The changes touch many localized user-facing strings and add long-running Cypress journeys (content-journeys), which increases CI time and flakiness risk without altering core inference or auth logic.

Overview
This PR audits and rewrites Simplified Chinese copy on About, FAQ, Glossary, API reference, Land Acknowledgement, and selected blog passages—aligned to English sources while preserving protected inline code, tag parity (e.g. cann), and terminology (推测解码 → 投机解码, 评测 → 评估, tooltip → 提示框). The Chinese About page now links to /zh/blog articles instead of English URLs with hreflang="en".

Blog reading chrome gains locale-aware TOC and heading-link copy (Chinese aria-labels, “链接已复制”), with analytics events including locale.

API docs UI adds min-w-0 and data-testid="api-schema-note" so wide schema blocks scroll inside the layout without horizontal page overflow on mobile.

Test coverage is the other major theme: stable data-testid / slug attributes on blog and glossary list/detail pages; new Cypress suites that click through all 31 blog pairs and 118 glossary entries at desktop and mobile widths; API overflow checks; expanded zh-pages journeys; and Vitest guards for FAQ parity, glossary fidelity, land-acknowledgement wording, and blog inline-code preservation.

^{Reviewed by Cursor Bugbot for commit ab10607. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
inferencemax-app	Ready	Preview	Aug 29, 2026 3:44am

[github-actions]

Claude finished @edwingao28's task in 2m 25s —— View job

---

Review complete

• Read the diff (origin/master...HEAD)
• Check CI status
• Static review (bugs, tests, breaking changes)
• Chinese-copy review (advisory)
• Runtime verification (localhost / Playwright)
• Post findings

---

🔴 1 blocking issue — a genuine CI failure not covered by the acknowledged timing guard.

blog-content.test.ts was changed to hardcode expect(enFiles).toHaveLength(19), but the repo has 31 blog posts (31 EN / 31 ZH confirmed on disk). The Tests (Unit) job is red with expected [ …(31) ] to have a length of 19 but got 31. The prior test used a flexible toBeGreaterThan(0) check, so this PR turned a green assertion red. This is distinct from the cypress-timings guard the PR description calls out as expected. Inline comment + fix →

Runtime verification (Playwright, real DB): /zh/about (corrected /zh/blog/... links, no more "英文文章" labels) and /zh/blog/inferencex-v2-... both render cleanly with 0 console errors; the localized BlogToc shows 本页目录 / （点击展开） and HeadingLink locale wiring works. New data-testid/data-* hooks on blog/glossary cards are inert markup — no risk.

Chinese copy (advisory, non-blocking): the touched strings are all legitimate fidelity/terminology fixes against the English source — NeoCoud→NeoCloud, 评测→评估 (matches the preferred evaluation 评估), 推测解码→投机解码, and scope-tightening on the audited glossary definitions (each guarded by a new glossary.test.ts assertion). Nothing that alters source meaning; no maintainer escalation needed.

Test coverage: new lib/content changes ship colocated tests (faq-data.test.ts, api-documentation.test.ts, land-acknowledgement-content.test.ts, blog-shared-chrome.test.tsx, expanded blog-content/glossary suites) plus the content-journeys.cy.ts E2E — good coverage, aside from the count bug above.

Fix the hardcoded post count and the unit suite goes green. Everything else LGTM.
· feat/zh-content-pages

[github-actions]

Claude finished @edwingao28's task in 1m 56s —— View job

---

Re-review complete

• Read new commits since last review — none (HEAD still 0748d30c)
• Check CI status
• Static review of new changes
• Chinese-copy review (advisory)
• Post findings

---

No new commits since my previous review. This sync appears to be a base/re-trigger, not new code, so there's nothing new to review — but the previously-flagged blocker is still unresolved and Tests (Unit) is still red.

🔴 Still blocking — unchanged from last review

Tests (Unit) (run 33219874137) reports 2 failed test files:

1. blog-content.test.ts:83 — expected [ …(31) ] to have a length of 19 but got 31. The repo has 31 EN / 31 ZH posts on disk, but the assertion added in this PR hardcodes toHaveLength(19). This is the exact issue from my inline comment and it has not been addressed. Fix: bump the count/title to 31, or drop the magic number and lean on expect(zhFiles).toEqual(enFiles) for pairing. This is a genuine regression this PR introduced (the old check was toBeGreaterThan(0)).

2. cypress-timings.test.ts — contains one positive timing for every current integration spec (62 vs 63). This is the acknowledged timing-baseline guard: the new content-journeys.cy.ts spec intentionally ships without a timing entry until the Chrome/Firefox run regenerates observed timings, per the PR's "Pending Draft verification". Not a new concern — expected while the PR is Draft.

Everything else

• Runtime verification from the prior review still stands (nothing changed): /zh/about, /zh/blog/..., localized BlogToc/HeadingLink render cleanly with 0 console errors.
• Chinese-copy changes remain legitimate fidelity/terminology fixes (NeoCloud, 评估, 投机解码, glossary scope-tightening) — advisory, non-blocking, no maintainer escalation needed.
• Test coverage for the new lib/content code is present.

Bottom line: fix the blog-content.test.ts count (finding #1) and the unit suite goes green apart from the expected cypress-timings guard, which clears once the Draft timing run lands. No other blocking issues.
· feat/zh-content-pages

[github-actions]

Claude finished @edwingao28's task in 1m 49s —— View job

---

Re-review complete

• Read new commit since last review — 675eb665 fix(tests): refresh content counts after rebase onto master (HEAD advanced from 0748d30c)
• Check CI status
• Verify the count fix resolves the prior blocker
• Post findings

---

✅ The 🔴 blocker from my previous review is fixed. Commit 675eb665 bumps the hardcoded counts to match the post-rebase repo state, and Typecheck and unit tests is now green.

What the new commit does (test-only, verified)

1. blog-content.test.ts — toHaveLength(19) → toHaveLength(31) (and title updated). Confirmed on disk: 31 EN / 31 ZH blog pairs, and expect(zhFiles).toEqual(enFiles) still guards pairing. ✔
2. content-journeys.cy.ts — BLOG_POST_COUNT 19 → 31, GLOSSARY_ENTRY_COUNT 54 → 118. Confirmed getAllGlossaryEntries().length === 118, so the [data-testid="glossary-entry-link"] length assertion matches the rendered index. This is the fix for the 16 Blacksmith E2E failures (the length assertions on the listing/index were the first thing to trip on the stale counts). ✔
3. timings.json — registers the new content-journeys.cy.ts spec (150 s) and restores alphabetical order (fleet-lifecycle moved to its correct slot). This clears the previously-acknowledged cypress-timings 62-vs-63 guard, which is why Tests (Unit) went green.

CI status

Check	Status
Typecheck and unit tests	✅ pass (was red)
Component tests	✅ pass
Lint and format	✅ pass
Cursor Bugbot	✅ pass
E2E (chrome, shard 2)	✅ pass
E2E (remaining shards)	⏳ still running

The unit blocker and the cypress-timings guard are both cleared. The remaining E2E shards are still in progress, but the commit targets exactly the length assertions that caused the earlier content-journeys failures, and the first completed shard is green.

No new concerns

The commit only touches two test files and timings.json — no UI/runtime surface changed since my prior review, so the earlier Playwright verification (/zh/about, /zh/blog/..., localized BlogToc/HeadingLink, 0 console errors) still stands. Chinese-copy changes remain the same legitimate fidelity/terminology fixes (advisory, non-blocking).

🟢 Re-review: no blocking issues. Prior blocker resolved; recommend confirming all E2E shards go green before merge.
· feat/zh-content-pages

[github-actions]

Claude finished @edwingao28's task in 55s —— View job

---

Re-review complete

• Read new commit since last review — 57cbbd41 fix(e2e): tolerate streamed head metadata in content journeys (HEAD advanced from 675eb665)
• Check CI status
• Static review of the new change
• Post findings

---

🟢 Re-review: no blocking issues. The single new commit is test-only and correctly reasoned.

What 57cbbd41 does (test-only, verified)

content-journeys.cy.ts — both the blog and glossary journeys previously did:

cy.get(`link[rel="alternate"][hreflang="${alternateLocale}"]`)
  .should('have.attr', 'href', `${CONTENT_SITE_URL}${alternatePath}`);

That grabs whatever alternate link is first in document order and immediately asserts its href. During a client-side navigation Next.js updates the body before the streamed <link rel="alternate"> tags replace the listing page's, so the first matching alternate can still be the stale listing-page one — a genuine race that flakes on the first article/term of each journey.

The fix folds the expected href into the selector and asserts existence with a retry:

cy.get(
  `link[rel="alternate"][hreflang="${alternateLocale}"][href="${CONTENT_SITE_URL}${alternatePath}"]`,
  { timeout: 15000 },
).should('exist');

Cypress retries the query until the fully-updated link appears, so the assertion no longer races the head update. This is the standard way to wait for streamed head metadata and is strictly more specific than the old check (it requires rel, hreflang, and the exact href). ✔ The alternateLocale/alternatePath inputs and the surrounding matrix are unchanged and valid.

This targets exactly the head-metadata timing that produced the remaining Blacksmith content-journeys flakes (the count assertions were already fixed in 675eb665).

CI status

Check	Status
Tests (Unit)	✅ pass
Component tests / Code Quality	✅ pass
Lint & Format	✅ pass
Tests (E2E)	⏳ in progress

Nothing else changed

Only one E2E test file was touched — no UI/runtime surface changed since the prior review, so the earlier Playwright verification (/zh/about, /zh/blog/..., localized BlogToc/HeadingLink, 0 console errors) still stands, and the Chinese-copy changes remain the same legitimate fidelity/terminology fixes (advisory, non-blocking).

Prior blocker (hardcoded 19 post count) stays resolved. Recommend confirming all E2E shards go green before merge.
· feat/zh-content-pages

[github-actions]

Claude finished @edwingao28's task in 1m 59s —— View job

---

Re-review complete

• Identify new commits since last review (57cbbd41)
• Review new changes (static)
• Chinese-copy review (advisory)
• Check CI status
• Runtime verification (/zh/about)
• Post findings

---

🟢 Re-review: no blocking issues. Two new commits since my prior review: 9ac9f6cc (zh copy refinements) and 1c924fd2 (merge master). The one code-bearing commit is Chinese-copy + test-only, and it's clean.

9ac9f6cc — refine explanatory page copy (verified)

1. content-journeys.cy.ts — removes the inline { timeout: 15000 } I flagged as helpful in the last review. This is actually the correct move: docs/testing.md:63 bans inline Cypress timeout overrides ("Never pass { timeout: N } to individual commands") in favor of the global defaultCommandTimeout (6000 ms in cypress.config.ts). The real race fix — folding the exact href into the selector so Cypress retries until the fully-updated streamed head link appears — is retained, so the 6 s global window still covers the client-side-nav head update. Convention-compliant, race still handled. ✔
2. zh/about/page.tsx, faq-data-zh.ts, glossary-zh.ts — fidelity/naturalness rewrites, checked against the English sources. The intro Open-Source Continuous ... Trusted by Operators of Trillion-Dollar, GigaWatt-Scale Token Factories → 持续运行的开源智能体推理基准测试，受到万亿美元级、吉瓦规模 Token 工厂运营方的信赖 is accurate and reads naturally; the FAQ/glossary refinements (Concurrency→并发量, tooltip→提示框, request batch→请求批次大小) tighten terminology without changing any claim. Advisory, non-blocking, no maintainer escalation needed.
3. faq-data.test.ts / glossary.test.ts — colocated assertions pin the new copy in both directions (positive + negative). Good coverage for the copy changes. ✔

Runtime verification (Playwright, real DB)

/zh/about renders the refined heading and intro paragraph exactly as authored, 0 console errors. The merge from master didn't disturb the localized surface.

CI status

Check	Status
Tests (Unit)	✅ pass (blocker from earlier reviews stays resolved)
Lint & Format	✅ pass
Code Quality	⏳ in progress
Tests (E2E)	⏳ in progress

The E2E run is the one thing to confirm green before merge, since 9ac9f6cc shortens the content-journeys alternate-link wait from 15 s to the 6 s global timeout — the retrying selector should cover it, but the shard result is the proof.

Prior blocker (hardcoded 19 post count) remains resolved. No new blocking issues.
· feat/zh-content-pages

[github-actions]

Claude finished @edwingao28's task in 1m 32s —— View job

---

Re-review complete

• Identify new commits since last review
• Review new changes (static)
• Chinese-copy review (advisory)
• Check CI status
• Runtime verification (/zh/about)
• Post findings

---

🟢 Re-review: no blocking issues. One code-bearing commit since my prior review — c3978510 fix(zh): refine content provenance copy (plus ab10607c, a master merge). It is Chinese-copy + test-only, and it's clean.

c3978510 — refine content provenance copy (verified)

• zh/about/page.tsx — Reproducibility section rewrite, checked against the English source (src/app/about/page.tsx). recipe→测试配置, tooltip→提示框, and naturalized step copy are faithful: "audit, rerun, or fork a benchmark" → 核查结果来源、重新运行测试，或基于现有配置创建新的基准测试 preserves the claim while reading as natural Chinese. "Browse workflow runs"→查看工作流运行记录, "…recipes"→查看测试配置. Advisory, non-blocking, no maintainer escalation needed.
• faq-data-zh.ts — FAQ answers move to 测试配置 / GitHub Actions 运行记录 / 提示框 terminology; no claim altered vs. the English FAQ source.
• glossary-zh.ts — mechanical tooltip→提示框 across 5 audited entries (speculative-decoding, context-parallelism, recipe, pipeline-parallelism, dp-attention), consistent with the established term.
• faq-data.test.ts / glossary.test.ts — colocated positive + negative assertions pin each new string (and forbid the old tooltip / 成功的运行将被加载…). Good coverage for the copy delta. ✔

Runtime verification (Playwright, real DB)

/zh/about renders the refined Reproducibility section exactly as authored, 0 console errors. The master merge did not disturb the localized surface.

CI status

Check	Status
Tests (Unit)	✅ pass
Lint & Format	✅ pass
Code Quality	✅ pass
Tests (E2E)	⏳ in progress

The prior blocker (hardcoded 19 post count) remains resolved. Confirm the E2E shards go green before merge; no new blocking issues.
· feat/zh-content-pages