Skip to content

Serve English in place of untranslated locale routes - #2214

Merged
David Pine (IEvangelist) merged 12 commits into
mainfrom
dapine-microsoft-locale-fallback-served-in-place
Nov 20, 2026
Merged

David Pine (IEvangelist) merged 12 commits into
mainfrom
dapine-microsoft-locale-fallback-served-in-place

Conversation

@IEvangelist

Copy link
Copy Markdown
Member

Summary

Part of a series of changes to shrink the frontend container image (the Astro dist is about 9.8 GB). This one targets untranslated locale pages.

Today Starlight builds a full English copy of every page for each locale that hasn't translated it. That's roughly 650 pages per locale across 13 locales, about 3 GB. Only ja has real translations. This PR stops building those copies. StaticHost serves the English page at the locale URL instead, without a redirect, and a small script switches the menus and labels to the reader's language and shows the "not translated" notice.

  • Starlight patch (patches/@astrojs__starlight@0.41.3.patch): getStaticPaths skips fallback routes (isFallback). Starlight's internal route list is unchanged, so sidebars and pagination still link within the locale. Upstream request for a configurable option: Option to skip generating fallback pages for untranslated content withastro/starlight#4419. The local patch stays until that ships.
  • Translated-route list: config/translated-paths.mjs builds the list from src/content/docs/{locale} and passes it in through the __ASPIRE_TRANSLATED_PATHS__ define. route-data-middleware.ts drops hreflang alternates that point to untranslated locale URLs. Canonical URLs stay English.
  • Dictionaries: /locale-fallback/{locale}.json maps English interface text to each locale. It covers Starlight and plugin UI strings, our custom i18n keys, sidebar labels, translated page titles, and the untranslated-content notice. /locale-fallback/locales.json lists the locales.
  • StaticHost: the new LocaleFallbackMiddleware runs after canonical-path redirects and before agent readiness, default files, and routing. When /{locale}/x doesn't exist but /x does, it rewrites the path internally and sets Content-Language: en. A missing trailing slash or wrong casing gets a 308 redirect that keeps the locale. Markdown requests (Accept: text/markdown and /de/x.md) return the English Markdown. The middleware turns itself off when the manifest is missing. It shares the canonical path index, so the web root is scanned once.
  • Client:
    • An inline head script marks the document and preloads the dictionary. The menus and sidebar stay hidden until the translated text is applied, or for 2 seconds at most.
    • src/scripts/locale-fallback.ts swaps the text and aria-labels, inserts a notice styled like Starlight's, keeps menu and sidebar links in the locale, and handles in-site navigation without full page reloads.
  • Dev server: config/locale-fallback-dev-integration.mjs does the same rewrite in astro dev, so local runs match production.

Known trade-off: <html lang> stays en, and only translated elements get lang="{locale}". Setting the whole page to the locale would make Pagefind load that locale's index, which is now nearly empty. As a result, search results on /de/ pages link to English URLs, and clicking one takes the reader out of the locale.

Third-party links and affiliations

None. The only link points to the upstream Starlight discussion.

Validation

  • dotnet test tests/StaticHost.Tests: passed (380 tests, including 7 new LocaleFallbackTests).
  • vitest run --config vitest.config.ts: 1511 passed, 1 failed (incremental-build.vitest.test.ts). It failed with spawn bun ENOENT because bun isn't on PATH on the dev machine. It also fails on main there, so it's unrelated to this change.
  • Targeted unit tests passed: locale-fallback, route-data-middleware-hreflang, route-data-middleware-sidebar-locale, locale-routes, language-switch, and astro-vite-config.
  • playwright test (desktop-chromium and mobile-chromium against astro dev) passed for:
    • the new tests/e2e/locale-fallback.spec.ts
    • the locale cases in api-markdown-routes, dev-layout, og-metadata, search-visual-parity, and ui-regressions
    • the axe check in mobile-ux on /de/get-started/first-app/
  • Updated tests:
    • Two og-metadata cases expected built fallback pages (/da/ and /uk/fundamentals/telemetry/). Those pages are no longer built, so I removed the cases.
    • The hreflang expectations now list only real translations.
  • eslint passed on the changed files. prettier --check passed with --end-of-line auto, because the working copy has CRLF line endings.
  • I didn't run bun run build locally. CI will run the first full build and the first E2E run against StaticHost.

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>
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2214. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2214 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

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

Copy link
Copy Markdown
Member Author

Combined validation: real aspire publish image

I merged #2215, #2214, #2213 and #2216 into the ADO deploy branch locally, then ran the same steps as pipelines/build.yml: bicep restore followed by aspire publish -o .generated (the Ev2 publish step). The resulting image was loaded with docker load and run as a container in Production mode with Redis.

Before After all four PRs
Ev2ServiceArtifactsRoot/Images/aspiredev.tar.gz ~4 GB 1.76 GB
Built HTML pages 38,344 29,134
Site output (dist) 9.8 GB 3.73 GB
wwwroot in image n/a 3.73 GB originals + 0.68 GB .br

The container starts in 11 s, /healthz returns 200, and idle memory is about 2 GB, likely from the 134 MB staticwebassets.endpoints.json.

Testing against the container

  • Layout check: 35 representative layouts (docs, splash, hub, 404, /de/ fallback, /ja/ translated, C#/TS/Go API landing, package, type and member pages) on desktop and mobile. Every page returned the expected status, with no failed requests and no page errors.
  • Full Playwright suite, CI=1 bunx playwright test, all 3 projects, reusing the container on :4322: 1,632 passed, 5 failed, 2 flaky, 107 skipped. Failures are triaged below.
  • Manual testing of the running container found no issues.
    This PR: saves about 3 GB of dist. Untranslated /de/... pages are served in place with German chrome and the Dieser Inhalt ist noch nicht in deiner Sprache verfügbar. banner; Content-Language: en; /de/x.md works. The combined build found that the links validator rejected 148 locale links to routes that are no longer built. That's fixed here in 0b3a81b plus tests in 58d80e9. Known follow-up: redirect pages under /de/ forward to the English URL (previously these returned 404).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
CI starts StaticHost before it unpacks the site, so reading the locale manifest at
startup left the fallback disabled and every untranslated locale route returned 404.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Clients fetch /locale-fallback/{locale}.json?v=<hash>, a short SHA-256 of the
emitted dictionaries, so the edge can cache them indefinitely.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…partial web root

StaticHost starts before CI unpacks the site and treats the locale manifest as the sign that the web root is complete. Extracting it under a temporary name and moving it into place afterwards closes a race that left pages 404ing for a whole E2E shard.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Rename CanonicalPathRedirectExtensions to StaticRoutingExtensions now that it also wires locale fallback.
- Check for the locale manifest before scanning the web root and rescan if it appears mid-scan, so a partial snapshot is never marked final.
- Validate links to translated locale pages instead of excluding them whenever the English page exists.
- Leave configured redirect sources to Astro in the dev locale fallback rewrite.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 20, 2026 18:11
Copilot AI balanced review requested due to automatic review settings November 20, 2026 18:11
…le-fallback-served-in-place

# Conflicts:
#	src/frontend/patches/@astrojs__starlight@0.41.3.patch
#	src/frontend/patches/README.md

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Localization still leaves accessible-name language, initialized tooltips, and lazy-loaded search controls incorrect, while client-side navigation and cached-dictionary behavior lack test coverage.

4 open issues
What changed in this PR

Reduces the frontend build size by serving English pages at untranslated locale URLs instead of generating duplicate pages. Client-side dictionaries localize navigation and interface labels while preserving English content.

Changes:

  • Skip untranslated Starlight routes and limit hreflang alternates to real translations.
  • Add StaticHost and development-server fallback routing, including Markdown support.
  • Add localized interface dictionaries, fallback notices, tests, and CI extraction coordination.
File Description
tests/​StaticHost.Tests/​LocaleFallbackTests.cs Tests fallback routing, redirects, Markdown, and index refresh.
tests/​StaticHost.Tests/​AgentReadinessTestServer.cs Adds fallback middleware to the test pipeline.
src/​statichost/​StaticHost/​Routing/​StaticWebRootIndex.cs Shares a retryable static-file index.
src/​statichost/​StaticHost/​Routing/​StaticRoutingExtensions.cs Registers routing middleware with the shared index.
src/​statichost/​StaticHost/​Routing/​LocaleFallbackResolver.cs Resolves locale requests to English files.
src/​statichost/​StaticHost/​Routing/​LocaleFallbackMiddleware.cs Applies fallback rewrites and language headers.
src/​statichost/​StaticHost/​Routing/​CanonicalPathResolver.cs Exposes existing-path lookup.
src/​statichost/​StaticHost/​Routing/​CanonicalPathRedirectMiddleware.cs Uses the shared path index.
src/​statichost/​StaticHost/​Routing/​CanonicalPathRedirectExtensions.cs Removes registration superseded by shared extensions.
src/​statichost/​StaticHost/​Program.cs Enables fallback before content-serving middleware.
src/​frontend/​tests/​unit/​route-data-middleware-hreflang.vitest.test.ts Updates alternate-language expectations.
src/​frontend/​tests/​unit/​locale-fallback.vitest.test.ts Tests dictionaries, links, and route helpers.
src/​frontend/​tests/​e2e/​og-metadata.spec.ts Removes expectations for generated fallback pages.
src/​frontend/​tests/​e2e/​locale-fallback.spec.ts Checks fallback rendering and localized interface text.
src/​frontend/​src/​utils/​translated-routes.ts Identifies routes backed by translations.
src/​frontend/​src/​utils/​locale-fallback.ts Defines dictionary and localization helpers.
src/​frontend/​src/​utils/​locale-fallback-version.ts Generates dictionary content hashes.
src/​frontend/​src/​utils/​locale-fallback-dictionary.ts Builds localized interface dictionaries.
src/​frontend/​src/​scripts/​locale-fallback.ts Localizes interface text, links, and notices.
src/​frontend/​src/​route-data-middleware.ts Removes untranslated hreflang alternates.
src/​frontend/​src/​pages/​locale-fallback/​locales.json.ts Emits the supported-locale manifest.
src/​frontend/​src/​pages/​locale-fallback/​[locale].json.ts Emits per-locale dictionaries.
src/​frontend/​src/​env.d.ts Declares the translated-route build constant.
src/​frontend/​src/​components/​starlight/​PageTitle.astro Adds the fallback-notice template and styling.
src/​frontend/​src/​components/​starlight/​Head.astro Includes fallback support on English pages.
src/​frontend/​src/​components/​LocaleFallback.astro Preloads dictionaries and temporarily hides untranslated interface elements.
src/​frontend/​patches/​README.md Documents the expanded Starlight patch.
src/​frontend/​patches/​@astrojs__starlight@0.41.3.patch Excludes fallback routes from generated pages.
src/​frontend/​config/​translated-paths.mjs Collects translated routes from content files.
src/​frontend/​config/​locale-fallback-dev-integration.mjs Adds development-server fallback rewrites.
src/​frontend/​config/​links-validator-exclude.mjs Recognizes valid fallback destinations during link validation.
src/​frontend/​astro.config.mjs Wires route data, validation, and development integration.
.github/​workflows/​frontend-build.yml Publishes the manifest after site extraction completes.

Review effort: Balanced

…pages

- Update Tippy tooltip content (and its language) when the dictionary arrives after tooltips initialized.
- Set lang on icon-only controls whose attributes are translated.
- Defer Pagefind initialization until the fallback dictionary localizes site-search's data-translations and data-ui-lang, keeping the English index.
- Add E2E coverage for tooltips, icon-only lang, the lazily initialized search UI, and click-driven ClientRouter navigation across translated, fallback, and English pages.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Switching <html lang> while Pagefind UI mounted didn't localize its strings. Read Pagefind's per-language UI strings from the installed @pagefind/default-ui at build time, include them in the fallback dictionary's search translations, and drop the lang switch from the Starlight patch. The English index is unchanged.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) merged commit a01bf08 into main Nov 20, 2026
21 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the dapine-microsoft-locale-fallback-served-in-place branch November 20, 2026 19:15
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.

4 participants