Skip to content

fix(docs): match locale notice routes with POSIX separators - #206

Open
dajiaohuang wants to merge 1 commit into
vastsa:mainfrom
dajiaohuang:fix/docs-locale-check-windows-paths
Open

fix(docs): match locale notice routes with POSIX separators#206
dajiaohuang wants to merge 1 commit into
vastsa:mainfrom
dajiaohuang:fix/docs-locale-check-windows-paths

Conversation

@dajiaohuang

Copy link
Copy Markdown

Fixes #201.

Summary

pnpm docs:check fails on Windows and passes on the Linux CI runner. The check builds the required source-notice route from a path.relative result, which separates with backslashes on Windows, so it looks for /spec/01-product\00-overview while the Chinese mirror links /spec/01-product/00-overview.

Cause

const englishRoute = `/spec/${relativePath.replace(/\.md$/, '')}`

On Windows relativePath is 01-product\00-overview.md. The mirror contains the POSIX route:

> **翻译说明:** 本页是与 [英文源规格](/spec/01-product/00-overview) 一一对应的机器辅助翻译。

so source.includes(...) never matches and every nested page is reported invalid. The three pages directly under docs/spec (00-baseline.md, NAV.md, README.md) have no separator and pass; the reported list contains exactly the other 74 files, which is the signature of the bug.

Reproduction

Windows, on main at 6e6d710e:

$ node docs/scripts/check-locales.mjs
Invalid Chinese source notices:
01-product\00-overview.md
... (74 entries)
$ echo $?
1

With this change:

$ node docs/scripts/check-locales.mjs
Verified 77 English/Chinese specification pairs.
$ echo $?
0

Changes

  • docs/scripts/check-locales.mjs: normalize separators when assembling the notice route; split the check into noticeRoute and verifyLocalePairs, with the CLI body behind a main() guard so importing the module no longer runs the scan. Messages and exit codes are unchanged.
  • docs/scripts/check-locales.test.mjs: covers the route normalization and the pair scan.
  • docs/package.json: adds "test": "node --test".

Validation

  • node docs/scripts/check-locales.mjs — exit 1 before, exit 0 after (77 pairs verified).
  • node --test in docs/ — 2 tests pass. Against the unfixed script the suite fails, so it is bound to the fix.
  • node scripts/check-release-docs.mjs — unaffected by this change (verified separately).
  • git diff --check — clean; git ls-files --eol reports w/lf for the spec pages, so this is not a line-ending problem.

Notes for the maintainer

  • The new test script uses Node's built-in runner, so it adds no dependency. ci.yml already runs pnpm -r --if-present test, which will now include the docs package; if you would rather keep the docs workspace out of that job, drop the script and keep the test file. No workflow file is modified.
  • The route assertion is only a regression guard on Windows: on Linux (path.sep === '/') the normalization is a no-op and the test passed before the fix as well. The assertion that fails on every platform is the import of noticeRoute, since the unfixed script does not export it.
  • Worth considering separately: ci.yml ignores docs/**, so only the docs-check workflow covers this path, and that workflow runs solely on ubuntu-latest — which is why a Windows-only failure can stay invisible. I have not changed any workflow.

🤖 Generated with Claude Code

`path.relative` separates with backslashes on Windows, so the notice route
built from a nested page became `/spec/01-product\00-overview` and never
matched the POSIX route the Chinese mirror actually links. Every nested page
was reported as an invalid source notice, and `pnpm docs:check` exited 1 on
Windows while passing on the Linux runner. The three pages directly under
`docs/spec` were unaffected because their relative path has no separator.

Normalize the separators when assembling the route, and split the check into
`noticeRoute`/`verifyLocalePairs` so both the route and the pair scan can be
covered instead of only by running the script.

Refs vastsa#201
@vercel

vercel Bot commented Sep 10, 2026

Copy link
Copy Markdown

@dajiaohuang is attempting to deploy a commit to the vastsa's projects Team on Vercel.

A member of the Team first needs to authorize it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] pnpm docs:check fails on Windows: notice routes are built with backslashes

1 participant