fix(docs): reject non-locale [lang] segments instead of serving the homepage (#12258)

`apps/docs/app/[lang]/` matches ANY single path segment, and `proxy.ts`'s
matcher deliberately excludes dotted paths from locale rewriting (static
assets must not be rewritten). So every dotted single-segment URL skipped the
proxy, landed on `[lang]` with `lang` set to that literal segment, and rendered
the full homepage under a 200 -- an unbounded set of duplicate homepages at
exactly the URLs crawlers probe by default, including `/robots.txt` and
`/sitemap.xml`.

Measured before the fix on the dev server: `/foo.txt`, `/ads.txt`,
`/security.txt`, `/anything.html`, `/sitemap_index.xml`, `/robots.txt` and
`/sitemap.xml` all returned 200 with the homepage, while `/this-page-does-not-exist`
correctly returned 404. A temporary probe in the layout printed
`lang="foo.txt"`, `lang="ads.txt"`, `lang="robots.txt"`, `lang="sitemap.xml"`
against `lang="en"` for `/docs`, `/blog` and `/`.

The declared locales are the contract, so enforce them where they are violated:
`lib/i18n.ts` gains `isSupportedLanguage()` derived from `i18n.languages`, and
the `[lang]` layout calls `notFound()` before it renders anything when the
segment is not a declared locale.

`scripts/check-docs-locale-catch-all.mjs` pins it. The guard is three lines in
a layout that is otherwise pure presentation, and deleting it breaks nothing
any other check can see -- every page still renders, every type still checks,
every link still resolves; the only symptom is a 200 where a 404 belongs, on
URLs no test requests. The gate checks the two halves as one conditional
invariant (if dotted paths bypass the proxy, then every top-level dynamic
segment must reject a non-locale parameter before rendering), so it reasons
rather than pattern-matches and covers the class rather than the file.

Co-authored-by: Jack Zhuang <zhuangjianguo@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 3 people

.github/workflows/lint.yml

@@ -1111,6 +1111,27 @@ jobs:
       - name: Docs redirect destinations resolve, and no chains
         run: pnpm check:docs-redirects
 
+      # The docs site's `app/[lang]/` is a catch-all that matches ANY single
+      # path segment, and `proxy.ts`'s matcher deliberately excludes dotted
+      # paths from locale rewriting — so before the guard landed, `/ads.txt`,
+      # `/security.txt`, `/sitemap_index.xml` and every other dotted
+      # single-segment URL rendered the full homepage under a 200 (measured on
+      # the dev server; the request log shows no `proxy.ts:` timing for those
+      # paths, and a probe printed `lang="ads.txt"`).
+      #
+      # It sits here rather than in a test because nothing else can see the
+      # regression: delete the three-line guard and every page still renders,
+      # every type still checks, every link still resolves. The only symptom is
+      # a 200 where a 404 belongs, on URLs no test requests.
+      #
+      # Runs its own --self-test first (via the pnpm script). Not ceremony: the
+      # live tree is green by construction after the fix, so a passing run over
+      # real data cannot distinguish a working gate from one that approves
+      # everything. The self-test is where every limb is observed failing, and
+      # where the proxy condition is observed flipping the requirement off.
+      - name: Docs locale catch-all rejects non-locale segments
+        run: pnpm check:docs-locale-catch-all
+
       # #11050 route spellings taught in prose: every /api/v1 wire-path
       # literal in the published corpora (content/docs/** minus releases/,
       # plus skills/**) is judged against the route ledgers, and a literal

apps/docs/app/[lang]/layout.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import { RootProvider } from 'fumadocs-ui/provider/next';
-import { i18n } from '@/lib/i18n';
+import { notFound } from 'next/navigation';
+import { i18n, isSupportedLanguage } from '@/lib/i18n';
 
 // Language display names mapping
 const LANGUAGE_NAMES: Record<string, string> = {
@@ -16,6 +17,16 @@ export default async function LanguageLayout({
   children: ReactNode;
 }) {
   const { lang } = await params;
+
+  // `[lang]` is a catch-all: it matches ANY single path segment. Paths that
+  // contain a dot reach it unrewritten, because `proxy.ts`'s matcher excludes
+  // them from locale rewriting on purpose (static assets must not be
+  // rewritten) -- so `/ads.txt`, `/anything.html` and `/sitemap_index.xml`
+  // arrive here with `lang` set to that literal segment. Without this check
+  // every one of them renders the homepage under a 200, publishing an
+  // unbounded set of duplicate homepages at exactly the URLs crawlers probe.
+  // Declared locales are the contract; reject anything else.
+  if (!isSupportedLanguage(lang)) notFound();
 
   return (
     <RootProvider

apps/docs/lib/i18n.ts

@@ -15,3 +15,18 @@ export const i18n = defineI18n({
   // Hide locale prefix for default language (e.g., /docs instead of /en/docs)
   hideLocale: 'default-locale',
 });
+
+/**
+ * True when `value` is one of the locales declared above.
+ *
+ * The `[lang]` route segment is a catch-all: without this check it matches ANY
+ * single path segment and renders the homepage under it. Paths containing a dot
+ * are the reachable case, because `proxy.ts`'s matcher deliberately excludes
+ * them from locale rewriting (static assets must not be rewritten), so they
+ * arrive at `[lang]` with `lang` set to the literal segment — `"robots.txt"`,
+ * `"ads.txt"`, `"anything.html"`. Declared locales are the contract; this is
+ * where it is enforced.
+ */
+export function isSupportedLanguage(value: string): boolean {
+  return (i18n.languages as readonly string[]).includes(value);
+}

package.json

@@ -42,6 +42,7 @@
     "check:doc-anchors": "node scripts/check-doc-anchors.mjs --self-test && node scripts/check-doc-anchors.mjs",
     "check:docs-audit-scope": "node scripts/docs-audit/affected-docs.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs",
     "check:docs-redirects": "node scripts/check-docs-redirects.mjs --self-test && node scripts/check-docs-redirects.mjs",
+    "check:docs-locale-catch-all": "node scripts/check-docs-locale-catch-all.mjs --self-test && node scripts/check-docs-locale-catch-all.mjs",
     "check:docs-image-tag": "node scripts/check-docs-image-tag.mjs --self-test && node scripts/check-docs-image-tag.mjs",
     "check:docs-image-tag-sync": "node scripts/sync-docs-image-tags.mjs --self-test",
     "check:react-page-adapter-contract": "node scripts/check-react-page-adapter-contract.mjs --self-test && node scripts/check-react-page-adapter-contract.mjs",