Strip locale prefix from API reference sidebar links (#755)

API reference pages under /reference/api/ are only generated for the default (English) locale because they're produced from package metadata rather than translated content. However, Starlight's i18n auto-prefixes the active locale to sidebar links (e.g. /it/reference/api/csharp/), which produces 404s for any non-default locale.

Rather than redirecting at request time, fix the source: extend the existing route-data middleware to walk the sidebar tree and rewrite hrefs that match the localized API reference pattern back to their canonical, locale-stripped path. The sidebar then never emits a link that 404s, regardless of the active locale.

Reuses stripApiReferenceLocale from src/utils/api-reference-routes (added in #754) so locale detection stays in one place.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: IEvangelist

src/frontend/src/route-data-middleware.ts

@@ -1,4 +1,5 @@
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+import { stripApiReferenceLocale } from './utils/api-reference-routes';
 
 /**
  * Custom route middleware that applies implicit pagination rules:
@@ -22,6 +23,15 @@ export const onRequest = defineRouteMiddleware((context) => {
 
   const { entry, pagination, sidebar } = routeData;
 
+  // --- Step 0: Canonicalize API reference sidebar links ---
+  // API reference pages under /reference/api/ are only generated for the default
+  // (English) locale because they're produced from package metadata rather than
+  // translated content. Starlight auto-prefixes the active locale to sidebar
+  // links, which produces 404s for non-default locales (e.g.
+  // /it/reference/api/csharp/). Rewrite those hrefs to point to the canonical
+  // English path so the sidebar never emits a link that 404s.
+  canonicalizeApiReferenceLinks(sidebar);
+
   // --- Step 1: Group boundary rules ---
   const location = findCurrentPage(sidebar);
   if (location) {
@@ -81,10 +91,33 @@ export const onRequest = defineRouteMiddleware((context) => {
 interface SidebarEntry {
   type: string;
   label: string;
+  href?: string;
   isCurrent?: boolean;
   entries?: SidebarEntry[];
 }
 
+/**
+ * Walk the sidebar tree and rewrite any link whose href is a localized API
+ * reference path (e.g. `/it/reference/api/csharp/`) to the canonical,
+ * locale-stripped path (e.g. `/reference/api/csharp/`).
+ */
+function canonicalizeApiReferenceLinks(entries: SidebarEntry[]): void {
+  for (const entry of entries) {
+    if (!entry) continue;
+
+    if (entry.type === 'link' && typeof entry.href === 'string') {
+      const canonical = stripApiReferenceLocale(entry.href);
+      if (canonical) {
+        entry.href = canonical;
+      }
+    }
+
+    if (entry.entries) {
+      canonicalizeApiReferenceLinks(entry.entries);
+    }
+  }
+}
+
 /**
  * Recursively find the current page (`isCurrent === true`) in the sidebar tree
  * and return its sibling entries along with its index within them.