From 88aed08357b7a463c56440d1f0b16722200ea843 Mon Sep 17 00:00:00 2001 From: IEvangelist <7679720+IEvangelist@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:20:07 -0600 Subject: [PATCH 01/11] Serve English in place of untranslated locale routes Untranslated locale routes are no longer built (~650 English copies per locale, ~3 GB of dist). StaticHost serves the English page in place at the locale URL, and a small client script localizes the chrome and shows the untranslated notice. - Starlight patch: skip fallback routes in getStaticPaths. - /locale-fallback/{locale}.json UI dictionaries and locales.json manifest. - hreflang alternates only list real translations. - StaticHost LocaleFallbackMiddleware (rewrite, Content-Language: en, in-locale redirects) sharing the canonical path index; astro dev mirrors it. - Unit, StaticHost, and E2E tests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/frontend/astro.config.mjs | 6 + .../locale-fallback-dev-integration.mjs | 67 ++++++++ src/frontend/config/translated-paths.mjs | 33 ++++ .../patches/@astrojs__starlight@0.41.3.patch | 15 ++ src/frontend/patches/README.md | 2 +- .../src/components/LocaleFallback.astro | 41 +++++ .../src/components/starlight/Head.astro | 4 + .../src/components/starlight/PageTitle.astro | 25 +++ src/frontend/src/env.d.ts | 2 + .../pages/locale-fallback/[locale].json.ts | 91 +++++++++++ .../src/pages/locale-fallback/locales.json.ts | 15 ++ src/frontend/src/route-data-middleware.ts | 21 +++ src/frontend/src/scripts/locale-fallback.ts | 153 ++++++++++++++++++ src/frontend/src/utils/locale-fallback.ts | 133 +++++++++++++++ src/frontend/src/utils/translated-routes.ts | 25 +++ .../tests/e2e/locale-fallback.spec.ts | 51 ++++++ src/frontend/tests/e2e/og-metadata.spec.ts | 4 +- .../tests/unit/locale-fallback.vitest.test.ts | 139 ++++++++++++++++ ...te-data-middleware-hreflang.vitest.test.ts | 22 ++- src/statichost/StaticHost/Program.cs | 5 + .../CanonicalPathRedirectExtensions.cs | 44 ++++- .../CanonicalPathRedirectMiddleware.cs | 8 +- .../Routing/CanonicalPathResolver.cs | 12 ++ .../Routing/LocaleFallbackMiddleware.cs | 54 +++++++ .../Routing/LocaleFallbackResolver.cs | 106 ++++++++++++ .../AgentReadinessTestServer.cs | 1 + tests/StaticHost.Tests/LocaleFallbackTests.cs | 113 +++++++++++++ 27 files changed, 1176 insertions(+), 16 deletions(-) create mode 100644 src/frontend/config/locale-fallback-dev-integration.mjs create mode 100644 src/frontend/config/translated-paths.mjs create mode 100644 src/frontend/src/components/LocaleFallback.astro create mode 100644 src/frontend/src/pages/locale-fallback/[locale].json.ts create mode 100644 src/frontend/src/pages/locale-fallback/locales.json.ts create mode 100644 src/frontend/src/scripts/locale-fallback.ts create mode 100644 src/frontend/src/utils/locale-fallback.ts create mode 100644 src/frontend/src/utils/translated-routes.ts create mode 100644 src/frontend/tests/e2e/locale-fallback.spec.ts create mode 100644 src/frontend/tests/unit/locale-fallback.vitest.test.ts create mode 100644 src/statichost/StaticHost/Routing/LocaleFallbackMiddleware.cs create mode 100644 src/statichost/StaticHost/Routing/LocaleFallbackResolver.cs create mode 100644 tests/StaticHost.Tests/LocaleFallbackTests.cs diff --git a/src/frontend/astro.config.mjs b/src/frontend/astro.config.mjs index c4b5f17828..1d30ad88fc 100644 --- a/src/frontend/astro.config.mjs +++ b/src/frontend/astro.config.mjs @@ -4,6 +4,8 @@ import { unified } from '@astrojs/markdown-remark'; import { sidebarTopics } from './config/sidebar/sidebar.topics.ts'; import { redirects } from './config/redirects.mjs'; import { locales } from './config/locales.ts'; +import { getTranslatedPaths } from './config/translated-paths.mjs'; +import { localeFallbackDevIntegration } from './config/locale-fallback-dev-integration.mjs'; import { headAttrs } from './config/head.attrs.ts'; import { socialConfig } from './config/socials.config.ts'; import { aspireProject } from './src/data/aspire-project.ts'; @@ -69,6 +71,9 @@ export default defineConfig({ define: { // Resolve filesystem-backed redirects before prerender modules are bundled. __ASPIRE_REDIRECT_PATHS__: JSON.stringify(Object.keys(redirects)), + // Untranslated locale routes aren't built (see the Starlight patch), so + // hreflang alternates only list localized routes that really exist. + __ASPIRE_TRANSLATED_PATHS__: JSON.stringify(getTranslatedPaths()), }, ...(staticHostUrl ? { @@ -246,6 +251,7 @@ export default defineConfig({ }), ...(isBuildTimingEnabled ? [buildTiming()] : []), aspireVersionPlaceholdersIntegration(), + localeFallbackDevIntegration(), ], build: { concurrency: buildConcurrency, diff --git a/src/frontend/config/locale-fallback-dev-integration.mjs b/src/frontend/config/locale-fallback-dev-integration.mjs new file mode 100644 index 0000000000..741e745a37 --- /dev/null +++ b/src/frontend/config/locale-fallback-dev-integration.mjs @@ -0,0 +1,67 @@ +// @ts-check +import { locales } from './locales.ts'; +import { getTranslatedPaths } from './translated-paths.mjs'; + +const localeSegments = Object.keys(locales) + .filter((key) => key !== 'root') + .map((key) => key.toLowerCase()); + +/** + * Path the dev server should render for `pathname`, mirroring StaticHost's + * `LocaleFallbackMiddleware`: untranslated locale routes (which the build no + * longer emits) render the English page in place. Returns `undefined` when the + * request needs no rewrite. + * + * @param {string} pathname + * @param {ReadonlySet} translatedPaths + * @returns {string | undefined} + */ +export function getLocaleFallbackDevPath(pathname, translatedPaths) { + const match = pathname.match(/^\/([^/]+)(\/.*)$/); + if (!match) return undefined; + + const [, segment, unlocalizedPath] = match; + if (!localeSegments.includes(segment.toLowerCase()) || unlocalizedPath === '/') { + return undefined; + } + + const lastSegment = unlocalizedPath.slice(unlocalizedPath.lastIndexOf('/') + 1); + const isMarkdown = lastSegment.endsWith('.md'); + // Only pages and their Markdown copies fall back; directory routes without a + // trailing slash are left for the dev server to redirect. + if (!unlocalizedPath.endsWith('/') && !isMarkdown) return undefined; + const pagePath = isMarkdown ? `${pathname.slice(0, -'.md'.length)}/` : pathname; + if (translatedPaths.has(pagePath.toLowerCase())) return undefined; + + return unlocalizedPath; +} + +/** + * Serves the English page in place of untranslated locale routes during + * `astro dev`, so local development and E2E runs match production. + * + * @returns {import('astro').AstroIntegration} + */ +export function localeFallbackDevIntegration() { + return { + name: 'aspire-locale-fallback-dev', + hooks: { + 'astro:server:setup': ({ server }) => { + server.middlewares.use((req, res, next) => { + const url = new URL(req.url ?? '/', 'http://localhost'); + // Re-read on each locale request so new translations are picked up without a restart. + const rewrittenPath = localeSegments.some((locale) => + url.pathname.toLowerCase().startsWith(`/${locale}/`) + ) + ? getLocaleFallbackDevPath(url.pathname, new Set(getTranslatedPaths())) + : undefined; + if (rewrittenPath) { + req.url = `${rewrittenPath}${url.search}`; + res.setHeader('Content-Language', 'en'); + } + next(); + }); + }, + }, + }; +} diff --git a/src/frontend/config/translated-paths.mjs b/src/frontend/config/translated-paths.mjs new file mode 100644 index 0000000000..495b2b987c --- /dev/null +++ b/src/frontend/config/translated-paths.mjs @@ -0,0 +1,33 @@ +// @ts-check +import { existsSync, readdirSync } from 'node:fs'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { locales } from './locales.ts'; + +const defaultDocsDir = fileURLToPath(new URL('../src/content/docs/', import.meta.url)); + +/** + * Route paths (for example `/ja/get-started/install-cli/`) of every page that + * has a real translation in a non-default locale. Untranslated locale routes + * are not built; the static host serves the English page in place. + * + * @param {string} [docsDir] + * @returns {string[]} + */ +export function getTranslatedPaths(docsDir = defaultDocsDir) { + const paths = new Set(); + for (const locale of Object.keys(locales)) { + if (locale === 'root') continue; + const localeDir = join(docsDir, locale); + if (!existsSync(localeDir)) continue; + + for (const file of readdirSync(localeDir, { recursive: true, encoding: 'utf8' })) { + if (!/\.mdx?$/i.test(file)) continue; + const slug = `${locale}/${file.replace(/\\/g, '/').replace(/\.mdx?$/i, '')}` + .toLowerCase() + .replace(/\/index$/, ''); + paths.add(`/${slug}/`); + } + } + return [...paths].sort(); +} diff --git a/src/frontend/patches/@astrojs__starlight@0.41.3.patch b/src/frontend/patches/@astrojs__starlight@0.41.3.patch index ab1f36b687..6973e9c0ad 100644 --- a/src/frontend/patches/@astrojs__starlight@0.41.3.patch +++ b/src/frontend/patches/@astrojs__starlight@0.41.3.patch @@ -112,3 +112,18 @@ index d8c80d826995d6c8ce598aa618ddf7ea575ecadc..ec1f9b15f677f0c7ae98160eef1c9dc7 } } customElements.define('site-search', SiteSearch); +diff --git a/utils/routing/index.ts b/utils/routing/index.ts +index c4af65f6c1c711399b58a984a3301ff56e39e2d5..042e435c4cbc0aabe300f5f42ee359630d8aa0c6 100644 +--- a/utils/routing/index.ts ++++ b/utils/routing/index.ts +@@ -96,7 +96,9 @@ export function getRouteBySlugParam(slugParam: string | undefined): Route | unde + } + + function getPaths(): Path[] { +- return routes.map((route) => ({ ++ // Fallback pages aren't emitted: the host serves the default-locale page in place. ++ const pageRoutes = routes.filter((route) => !route.isFallback); ++ return pageRoutes.map((route) => ({ + params: { slug: slugToParam(route.id) }, + props: route, + })); diff --git a/src/frontend/patches/README.md b/src/frontend/patches/README.md index e0c9d212ce..3270999fca 100644 --- a/src/frontend/patches/README.md +++ b/src/frontend/patches/README.md @@ -6,7 +6,7 @@ regenerated (`bun patch `, edit, then `bun patch --commit `) | Patch | Why | | --- | --- | -| `@astrojs__starlight@0.41.3.patch` | Starlight search must initialize and dispose per element across `ClientRouter` swaps, not only on `DOMContentLoaded` ([#1673](https://github.com/microsoft/aspire.dev/issues/1673)). | +| `@astrojs__starlight@0.41.3.patch` | Starlight search must initialize and dispose per element across `ClientRouter` swaps, not only on `DOMContentLoaded` ([#1673](https://github.com/microsoft/aspire.dev/issues/1673)). Also skips untranslated locale fallback routes: StaticHost serves the English page in place (`LocaleFallbackMiddleware`) and `src/scripts/locale-fallback.ts` localizes the chrome, instead of emitting a full English copy per locale. | | `astro@7.4.1.patch` | Imported SVGs are callable components that can't be structured-cloned, so the parallel prerender worker keeps only their image metadata before posting results. | | `starlight-page-actions@0.7.0.patch` | Keeps accessible actions across page swaps, allows readable heading markup, and points Markdown actions on untranslated locale pages to the default-locale Markdown. | | `starlight-plugin-icons@1.1.6.patch` | Temporary network-resilience fix for `getMaterialIconsData`: falls back to the vendored `.starlight-icons` cache when the icon-data fetch fails. Remove once [Rettend/starlight-plugin-icons#9](https://github.com/Rettend/starlight-plugin-icons/pull/9) is merged and released. | diff --git a/src/frontend/src/components/LocaleFallback.astro b/src/frontend/src/components/LocaleFallback.astro new file mode 100644 index 0000000000..ae10615011 --- /dev/null +++ b/src/frontend/src/components/LocaleFallback.astro @@ -0,0 +1,41 @@ +--- +import { fallbackLocales, getLocaleFallbackDictionaryPath } from '@utils/locale-fallback'; + +/* + * Rendered only on default-locale (English) pages. The static host serves + * those pages in place of untranslated locale routes such as + * `/de/get-started/install-cli/`; this marks the document before first paint + * so the chrome stays hidden until `@scripts/locale-fallback` localizes it. + */ +const dictionaryPathTemplate = getLocaleFallbackDictionaryPath('{locale}'); +--- + + + + diff --git a/src/frontend/src/components/starlight/Head.astro b/src/frontend/src/components/starlight/Head.astro index a56cafaece..435f0edb8b 100644 --- a/src/frontend/src/components/starlight/Head.astro +++ b/src/frontend/src/components/starlight/Head.astro @@ -6,6 +6,7 @@ import poppinsBold from '@fontsource/poppins/files/poppins-latin-700-normal.woff import DefaultHead from '@astrojs/starlight/components/Head.astro'; import { ClientRouter } from 'astro:transitions'; import AccessibleCodeButtons from '../AccessibleCodeButtons.astro'; +import LocaleFallback from '../LocaleFallback.astro'; import SiteTour from '../SiteTour.astro'; import { getStructuredData } from '@utils/structured-data'; import { getOgMetadata } from '@utils/page-metadata'; @@ -21,6 +22,8 @@ const route = Astro.locals?.starlightRoute; const entryId = route?.entry?.id; const path = route?.entry?.filePath; const isSiteTourEnabled = import.meta.env.PUBLIC_ENABLE_SITE_TOUR === 'true'; +// English pages are also served in place of untranslated locale routes. +const isDefaultLocalePage = route ? !route.locale : true; const structuredData = route ? getStructuredData(route, Astro.url, Astro.site) : undefined; const ogMetadata = route ? getOgMetadata(route, Astro.url, Astro.site) : undefined; @@ -67,6 +70,7 @@ function computeSourceUrl() { }); +{isDefaultLocalePage && } { ogMetadata && ( diff --git a/src/frontend/src/components/starlight/PageTitle.astro b/src/frontend/src/components/starlight/PageTitle.astro index 2751f60ee8..bdda6d7c99 100644 --- a/src/frontend/src/components/starlight/PageTitle.astro +++ b/src/frontend/src/components/starlight/PageTitle.astro @@ -6,6 +6,9 @@ import ReadableText from '@components/ReadableText.astro'; const currentPath = Astro.url.pathname.replace(/\/$/, '').replace(/^\//, ''); const isDevDirectory = ['hub', 'hub/browse', 'hub/glossary'].includes(currentPath); +// The static host also serves English pages in place of untranslated locale +// routes; `@scripts/locale-fallback` then shows this notice in that locale. +const hasLocaleFallbackNotice = !Astro.locals.starlightRoute.locale; --- {isDevDirectory && ( @@ -42,7 +45,29 @@ const isDevDirectory = ['hub', 'hub/browse', 'hub/glossary'].includes(currentPat )} +{hasLocaleFallbackNotice && ( + +)} +