docs(i18n): keep the locale prefix on twelve links in the Chinese pages

[claude]

Fixes #1592

Description

Twelve site-absolute links inside the translated documentation dropped the locale
segment, so a reader on a Chinese page clicked and landed silently on the English
page. The target existed, so nothing 404-ed and nothing reported it. The docs site
sets hideLocale: 'default-locale' (apps/docs/lib/i18n.ts), so English lives at
/docs/... and /zh-Hans/docs/... / /zh-Hant/docs/... are the only spellings
that open a translated page.

The links stay site-absolute — the established form here, 654 of them under
content/docs after this change — and only gain the locale segment. The English
pages were already correct and are untouched.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Documentation update

Changes Made

Every rewritten link, with the file the URL now resolves to. Each target was
checked to ship the page's own locale before rewriting: adding a prefix to a
target that does not ship that locale would turn a silent wrong-language landing
into a hard 404, which is strictly worse.

#	edited page	link now	resolves to	locale page
1	administration/sandbox-and-releases.zh-Hans.mdx:193	/zh-Hans/docs/guides/email-and-calendar	guides/email-and-calendar.zh-Hans.mdx	exists
2	administration/sandbox-and-releases.zh-Hant.mdx:193	/zh-Hant/docs/guides/email-and-calendar	guides/email-and-calendar.zh-Hant.mdx	exists
3	reference/faq.zh-Hans.mdx:156	/zh-Hans/docs/guides/integrations	guides/integrations.zh-Hans.mdx	exists
4	reference/faq.zh-Hant.mdx:156	/zh-Hant/docs/guides/integrations	guides/integrations.zh-Hant.mdx	exists
5	sales/opportunities.zh-Hans.mdx:42	/zh-Hans/docs/sales/quotes	sales/quotes.zh-Hans.mdx	exists
6	sales/opportunities.zh-Hans.mdx:44	/zh-Hans/docs/analytics/dashboards	analytics/dashboards.zh-Hans.mdx	exists
7	sales/opportunities.zh-Hant.mdx:42	/zh-Hant/docs/sales/quotes	sales/quotes.zh-Hant.mdx	exists
8	sales/opportunities.zh-Hant.mdx:44	/zh-Hant/docs/analytics/dashboards	analytics/dashboards.zh-Hant.mdx	exists
9	service/cases.zh-Hans.mdx:156	/zh-Hans/docs/administration/sharing-and-security	administration/sharing-and-security.zh-Hans.mdx	exists
10	service/cases.zh-Hant.mdx:156	/zh-Hant/docs/administration/sharing-and-security	administration/sharing-and-security.zh-Hant.mdx	exists
11	service/index.zh-Hans.mdx:39	/zh-Hans/docs/service/cases	service/cases.zh-Hans.mdx	exists
12	service/index.zh-Hant.mdx:39	/zh-Hant/docs/service/cases	service/cases.zh-Hant.mdx	exists

12 of 12 targets ship the locale, so none of the twelve was left alone.

Plus .changeset/chinese-docs-links-keep-their-locale.md. Diff: 10 files, 12
insertions, 12 deletions, one line changed per link.

Measured, not recalled

Taken in this worktree at origin/main = 81a79ee, 2026-09-05T22:35Z, and
re-taken after the fix at 329a881:

	before	after
unprefixed ](/docs/…) in .zh-Han{s,t}.mdx	12	0
prefixed ](/zh-Han{s,t}/docs/…), link occurrences	642	654
prefixed, matching lines (grep -c)	612	624

The card's control figure of 619 (317 + 302) is stale and is not quoted here.
⚠️ Note the two denominators are different measurements of the same tree: 642
counts link occurrences, 612 counts lines holding at least one such link (30
lines carry two or more). The numerator 12 is an occurrence count that happens
to also be 12 lines, so a 12 / 612 ratio mixes the two units.

Each edited line was checked mechanically to differ from its previous form by
the inserted locale segment and by nothing else — 12 line pairs, 12 prefixes
inserted, 0 mismatches.

Three-face parity was checked rather than assumed. The English face of all five
page families already spells these links correctly (/docs/... is right for the
default locale), so nothing here makes the three faces disagree in a new way. In
fact six of the twelve sites contradicted their own page: reference/faq.zh-Hans.mdx
links Integrations with the prefix on line 148 and without it on line 156.

Testing

pnpm verify chain, whole chain green in this worktree at 329a881. What each
green actually establishes is stated, because most of them do not look at this
change at all:

gate	exit	scope vs this diff	what its green establishes
pnpm validate	0	src/ metadata	nothing about this change
pnpm typecheck	0	*.ts	nothing about this change
pnpm lint	0	src/ metadata	nothing about this change
pnpm lint:i18n-gate	0	src/translations/** lint issues	nothing about this change
pnpm hygiene	0	control-byte check does read content/ + .changeset/ (its own line: "plus 460 under content, .changeset, docs, .github, .claude")	no raw control bytes in the 10 edited pages or the changeset. Says nothing about link correctness
pnpm hygiene:tokens	0	src/**/*.ts	nothing about this change
pnpm build	0	metadata artifact	nothing about this change
pnpm test	0 — 160 files, 3391 passed, 1 skipped	the docs suites read content/docs, including these 10 files	this change breaks none of them. Not evidence the links are right — see below

⛔ No green here is evidence that the links are correct. That was measured,
not assumed. With the defect fully restored on disk from 81a79ee (all 10 files
byte-identical to their pre-fix blobs, verified by git hash-object against the
base blob hashes, 12 unprefixed links back on disk), the whole suite is still
green: 160 files, 3391 passed — and pnpm hygiene is still green too. The tree
was then restored to HEAD and git diff HEAD proved empty. So no gate in this
repo can distinguish the defect from the fix, which is the card's own finding,
now measured rather than recalled.

What does stand behind the change is the per-link resolution table above: 654 of
654 prefixed links in localized pages now point at a localized page that exists
on disk (0 missing), and no English page carries a zh-Han{s,t} prefix.

Workflows this PR wakes

• Link Check — triggers (**/*.md and **/*.mdx), but is configured
  file-extension: '.md', an exact match, with check-modified-files-only: yes.
  It therefore opens none of the 10 .mdx files and only the changeset. Its
  own header records that it has no base URL and calls every site-absolute
  /docs/… link dead, so a green from it is not evidence about these edits, and
  a red from it would be about the changeset. The changeset deliberately contains
  no markdown links and no bare URLs.
• Docs App — fires on content/docs/** and will build the docs app. It does
  not resolve markdown link targets.
• CI, CodeQL, E2E, Labeler — fire on every PR.
• Changeset Check — fires; this PR adds a changeset, so no skip-changeset
  label is needed or applied.
• Code Quality — does not fire: its paths are **.ts/.js/.mjs/.json/.yml/.yaml
  and this diff has none of those (the changeset is .md).
• Deploy Docs — does not fire (push to main, paths docs/** + README.md).

Scope

Exactly the 12 links plus the changeset. Two things this PR deliberately does
not do, per the seat ruling on the card:

• No guard. The card's Suggested shape proposes a test that keeps the ratio
  from drifting back. AGENTS.md § 3. ⛔ Do not build platform-level tooling here
  rules it out: lint, validation, gates and diagnostics belong to the platform, and
  tests here pin this repo's own business facts. A locale-prefix-on-links rule pins
  no business fact of this repo. Precedent: [Decision] 要不要加一道注释量门禁?#1183 的棘轮按设计看不见 #1184 的工作,phase 2/3 目前没有仪表 #1423, where the comment-volume gate was
  deliberately not built.
• No upstream card either, this round: epic Epic: bring this repo's test farm back under the 2026-08-31 ruling — platform-first, os lint --strict first, then retire the local re-implementations by family #1579 step 6 froze this family
  ("no new docs-drift tests; no card; revisit when a platform doc-lint exists").
  The candidate is recorded on Twelve links inside localized docs pages drop the locale prefix, so a Chinese reader clicking them lands on the English page #1592 for that revisit.

No test/** file is touched. No out-of-scope defect was found while doing this:
after the fix, 654 of 654 prefixed links resolve, and the only other site-absolute
paths in localized pages are three /screenshots/... asset URLs, which are
correctly unprefixed.

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 5, 2026 10:50pm UTC