alepha 0.22.0 → 0.23.0

package/src/react/i18n/__tests__/I18nProvider.spec.ts

@@ -449,6 +449,95 @@ describe("I18nProvider", () => {
     });
   });
 
+  describe("server-side language autodetect (Accept-Language)", () => {
+    /**
+     * Injects a real, dictionary-populated `I18nProvider` and exposes the
+     * protected resolution used by the `server:onRequest` hook, so the priority
+     * (cookie → header → fallback) can be unit-tested against a true registry.
+     */
+    const setup = (AppClass: new () => unknown) => {
+      const alepha = Alepha.create().with(AlephaReactI18n);
+      alepha.inject(AppClass as any);
+      const i18n = alepha.inject(I18nProvider);
+      return {
+        i18n,
+        resolve: (cookieLang?: string, headerLang?: string): string =>
+          (i18n as any).resolveRequestLang(cookieLang, headerLang),
+      };
+    };
+
+    class App {
+      en = $dictionary({
+        lazy: async () => ({ default: { hello: "Hello" } }),
+      });
+
+      fr = $dictionary({
+        lazy: async () => ({ default: { hello: "Bonjour" } }),
+      });
+    }
+
+    test("uses the Accept-Language header when no cookie is set", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, "fr")).toBe("fr");
+    });
+
+    test("lets a manually-selected cookie win over the header", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve("en", "fr")).toBe("en");
+    });
+
+    test("falls back when the header language is not registered", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, "de")).toBe("en");
+    });
+
+    test("falls back when neither cookie nor header is present", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, undefined)).toBe("en");
+    });
+
+    test("normalizes a region-qualified header to a registered base language", ({
+      expect,
+    }) => {
+      expect(setup(App).resolve(undefined, "fr-FR")).toBe("fr");
+    });
+
+    test("prefers an exact region match when one is registered", ({
+      expect,
+    }) => {
+      class RegionApp {
+        enUS = $dictionary({
+          lang: "en-US",
+          lazy: async () => ({ default: { color: "color" } }),
+        });
+
+        fr = $dictionary({
+          lazy: async () => ({ default: { color: "couleur" } }),
+        });
+      }
+
+      expect(setup(RegionApp).resolve(undefined, "en-US")).toBe("en-US");
+    });
+
+    test("ignores the header when autoDetect is disabled", ({ expect }) => {
+      const { i18n, resolve } = setup(App);
+      i18n.options.autoDetect = false;
+      expect(resolve(undefined, "fr")).toBe("en");
+    });
+
+    test("still honours a manual cookie when autoDetect is disabled", ({
+      expect,
+    }) => {
+      const { i18n, resolve } = setup(App);
+      i18n.options.autoDetect = false;
+      expect(resolve("fr", "en")).toBe("fr");
+    });
+  });
+
   test("should handle partial interpolation args", async ({ expect }) => {
     class App {
       en = $dictionary({

package/src/react/i18n/__tests__/locale-routing.spec.ts

@@ -0,0 +1,107 @@
+import { Alepha } from "alepha";
+import {
+  $page,
+  AlephaReactRouter,
+  ReactPageProvider,
+  RouterLocaleProvider,
+} from "alepha/react/router";
+import { ServerRouterProvider } from "alepha/server";
+import { describe, test } from "vitest";
+import { AlephaReactI18n } from "../index.ts";
+import { $dictionary } from "../primitives/$dictionary.ts";
+import { I18nProvider } from "../providers/I18nProvider.ts";
+
+/**
+ * End-to-end wiring of locale-prefix routing (`routing: "prefix"`) across the
+ * i18n and router modules: configuration, outbound URL prefixing, and the
+ * URL-as-source-of-truth language resolution.
+ */
+describe("locale-prefix routing", () => {
+  class App {
+    en = $dictionary({
+      lazy: async () => ({ default: { hi: "Hi" } }),
+    });
+    fr = $dictionary({
+      lazy: async () => ({ default: { hi: "Salut" } }),
+    });
+    about = $page({
+      name: "about",
+      path: "/about",
+      component: () => "about",
+    });
+  }
+
+  // Everything is injected BEFORE start() — the DI container locks once started.
+  const start = async (routing: "none" | "prefix") => {
+    const alepha = Alepha.create()
+      .with(AlephaReactRouter)
+      .with(AlephaReactI18n);
+    alepha.inject(App);
+    const i18n = alepha.inject(I18nProvider);
+    const locale = alepha.inject(RouterLocaleProvider);
+    const pages = alepha.inject(ReactPageProvider);
+    const server = alepha.inject(ServerRouterProvider);
+    i18n.options.routing = routing;
+    await alepha.start();
+    return { alepha, i18n: i18n as any, locale, pages, server };
+  };
+
+  test("i18n configures the router locale provider from its dictionaries", async ({
+    expect,
+  }) => {
+    const { locale } = await start("prefix");
+    expect(locale.enabled).toBe(true);
+    expect(locale.defaultLocale).toBe("en");
+    expect(locale.locales).toEqual(["en", "fr"]);
+    expect(locale.prefixedLocales).toEqual(["fr"]);
+  });
+
+  test("generated URLs carry the active locale prefix (default stays bare)", async ({
+    expect,
+  }) => {
+    const { pages, locale } = await start("prefix");
+
+    // default locale → unprefixed
+    expect(pages.pathname("about")).toBe("/about");
+
+    // active locale fr → prefixed
+    locale.current = "fr";
+    expect(pages.pathname("about")).toBe("/fr/about");
+  });
+
+  test("the URL locale wins over cookie and Accept-Language", async ({
+    expect,
+  }) => {
+    const { i18n } = await start("prefix");
+
+    // url prefix beats a conflicting cookie + header
+    expect(i18n.resolveRequestLang("en", "en", "fr")).toBe("fr");
+    // an unprefixed path resolves to the default locale (no redirect)
+    expect(i18n.detectUrlLocale("/about")).toBe("en");
+    expect(i18n.detectUrlLocale("/fr/about")).toBe("fr");
+  });
+
+  test("registers prefixed server route variants for non-default locales", async ({
+    expect,
+  }) => {
+    const { server } = await start("prefix");
+    const paths = server.getRoutes().map((route) => route.path);
+
+    expect(paths).toContain("/about");
+    expect(paths).toContain("/fr/about");
+    // the default locale is never prefixed
+    expect(paths).not.toContain("/en/about");
+  });
+
+  test("stays inert when routing is left as 'none'", async ({ expect }) => {
+    const { i18n, pages, locale, server } = await start("none");
+
+    expect(locale.enabled).toBe(false);
+    expect(pages.pathname("about")).toBe("/about");
+    expect(i18n.detectUrlLocale("/fr/about")).toBeUndefined();
+
+    const paths = server.getRoutes().map((route) => route.path);
+    expect(paths).toContain("/about");
+    expect(paths).not.toContain("/fr/about");
+  });
+});

package/src/react/i18n/providers/I18nProvider.ts

@@ -1,6 +1,9 @@
 import { $hook, $inject, Alepha, TypeBoxError, TypeProvider, t } from "alepha";
 import { type DateTime, DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
+// Locale-prefix routing is optional: the router module (one-directional
+// dependency, `i18n → router`) is only consulted when it is also registered.
+import { RouterLocaleProvider } from "alepha/react/router";
 import { $cookie } from "alepha/server/cookies";
 import type { ServiceDictionary } from "../hooks/useI18n.ts";
 
@@ -26,10 +29,50 @@ export class I18nProvider<
     translations: Record<string, string>;
   }> = [];
 
-  options = {
+  options: {
+    fallbackLang: string;
+    autoDetect: boolean;
+    routing: "none" | "prefix";
+  } = {
     fallbackLang: "en",
+    /**
+     * When true (the default), the UI language for a first-time visitor (one
+     * with no `lang` cookie) is detected server-side from the `Accept-Language`
+     * header. A manually-selected language (the cookie) always takes
+     * precedence, so this never overrides an explicit user choice. Set to false
+     * to always start in `fallbackLang` regardless of the browser's preferred
+     * language.
+     */
+    autoDetect: true,
+    /**
+     * URL strategy for languages:
+     * - `"none"` (default): language lives in a cookie; URLs are not localized.
+     * - `"prefix"`: each non-default language gets a path prefix (`/fr/about`),
+     *   making every language a distinct, crawlable URL for SEO. The default
+     *   language (`fallbackLang`) stays unprefixed. Requires the router module.
+     *   The URL becomes the source of truth for language (it wins over the
+     *   cookie / `Accept-Language`), and there is no automatic redirect.
+     */
+    routing: "none",
   };
 
+  /**
+   * Lazily-resolved locale-prefix router integration. Present only when both
+   * the router module is registered AND `routing: "prefix"` was configured —
+   * otherwise i18n stays fully standalone.
+   */
+  protected localeProviderResolved = false;
+  protected localeProviderRef?: RouterLocaleProvider;
+  protected get localeProvider(): RouterLocaleProvider | undefined {
+    if (!this.localeProviderResolved) {
+      this.localeProviderResolved = true;
+      if (this.alepha.has(RouterLocaleProvider)) {
+        this.localeProviderRef = this.alepha.inject(RouterLocaleProvider);
+      }
+    }
+    return this.localeProviderRef;
+  }
+
   public dateFormat: { format: (value: Date) => string } =
     new Intl.DateTimeFormat(this.lang);
 
@@ -50,22 +93,103 @@ export class I18nProvider<
     this.refreshLocale();
   }
 
+  /**
+   * Configure locale-prefix routing on the router, before the SSR routes are
+   * registered (`priority: "first"` runs ahead of the router's own `configure`
+   * hook). No-op unless `routing: "prefix"` and the router module is present.
+   */
+  protected readonly onConfigure = $hook({
+    on: "configure",
+    priority: "first",
+    handler: () => {
+      const localeProvider = this.localeProvider;
+      if (this.options.routing === "prefix" && localeProvider) {
+        localeProvider.configure({
+          enabled: true,
+          defaultLocale: this.fallbackLang,
+          locales: this.languages,
+        });
+      }
+    },
+  });
+
   protected readonly onRender = $hook({
     on: "server:onRequest",
     priority: "last",
     handler: async ({ request }) => {
-      this.alepha.store.set("alepha.react.i18n.lang", this.cookie.get(request));
+      this.alepha.store.set(
+        "alepha.react.i18n.lang",
+        this.resolveRequestLang(
+          this.cookie.get(request),
+          request.language,
+          this.detectUrlLocale(request.url?.pathname),
+        ),
+      );
     },
   });
 
+  /**
+   * Detects the language carried by the request URL when `routing: "prefix"` is
+   * active. Returns the locale for any URL (the prefixed one for `/fr/...`, the
+   * default for an unprefixed path), or `undefined` when prefix routing is off.
+   */
+  protected detectUrlLocale(pathname: string | undefined): string | undefined {
+    const localeProvider = this.localeProvider;
+    if (localeProvider?.enabled && pathname) {
+      return localeProvider.detect(pathname).locale || undefined;
+    }
+    return undefined;
+  }
+
+  /**
+   * Resolves the UI language for an incoming server request.
+   *
+   * Priority:
+   * 0. the URL locale prefix (`routing: "prefix"`) — the URL is the source of
+   *    truth and wins over everything, with no redirect;
+   * 1. the `lang` cookie — a language the user manually selected;
+   * 2. the `Accept-Language` header (when `autoDetect` is enabled) — but only
+   *    when the detected language is actually registered, so we never switch to
+   *    a locale we have no dictionary for. A region-qualified header (`en-US`)
+   *    matches an exact registration first, then its base language (`en`);
+   * 3. `fallbackLang`.
+   */
+  protected resolveRequestLang(
+    cookieLang: string | undefined,
+    headerLang: string | undefined,
+    urlLocale?: string,
+  ): string {
+    if (urlLocale) {
+      return urlLocale;
+    }
+
+    if (cookieLang) {
+      return cookieLang;
+    }
+
+    if (this.options.autoDetect && headerLang) {
+      const registered = this.languages;
+      for (const candidate of [headerLang, headerLang.split("-")[0]]) {
+        if (registered.includes(candidate)) {
+          return candidate;
+        }
+      }
+    }
+
+    return this.fallbackLang;
+  }
+
   protected readonly onStart = $hook({
     on: "start",
     handler: async () => {
       if (this.alepha.isBrowser()) {
-        // get cookie lang
-        const cookieLang = this.cookie.get();
-        if (cookieLang) {
-          this.alepha.store.set("alepha.react.i18n.lang", cookieLang);
+        // In prefix mode the URL (hydrated into the lang state by the server)
+        // is the source of truth, so the cookie must not override it.
+        if (!this.localeProvider?.enabled) {
+          const cookieLang = this.cookie.get();
+          if (cookieLang) {
+            this.alepha.store.set("alepha.react.i18n.lang", cookieLang);
+          }
         }
 
         for (const item of this.registry) {
@@ -94,26 +218,61 @@ export class I18nProvider<
     TypeProvider.setLocale(this.lang);
   }
 
-  public setLang = async (lang: string) => {
+  /**
+   * Activates a language: lazily loads its dictionaries (browser), updates the
+   * lang state, and refreshes the locale-bound formatters. Does NOT persist a
+   * cookie or navigate — that is the caller's concern.
+   */
+  protected applyLang = async (lang: string) => {
     if (this.alepha.isBrowser()) {
       for (const item of this.registry) {
-        if (lang === item.lang) {
-          if (Object.keys(item.translations).length > 0) {
-            continue; // already loaded
-          }
+        if (lang === item.lang && Object.keys(item.translations).length === 0) {
           item.translations = await item.loader();
         }
       }
-      this.cookie.set(lang);
     }
 
     this.alepha.store.set("alepha.react.i18n.lang", lang);
     this.refreshLocale();
   };
 
+  public setLang = async (lang: string) => {
+    const localeProvider = this.localeProvider;
+    if (localeProvider?.enabled) {
+      // The URL is the source of truth: switching language means navigating to
+      // the same page under the new locale prefix. Dictionaries and formatters
+      // are then activated via the resulting `alepha.react.router.locale`
+      // change (see the `mutate` hook). No cookie is written in prefix mode.
+      const { ReactRouter } = await import("alepha/react/router");
+      const router = this.alepha.inject(ReactRouter);
+      const canonical = localeProvider.detect(router.pathname).pathname;
+      await router.push(localeProvider.withPrefix(canonical, lang));
+      return;
+    }
+
+    await this.applyLang(lang);
+    if (this.alepha.isBrowser()) {
+      this.cookie.set(lang);
+    }
+  };
+
   protected readonly mutate = $hook({
     on: "state:mutate",
     handler: async ({ key, value }) => {
+      // Prefix-mode navigation changed the active locale (set by the router) →
+      // activate the matching language (loads dictionaries, refreshes
+      // formatters, and re-renders consumers via the lang state).
+      if (
+        key === "alepha.react.router.locale" &&
+        this.localeProvider?.enabled
+      ) {
+        const lang = (value as string) || this.fallbackLang;
+        if (lang !== this.lang) {
+          await this.applyLang(lang);
+        }
+        return;
+      }
+
       if (key === "alepha.react.i18n.lang" && this.alepha.isBrowser()) {
         let hasChanged = false;
         for (const item of this.registry) {

package/src/react/router/__tests__/RouterLocaleProvider.spec.ts

@@ -0,0 +1,127 @@
+import { Alepha } from "alepha";
+import { describe, test } from "vitest";
+import { RouterLocaleProvider } from "../providers/RouterLocaleProvider.ts";
+
+describe("RouterLocaleProvider", () => {
+  const setup = (config?: Parameters<RouterLocaleProvider["configure"]>[0]) => {
+    const alepha = Alepha.create();
+    const provider = alepha.inject(RouterLocaleProvider);
+    if (config) {
+      provider.configure(config);
+    }
+    return provider;
+  };
+
+  describe("when disabled (default)", () => {
+    test("detect leaves the pathname untouched", ({ expect }) => {
+      const provider = setup();
+      expect(provider.detect("/fr/about")).toEqual({
+        locale: "",
+        pathname: "/fr/about",
+      });
+    });
+
+    test("withPrefix returns the pathname unchanged", ({ expect }) => {
+      const provider = setup();
+      expect(provider.withPrefix("/about", "fr")).toBe("/about");
+    });
+  });
+
+  describe("when enabled with default 'en' and locales [en, fr, de]", () => {
+    const config = {
+      enabled: true,
+      defaultLocale: "en",
+      locales: ["en", "fr", "de"],
+    };
+
+    test("exposes only non-default locales as prefixed", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.prefixedLocales).toEqual(["fr", "de"]);
+    });
+
+    test("detect strips a known prefixed locale", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.detect("/fr/about")).toEqual({
+        locale: "fr",
+        pathname: "/about",
+      });
+    });
+
+    test("detect treats an unprefixed path as the default locale", ({
+      expect,
+    }) => {
+      const provider = setup(config);
+      expect(provider.detect("/about")).toEqual({
+        locale: "en",
+        pathname: "/about",
+      });
+    });
+
+    test("detect ignores a segment that is the default locale", ({
+      expect,
+    }) => {
+      const provider = setup(config);
+      // /en is NOT a prefixed locale (default is unprefixed), so it is a normal path
+      expect(provider.detect("/en/about")).toEqual({
+        locale: "en",
+        pathname: "/en/about",
+      });
+    });
+
+    test("detect normalizes the bare locale root to '/'", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.detect("/fr")).toEqual({ locale: "fr", pathname: "/" });
+      expect(provider.detect("/fr/")).toEqual({ locale: "fr", pathname: "/" });
+    });
+
+    test("detect strips a deep prefixed path", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.detect("/de/c/42/quest")).toEqual({
+        locale: "de",
+        pathname: "/c/42/quest",
+      });
+    });
+
+    test("withPrefix prepends a non-default locale", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/about", "fr")).toBe("/fr/about");
+    });
+
+    test("withPrefix leaves the default locale unprefixed", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/about", "en")).toBe("/about");
+    });
+
+    test("withPrefix handles the root path", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/", "fr")).toBe("/fr");
+    });
+
+    test("withPrefix ignores an unknown locale", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/about", "zz")).toBe("/about");
+    });
+  });
+
+  describe("current locale (store-backed)", () => {
+    test("defaults to the default locale", ({ expect }) => {
+      const provider = setup({
+        enabled: true,
+        defaultLocale: "en",
+        locales: ["en", "fr"],
+      });
+      expect(provider.current).toBe("en");
+    });
+
+    test("withPrefix uses current() when no locale is passed", ({ expect }) => {
+      const provider = setup({
+        enabled: true,
+        defaultLocale: "en",
+        locales: ["en", "fr"],
+      });
+      provider.current = "fr";
+      expect(provider.current).toBe("fr");
+      expect(provider.withPrefix("/about")).toBe("/fr/about");
+    });
+  });
+});

package/src/react/router/index.browser.ts

@@ -9,6 +9,7 @@ import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
 import { ReactBrowserRendererProvider } from "./providers/ReactBrowserRendererProvider.ts";
 import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
 import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { RouterLocaleProvider } from "./providers/RouterLocaleProvider.ts";
 import { ReactPageService } from "./services/ReactPageService.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
 
@@ -18,6 +19,7 @@ export * from "./index.shared.ts";
 export * from "./providers/ReactBrowserProvider.ts";
 export * from "./providers/ReactBrowserRendererProvider.ts";
 export * from "./providers/ReactBrowserRouterProvider.ts";
+export * from "./providers/RouterLocaleProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -30,6 +32,7 @@ export const AlephaReactRouter = $module({
     ReactBrowserProvider,
     ReactRouter,
     ReactBrowserRendererProvider,
+    RouterLocaleProvider,
     ReactPageService,
   ],
   register: (alepha) =>
@@ -43,5 +46,6 @@ export const AlephaReactRouter = $module({
       .with(ReactBrowserProvider)
       .with(ReactBrowserRouterProvider)
       .with(ReactBrowserRendererProvider)
+      .with(RouterLocaleProvider)
       .with(ReactRouter),
 });

package/src/react/router/index.shared.ts

@@ -15,5 +15,6 @@ export * from "./hooks/useRouter.ts";
 export * from "./hooks/useRouterState.ts";
 export * from "./primitives/$page.ts";
 export * from "./providers/ReactPageProvider.ts";
+export * from "./providers/RootComponentsProvider.ts";
 export * from "./services/ReactPageService.ts";
 export * from "./services/ReactRouter.ts";

package/src/react/router/index.ts

@@ -15,6 +15,7 @@ import {
 import { ReactPreloadProvider } from "./providers/ReactPreloadProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
 import { ReactServerTemplateProvider } from "./providers/ReactServerTemplateProvider.ts";
+import { RouterLocaleProvider } from "./providers/RouterLocaleProvider.ts";
 import { SSRManifestProvider } from "./providers/SSRManifestProvider.ts";
 import { ReactPageServerService } from "./services/ReactPageServerService.ts";
 import { ReactPageService } from "./services/ReactPageService.ts";
@@ -28,6 +29,7 @@ export * from "./providers/ReactPageProvider.ts";
 export * from "./providers/ReactPreloadProvider.ts";
 export * from "./providers/ReactServerProvider.ts";
 export * from "./providers/ReactServerTemplateProvider.ts";
+export * from "./providers/RouterLocaleProvider.ts";
 export * from "./providers/SSRManifestProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -35,6 +37,11 @@ export * from "./providers/SSRManifestProvider.ts";
 declare module "alepha" {
   interface State {
     "alepha.react.router.state"?: ReactRouterState;
+    /**
+     * The active locale path-prefix (e.g. `"fr"`), when `routing: "prefix"` is
+     * enabled on the i18n module. Empty/absent for the default locale.
+     */
+    "alepha.react.router.locale"?: string;
   }
 
   interface Hooks {
@@ -124,6 +131,7 @@ export const AlephaReactRouter = $module({
     ReactRouter,
     ReactServerProvider,
     ReactServerTemplateProvider,
+    RouterLocaleProvider,
     SSRManifestProvider,
     ReactPageServerService,
   ],
@@ -143,6 +151,7 @@ export const AlephaReactRouter = $module({
       .with(ReactServerTemplateProvider)
       .with(ReactPreloadProvider)
       .with(ReactServerProvider)
+      .with(RouterLocaleProvider)
       .with(ReactPageProvider)
       .with(ReactRouter),
 });

package/src/react/router/providers/ReactBrowserRouterProvider.ts

@@ -13,6 +13,7 @@ import {
   ReactPageProvider,
   type ReactRouterState,
 } from "./ReactPageProvider.ts";
+import { RouterLocaleProvider } from "./RouterLocaleProvider.ts";
 
 export interface BrowserRoute extends Route {
   page: PageRoute;
@@ -26,6 +27,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
   protected readonly alepha = $inject(Alepha);
   protected readonly pageApi = $inject(ReactPageProvider);
   protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
+  protected readonly localeProvider = $inject(RouterLocaleProvider);
 
   public add(entry: PageRouteEntry) {
     this.pageApi.add(entry);
@@ -75,7 +77,19 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
     });
 
     try {
-      const { route, params } = this.match(pathname);
+      // In locale-prefix mode the URL is the source of truth for language:
+      // strip a leading `/fr`-style segment and remember it (the i18n module
+      // reacts to this to switch dictionaries), then match on the canonical
+      // path so the single page tree still resolves. `state.url` keeps the
+      // full prefixed URL so generated links carry the prefix forward.
+      let matchPathname = pathname;
+      if (this.localeProvider.enabled) {
+        const detected = this.localeProvider.detect(pathname);
+        this.localeProvider.current = detected.locale;
+        matchPathname = detected.pathname;
+      }
+
+      const { route, params } = this.match(matchPathname);
 
       const query: Record<string, string> = {};
       if (search) {