@bleedingdev/modern-js-plugin-i18n 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/dist/types/runtime/providerComposition.d.ts

@@ -1,6 +1,16 @@
 import type React from 'react';
 import type { BaseLocaleDetectionOptions } from '../shared/type.js';
+import type { I18nUrlStrategy } from '../shared/urlStrategy.js';
 import type { I18nInstance } from './i18n/index.js';
+export interface I18nLanguageSynchronizationProps {
+    i18nInstance: I18nInstance | undefined;
+    localePathRedirect: boolean;
+    languages: string[];
+    pathname: string | undefined;
+    prevLangRef: React.MutableRefObject<string>;
+    setLang: (language: string) => void;
+    children: (synchronizeLanguage: (language: string) => void) => React.ReactNode;
+}
 interface I18nRootWrapperOptions {
     entryName?: string;
     htmlLangAttr: boolean;
@@ -8,7 +18,9 @@ interface I18nRootWrapperOptions {
     languages: string[];
     fallbackLanguage: string;
     ignoreRedirectRoutes?: BaseLocaleDetectionOptions['ignoreRedirectRoutes'];
-    localisedUrls?: BaseLocaleDetectionOptions['localisedUrls'];
+    urlStrategy?: I18nUrlStrategy;
+    NavigationProvider?: React.ComponentType<React.PropsWithChildren>;
+    LanguageSynchronization?: React.ComponentType<I18nLanguageSynchronizationProps>;
     getLatestI18nInstance: () => I18nInstance | undefined;
     getI18nextProvider: () => React.ComponentType<any> | null | undefined;
 }

package/dist/types/runtime/routerAdapter.d.ts

@@ -1,27 +1,44 @@
 import type React from 'react';
-type I18nRouterFramework = 'react-router' | 'tanstack' | string;
 interface I18nRouterLocation {
     pathname: string;
     search: string;
     hash: string;
 }
-interface I18nRouterNavigateOptions {
+type I18nRouterNavigate = (href: string, options?: {
     replace?: boolean;
     state?: unknown;
-}
-type I18nRouterNavigate = (href: string, options?: I18nRouterNavigateOptions) => void | Promise<void>;
+}) => void | Promise<void>;
 type I18nRouterLink = React.ComponentType<{
     to: string;
     children?: React.ReactNode;
     [key: string]: unknown;
 }>;
-interface I18nRouterAdapter {
-    framework?: I18nRouterFramework;
+export interface I18nRouterLinkTarget {
+    pathname: string;
+    href: string;
+    search?: Record<string, unknown>;
+    hash?: string;
+    hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+    prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+    preload?: unknown;
+}
+export interface I18nRouterAdapter {
+    framework?: string;
     hasRouter: boolean;
     location: I18nRouterLocation | null;
     navigate: I18nRouterNavigate | null;
     Link: I18nRouterLink | null;
     params: Record<string, string>;
+    /** Convert an already resolved target to the selected router's own props. */
+    createLinkProps?: (target: I18nRouterLinkTarget) => {
+        to: string;
+        [key: string]: unknown;
+    };
 }
+export declare const I18nNavigationProvider: ({ children, value, }: React.PropsWithChildren<{
+    value: I18nRouterAdapter;
+}>) => React.JSX.Element;
+/** Read native router hooks only when their own provider is present. */
+export declare const useNativeI18nRouterAdapter: () => I18nRouterAdapter;
 export declare const useI18nRouterAdapter: () => I18nRouterAdapter;
 export {};

package/dist/types/runtime/sharedContexts.d.ts

@@ -0,0 +1 @@
+export { ModernI18nContext, ReactI18nextProviderContext, } from './contexts.js';

package/dist/types/runtime/utils.d.ts

@@ -1,4 +1,5 @@
-import { type LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
+export { splitUrlTarget } from '@modern-js/runtime-utils/url';
 export declare const getPathname: (context: {
     ssrContext?: {
         request?: {
@@ -15,15 +16,6 @@ export declare const getEntryPath: () => string;
  * @returns The detected language or fallback language
  */
 export declare const getLanguageFromPath: (pathname: string, languages: string[], fallbackLanguage: string) => string;
-/**
- * Split a link target into its pathname, search and hash parts without
- * relying on `new URL` (SSR-hot path; targets are relative).
- */
-export declare const splitUrlTarget: (target: string) => {
-    pathname: string;
-    search: string;
-    hash: string;
-};
 /**
  * Helper function to build localized URL
  * @param target - The language-agnostic target; may include `?search` and `#hash`
@@ -31,7 +23,7 @@ export declare const splitUrlTarget: (target: string) => {
  * @param languages - Array of supported languages
  * @returns The localized URL path with search and hash re-appended verbatim
  */
-export declare const buildLocalizedUrl: (target: string, language: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;
+export declare const buildLocalizedUrl: (target: string, language: string, languages: string[], urlStrategy?: I18nUrlStrategy) => string;
 export declare const detectLanguageFromPath: (pathname: string, languages: string[], localePathRedirect: boolean) => {
     detected: boolean;
     language?: string;
@@ -39,4 +31,4 @@ export declare const detectLanguageFromPath: (pathname: string, languages: strin
 /**
  * Check if the given pathname should ignore automatic locale redirect
  */
-export declare const shouldIgnoreRedirect: (pathname: string, languages: string[], ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean)) => boolean;
+export declare const shouldIgnoreRedirect: (pathname: string, languages: string[], ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean), urlStrategy?: I18nUrlStrategy) => boolean;

package/dist/types/server/defaultUrlStrategy.d.ts

@@ -0,0 +1,11 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
+import type { I18nUrlStrategy } from '../shared/urlStrategy.js';
+/**
+ * Mapped locale URLs work without any extra plugin. `localeDetection.localisedUrls`
+ * alone is enough: the server derives the URL policy from the map it is given.
+ * An explicit `resolveUrlStrategy` still wins, so an integration can replace the
+ * policy wholesale.
+ */
+export declare const createDefaultUrlStrategy: (localisedUrls?: LocalisedUrlsOption) => I18nUrlStrategy;
+/** A non-empty map is the only configuration that needs a derived policy. */
+export declare const resolveDefaultUrlStrategy: (localisedUrls: unknown) => I18nUrlStrategy | undefined;

package/dist/types/server/index.d.ts

@@ -1,9 +1,11 @@
 import type { ServerPlugin } from '@modern-js/server-runtime';
 import type { LocaleDetectionOptions } from '../shared/type.js';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
 export { collectApiPrefixes, matchesApiPrefix } from './apiPrefix.js';
 export interface I18nPluginOptions {
     localeDetection: LocaleDetectionOptions;
     staticRoutePrefixes: string[];
+    resolveUrlStrategy?: (entryName: string) => I18nUrlStrategy | undefined;
 }
 export declare const i18nServerPlugin: (options: I18nPluginOptions) => ServerPlugin;
 export default i18nServerPlugin;

package/dist/types/server/mappedUrlStrategy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The mapped-URL policy moved to `../shared` so the client runtime can derive
+ * the same policy the server does — SSR and a hydrated `<Link>` have to agree
+ * on the mapping or client navigation targets a path the server will not serve.
+ * Re-exported here to keep the server-side import path stable.
+ */
+export { createMappedUrlStrategy, resolveMappedUrlStrategy, } from '../shared/mappedUrlStrategy.js';

package/dist/types/server/redirectPolicy.d.ts

@@ -1,22 +1,14 @@
-import type { LocaleDetectionOptions } from '../shared/type.js';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
 interface LocaleRedirectRequest {
     url: string;
-    header: () => {
+    header?: () => {
         host?: string;
     };
 }
-/**
- * Check if pathname should ignore automatic locale redirect.
- */
-export declare const shouldIgnoreRedirect: (pathname: string, urlPath: string, ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean)) => boolean;
-/**
- * Check if pathname is a static or federation resource request.
- *
- * This includes configured staticRoutePrefixes, the shared default skip policy
- * from ADR-0002, and language-prefixed variants such as /en/static/app.js.
- */
+export declare const shouldIgnoreRedirect: (pathname: string, urlPath: string, ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean), urlStrategy?: I18nUrlStrategy, languages?: string[]) => boolean;
+/** Native configured/static exclusions remain in effect for every strategy. */
 export declare const isStaticResourceRequest: (pathname: string, staticRoutePrefixes: string[], languages?: string[]) => boolean;
 export declare const getLanguageFromPath: (req: LocaleRedirectRequest, urlPath: string, languages: string[]) => string | null;
-export declare const buildLocalizedUrl: (req: LocaleRedirectRequest, urlPath: string, language: string, languages: string[], localisedUrls?: LocaleDetectionOptions['localisedUrls']) => string;
+export declare const buildLocalizedUrl: (req: LocaleRedirectRequest, urlPath: string, language: string, languages: string[], urlStrategy?: I18nUrlStrategy) => string;
 export declare const createLocaleRedirectResponse: (location: string) => Response;
 export {};

package/dist/types/shared/mappedUrlStrategy.d.ts

@@ -0,0 +1,27 @@
+import { type LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
+import type { I18nUrlStrategy } from './urlStrategy.js';
+/**
+ * The fork's native locale-redirect exclusions (federation artifacts, static
+ * and upload prefixes). Re-exported from this fork-owned seam so the native
+ * runtime and server redirect paths apply them without importing the
+ * extensions package themselves.
+ */
+export { isDefaultLocaleRedirectSkipPath } from '@modern-js/i18n-runtime-extensions';
+/**
+ * Build the URL policy from a mapped-locale-URL configuration.
+ *
+ * `localeDetection.localisedUrls` is plain data, so unlike a `urlStrategy`
+ * object it survives the JSON boundary between `modern.config.ts` and the
+ * generated runtime registration. It is therefore the one configuration both
+ * sides can rely on for mapped URLs.
+ *
+ * This is shared rather than server-only on purpose. The server and the client
+ * have to agree on the mapping or a hydrated `<Link>` navigates to a path the
+ * server will not serve: SSR renders `/cs/obchodni-podminky` while a
+ * client-side navigation asks for `/cs/terms-of-service`. The helpers below are
+ * pure pathname functions from `@modern-js/i18n-runtime-extensions`, so the
+ * client cost is a few hundred bytes of string work and no i18n engine.
+ */
+export declare const createMappedUrlStrategy: (localisedUrls?: LocalisedUrlsOption) => I18nUrlStrategy;
+/** Only a non-empty map needs a derived policy. */
+export declare const resolveMappedUrlStrategy: (localeDetection: unknown) => I18nUrlStrategy | undefined;

package/dist/types/shared/type.d.ts

@@ -1,4 +1,3 @@
-import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
 import type { LanguageDetectorOptions, Resources } from '../runtime/i18n/instance.js';
 export interface BaseLocaleDetectionOptions {
     localePathRedirect?: boolean;
@@ -8,18 +7,15 @@ export interface BaseLocaleDetectionOptions {
     detection?: LanguageDetectorOptions;
     ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
     /**
-     * Enables localised pathnames in addition to the locale prefix.
+     * Canonical-path -> per-language path map, e.g.
+     * `{ '/products': { en: '/products', cs: '/produkty' } }`.
      *
-     * - non-empty object: map canonical route paths to every configured
-     *   language; route generation then validates that every localisable route
-     *   path has entries for all configured languages.
-     * - absent / `false` / `true` / empty object: keep only locale-prefix
-     *   behavior (`/en/about`).
-     *
-     * Strictly opt-in: without a map, `localePathRedirect` + `languages` behave
-     * exactly like upstream Modern.js.
+     * Plain data on purpose: the generated runtime registration carries plugin
+     * options as JSON, so a map survives the trip where a `urlStrategy` object
+     * would lose its methods. The CLI expands file-system routes from it, and
+     * the server derives its URL strategy from it, with no extra plugin.
      */
-    localisedUrls?: LocalisedUrlsOption;
+    localisedUrls?: boolean | Record<string, Record<string, string>>;
 }
 export interface LocaleDetectionOptions extends BaseLocaleDetectionOptions {
     localeDetectionByEntry?: Record<string, BaseLocaleDetectionOptions>;

package/dist/types/shared/urlStrategy.d.ts

@@ -0,0 +1,18 @@
+/** Per-plugin URL policy. Search and hash remain owned by native URL handling. */
+export interface I18nUrlStrategy {
+    localizePathname(pathname: string, language: string, languages: readonly string[]): string;
+    canonicalPathname(pathname: string, languages: readonly string[]): string;
+    /** Adds exclusions; it cannot enable redirects excluded by native rules. */
+    shouldSkipRedirect?(pathname: string, languages: readonly string[]): boolean;
+}
+/**
+ * A URL strategy reaches the runtime through the generated runtime
+ * registration, which carries plugin options as JSON. Functions do not survive
+ * that, so a configured strategy can arrive as an empty object — which is
+ * truthy and would make every call site throw. Anything that is not a complete
+ * strategy is treated as absent, and the caller falls back to the built-in
+ * language-prefix behaviour.
+ */
+export declare const asI18nUrlStrategy: (candidate: unknown) => I18nUrlStrategy | undefined;
+/** `true` when a value was configured as a strategy but cannot be used as one. */
+export declare const isUnusableI18nUrlStrategy: (candidate: unknown) => boolean;

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.9.0-ultramodern.2",
+  "version": "3.9.0-ultramodern.21",
   "engines": {
     "node": ">=20"
   },
@@ -55,6 +55,13 @@
       },
       "default": "./dist/esm/runtime/context.mjs"
     },
+    "./runtime/contexts": {
+      "types": "./dist/types/runtime/contexts.d.ts",
+      "node": {
+        "module": "./dist/esm/runtime/contexts.mjs"
+      },
+      "default": "./dist/esm/runtime/contexts.mjs"
+    },
     "./runtime/no-react-i18next": {
       "types": "./dist/types/runtime/no-react-i18next.d.ts",
       "node": {
@@ -80,6 +87,14 @@
     "./i18n": {
       "types": "./dist/types/runtime/i18n/index.d.ts",
       "default": "./dist/esm/runtime/i18n/index.mjs"
+    },
+    "./config": {
+      "types": "./dist/types/shared/utils.d.ts",
+      "node": {
+        "import": "./dist/esm-node/shared/utils.mjs",
+        "require": "./dist/cjs/shared/utils.js"
+      },
+      "default": "./dist/esm/shared/utils.mjs"
     }
   },
   "typesVersions": {
@@ -96,6 +111,9 @@
       "runtime/consumer": [
         "./dist/types/runtime/context.d.ts"
       ],
+      "runtime/contexts": [
+        "./dist/types/runtime/contexts.d.ts"
+      ],
       "runtime/no-react-i18next": [
         "./dist/types/runtime/no-react-i18next.d.ts"
       ],
@@ -107,26 +125,29 @@
       ],
       "i18n": [
         "./dist/types/runtime/i18n/index.d.ts"
+      ],
+      "config": [
+        "./dist/types/shared/utils.d.ts"
       ]
     }
   },
   "dependencies": {
-    "@modern-js/i18n-runtime-extensions": "npm:@bleedingdev/modern-js-i18n-runtime-extensions@3.9.0-ultramodern.2",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.2",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.2",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.2",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.9.0-ultramodern.2",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.2",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.2",
+    "@modern-js/i18n-runtime-extensions": "npm:@bleedingdev/modern-js-i18n-runtime-extensions@3.9.0-ultramodern.21",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.21",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.21",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.21",
+    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.9.0-ultramodern.21",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.21",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.21",
     "@swc/helpers": "^0.5.23",
     "i18next-browser-languagedetector": "^8.2.1",
     "i18next-chained-backend": "^5.0.6",
-    "i18next-fs-backend": "^2.6.7",
+    "i18next-fs-backend": "^2.6.8",
     "i18next-http-backend": "^4.0.2",
-    "i18next-http-middleware": "^3.9.8"
+    "i18next-http-middleware": "^3.9.9"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.2",
+    "@modern-js/runtime": "3.9.0-ultramodern.21",
     "i18next": ">=25.7.4",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -141,16 +162,18 @@
     }
   },
   "devDependencies": {
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.0-ultramodern.2",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.2",
-    "@rslib/core": "1.0.0",
-    "@types/node": "^26.4.1",
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.0-ultramodern.21",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.21",
+    "@modern-js/runtime-extensions": "npm:@bleedingdev/modern-js-runtime-extensions@3.9.0-ultramodern.21",
+    "@rslib/core": "1.0.2",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.6.2",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "esbuild": "^0.28.2",
     "i18next": "26.4.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "react-i18next": "17.0.13",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-i18next": "17.0.15",
     "ts-node": "^10.9.2",
     "typescript": "^7.0.2"
   },
@@ -161,6 +184,6 @@
   "scripts": {
     "dev": "rslib build --watch",
     "build": "rslib build",
-    "test": "rstest --passWithNoTests"
+    "test": "rstest"
   }
 }

package/rslib.config.mts

@@ -1,4 +1,11 @@
 import { rslibConfig } from '@modern-js/rslib';
 import { defineConfig } from '@rslib/core';
 
-export default defineConfig(rslibConfig);
+export default defineConfig({
+  ...rslibConfig,
+  // Keep `@modern-js/plugin-i18n/runtime/contexts` a package self-reference in
+  // the output: Module Federation shares the i18n contexts by that request.
+  output: {
+    externals: ['@modern-js/plugin-i18n/runtime/contexts'],
+  },
+});

package/rstest.config.mts

@@ -29,13 +29,14 @@ export default {
       include: [
         'tests/i18nUtils.test.ts',
         'tests/localisedUrls.test.ts',
-        'tests/localisedUrlRewriteMatrix.fork.test.ts',
-        'tests/linkTypes.test.ts',
+        'tests/localisedRouteGeneration.test.ts',
+        'tests/mappedUrlStrategyDerivation.test.ts',
+        'tests/defaultUrlStrategy.test.ts',
+        'tests/urlStrategySerialization.test.ts',
         'tests/backendDefaults.test.ts',
         'tests/redirectPolicy.test.ts',
-        'tests/peerCohort.test.ts',
         'tests/reactI18nextRuntimeBoundary.test.ts',
-        'tests/federatedI18nBoundary.test.tsx',
+        'tests/federatedI18nBoundaryResolver.test.tsx',
       ],
       extends: commonConfig,
     }),
@@ -45,7 +46,7 @@ export default {
       include: [
         'tests/routerAdapter.test.tsx',
         'tests/link.test.tsx',
-        'tests/federatedI18nBoundary.client.test.tsx',
+        'tests/navigation.test.tsx',
       ],
       extends: commonConfig,
     }),

package/src/cli/index.ts

@@ -1,19 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import type { AppTools, CliPlugin } from '@modern-js/app-tools';
-import {
-  applyLocalisedUrlsToRoutes,
-  resolveLocalisedUrlsConfig,
-} from '@modern-js/i18n-runtime-extensions';
 import { getPublicDirRoutePrefixes } from '@modern-js/server-core';
-import type {
-  Entrypoint,
-  NestedRouteForCli,
-  PageRoute,
-} from '@modern-js/types';
+import type { Entrypoint } from '@modern-js/types';
+import { logger } from '@modern-js/utils';
 import type { BackendOptions, LocaleDetectionOptions } from '../shared/type';
+import { isUnusableI18nUrlStrategy } from '../shared/urlStrategy';
 import { getBackendOptions, getLocaleDetectionOptions } from '../shared/utils';
 import { applyDetectedBackendPaths, detectLocalesDirectory } from './locales';
+import { applyLocalisedRoutes } from './localisedRoutes';
 import '../runtime/types';
 
 export type TransformRuntimeConfigFn = (
@@ -120,12 +115,28 @@ export const i18nPlugin = (
       }
 
       // Build final config with base config and transformed extended config
-      const config = {
+      const config: Record<string, unknown> = {
         entryName: entrypoint.entryName,
         localeDetection: localeDetectionOptions,
         backend: backendOptions,
         ...extendedConfig,
       };
+
+      // This config is written into the generated runtime registration as
+      // JSON, so an object carrying functions arrives at the runtime with none
+      // of them. Drop it rather than shipping a broken `{}` that every call
+      // site would then have to survive, and say what to configure instead.
+      if (isUnusableI18nUrlStrategy(config.urlStrategy)) {
+        delete config.urlStrategy;
+        logger.warn(
+          '[i18n] `urlStrategy` cannot be passed through `modern.config.ts`: ' +
+            'the generated runtime registration carries plugin options as ' +
+            'JSON, which drops its methods. Configure ' +
+            '`localeDetection.localisedUrls` instead — the runtime and the ' +
+            'server both derive the URL policy from it — or register a ' +
+            'runtime plugin that supplies the strategy directly.',
+        );
+      }
       const { reactI18next } = extendedConfig as { reactI18next?: boolean };
       const runtimePluginPath =
         customPlugin?.runtime?.path ||
@@ -144,39 +155,28 @@ export const i18nPlugin = (
       };
     });
 
-    api.modifyFileSystemRoutes(({ entrypoint, routes }) => {
-      if (!localeDetection) {
-        return { entrypoint, routes };
-      }
-
-      const localeDetectionOptions = getLocaleDetectionOptions(
-        entrypoint.entryName,
-        localeDetection,
-      );
-      const {
-        localePathRedirect,
-        languages = [],
-        localisedUrls,
-      } = localeDetectionOptions;
-
-      if (!localePathRedirect || languages.length === 0) {
-        return { entrypoint, routes };
-      }
-
-      const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
-      if (!localisedUrlsConfig.enabled) {
-        return { entrypoint, routes };
-      }
-
-      return {
+    // Mapped locale URLs are a property of `localeDetection.localisedUrls`, not
+    // of any particular app-tools composition, so the route expansion lives
+    // here rather than in an opt-in fork plugin. A bare `appTools()` consumer
+    // that declares the map gets `/cs/obchodni-podminky` generated alongside
+    // `/cs/terms-of-service`; without this the localized path 404s under SSR.
+    //
+    // This is deliberately not registered from `@modern-js/i18n-integration`:
+    // that package peer-depends on `@modern-js/runtime`, and pulling it into
+    // the default app-tools path closes an Nx cycle
+    // (app-tools -> app-tools-extensions -> i18n-integration -> runtime -> app-tools).
+    // `@modern-js/i18n-runtime-extensions` is already a direct dependency here,
+    // so nothing new is added to the graph.
+    api.modifyFileSystemRoutes(({ entrypoint, routes }) => ({
+      entrypoint,
+      routes: applyLocalisedRoutes(
+        routes as any,
+        localeDetection
+          ? getLocaleDetectionOptions(entrypoint.entryName, localeDetection)
+          : undefined,
         entrypoint,
-        routes: applyLocalisedUrlsToRoutes(
-          routes as (NestedRouteForCli | PageRoute)[],
-          languages,
-          localisedUrlsConfig.map,
-        ) as (NestedRouteForCli | PageRoute)[],
-      };
-    });
+      ) as typeof routes,
+    }));
 
     api._internalServerPlugins(({ plugins }) => {
       const { serverRoutes, metaName } = api.getAppContext();

package/src/cli/localisedRoutes.ts

@@ -0,0 +1,53 @@
+import {
+  applyLocalisedUrlsToRoutes,
+  resolveLocalisedUrlsConfig,
+} from '@modern-js/i18n-runtime-extensions';
+import { getEntrypointRoutesOwner } from '@modern-js/runtime/cli';
+import type {
+  Entrypoint,
+  NestedRouteForCli,
+  PageRoute,
+} from '@modern-js/types';
+import type { BaseLocaleDetectionOptions } from '../shared/type';
+
+type FileSystemRoutes = (NestedRouteForCli | PageRoute)[];
+
+/**
+ * Expand file-system routes from `localeDetection.localisedUrls`.
+ *
+ * Fork-owned: the localised-URL engine lives in
+ * `@modern-js/i18n-runtime-extensions`, which upstream-owned files must not
+ * import. `cli/index.ts` calls this through a relative import so the seam, not
+ * the edge, is what appears in the upstream-shaped file.
+ *
+ * Returns the routes unchanged unless locale-path redirects are on, languages
+ * are declared, and a non-empty map is configured — an upstream-style config
+ * with `localePathRedirect` and `languages` but no map keeps plain
+ * locale-prefix behaviour.
+ */
+export const applyLocalisedRoutes = (
+  routes: FileSystemRoutes,
+  localeDetection: BaseLocaleDetectionOptions | undefined,
+  entrypoint?: Entrypoint & Parameters<typeof getEntrypointRoutesOwner>[0],
+): FileSystemRoutes => {
+  const {
+    localePathRedirect,
+    languages = [],
+    localisedUrls,
+  } = localeDetection ?? {};
+  const resolved = resolveLocalisedUrlsConfig(localisedUrls);
+
+  if (!localePathRedirect || !languages.length || !resolved.enabled) {
+    return routes;
+  }
+
+  return applyLocalisedUrlsToRoutes(
+    routes,
+    languages,
+    resolved.map,
+    entrypoint &&
+      getEntrypointRoutesOwner(entrypoint) === '@modern-js/plugin-tanstack'
+      ? 'canonical'
+      : 'physical',
+  ) as FileSystemRoutes;
+};