@bleedingdev/modern-js-plugin-i18n 3.9.0-ultramodern.7 → 3.9.0-ultramodern.9

package/dist/esm-node/runtime/core.mjs

@@ -1,4 +1,6 @@
 import "node:module";
+import { resolveMappedUrlStrategy } from "../shared/mappedUrlStrategy.mjs";
+import { asI18nUrlStrategy } from "../shared/urlStrategy.mjs";
 import { setupI18nBeforeRender } from "./pluginSetup.mjs";
 import { createI18nRootWrapper } from "./providerComposition.mjs";
 import { resolveReactI18nextIntegration } from "./reactI18next.mjs";
@@ -9,6 +11,7 @@ const createI18nPlugin = (loadReactI18nextIntegration)=>(options)=>({
                 const { entryName, i18nInstance: userI18nInstance, initOptions, localeDetection, backend, htmlLangAttr = false, reactI18next = true, urlStrategy, NavigationProvider, LanguageSynchronization } = options;
                 const { localePathRedirect = false, i18nextDetector = true, languages = [], fallbackLanguage = 'en', detection, ignoreRedirectRoutes } = localeDetection || {};
                 const { enabled: backendEnabled = false } = backend || {};
+                const resolvedUrlStrategy = asI18nUrlStrategy(urlStrategy) ?? resolveMappedUrlStrategy(localeDetection);
                 let latestI18nInstance;
                 let I18nextProvider;
                 api.onBeforeRender(async (context)=>{
@@ -36,7 +39,7 @@ const createI18nPlugin = (loadReactI18nextIntegration)=>(options)=>({
                     languages,
                     fallbackLanguage,
                     ignoreRedirectRoutes,
-                    urlStrategy,
+                    urlStrategy: resolvedUrlStrategy,
                     NavigationProvider,
                     LanguageSynchronization,
                     getLatestI18nInstance: ()=>latestI18nInstance,

package/dist/esm-node/runtime/utils.mjs

@@ -2,6 +2,8 @@ import "node:module";
 import { isBrowser } from "@modern-js/runtime";
 import { getGlobalBasename } from "@modern-js/runtime/context";
 import { splitUrlTarget } from "@modern-js/runtime-utils/url";
+import { isDefaultLocaleRedirectSkipPath } from "../shared/mappedUrlStrategy.mjs";
+import { asI18nUrlStrategy } from "../shared/urlStrategy.mjs";
 const getPathname = (context)=>{
     if (isBrowser()) return window.location.pathname;
     return context.ssrContext?.request?.pathname || '/';
@@ -19,7 +21,8 @@ const getLanguageFromPath = (pathname, languages, fallbackLanguage)=>{
 };
 const buildLocalizedUrl = (target, language, languages, urlStrategy)=>{
     const { pathname, search, hash } = splitUrlTarget(target);
-    if (urlStrategy) return `${urlStrategy.localizePathname(pathname, language, languages)}${search}${hash}`;
+    const strategy = asI18nUrlStrategy(urlStrategy);
+    if (strategy) return `${strategy.localizePathname(pathname, language, languages)}${search}${hash}`;
     const segments = pathname.split('/').filter(Boolean);
     if (segments[0] && languages.some((item)=>item.toLowerCase() === segments[0].toLowerCase())) segments[0] = language;
     else segments.unshift(language);
@@ -44,7 +47,8 @@ const detectLanguageFromPath = (pathname, languages, localePathRedirect)=>{
     };
 };
 const shouldIgnoreRedirect = (pathname, languages, ignoreRedirectRoutes, urlStrategy)=>{
-    if (urlStrategy?.shouldSkipRedirect?.(pathname, languages)) return true;
+    if (isDefaultLocaleRedirectSkipPath(pathname, languages)) return true;
+    if (asI18nUrlStrategy(urlStrategy)?.shouldSkipRedirect?.(pathname, languages)) return true;
     if (!ignoreRedirectRoutes) return false;
     const segments = pathname.split('/').filter(Boolean);
     if (segments[0] && languages.some((item)=>item.toLowerCase() === segments[0].toLowerCase())) segments.shift();

package/dist/esm-node/server/defaultUrlStrategy.mjs

@@ -0,0 +1,8 @@
+import "node:module";
+import { createMappedUrlStrategy } from "./mappedUrlStrategy.mjs";
+const createDefaultUrlStrategy = (localisedUrls)=>createMappedUrlStrategy(localisedUrls);
+const resolveDefaultUrlStrategy = (localisedUrls)=>{
+    if (!localisedUrls || 'object' != typeof localisedUrls || 0 === Object.keys(localisedUrls).length) return;
+    return createDefaultUrlStrategy(localisedUrls);
+};
+export { createDefaultUrlStrategy, resolveDefaultUrlStrategy };

package/dist/esm-node/server/index.mjs

@@ -1,6 +1,8 @@
 import "node:module";
+import { asI18nUrlStrategy } from "../shared/urlStrategy.mjs";
 import { getLocaleDetectionOptions } from "../shared/utils.mjs";
 import { collectApiPrefixes, matchesApiPrefix } from "./apiPrefix.mjs";
+import { resolveDefaultUrlStrategy } from "./defaultUrlStrategy.mjs";
 import { convertToHonoLanguageDetectorOptions } from "./detectorOptions.mjs";
 import { buildLocalizedUrl, createLocaleRedirectResponse, getLanguageFromPath, isStaticResourceRequest, shouldIgnoreRedirect } from "./redirectPolicy.mjs";
 import * as __rspack_external__modern_js_server_core_hono_0af3baa7 from "@modern-js/server-core/hono";
@@ -27,8 +29,7 @@ const i18nServerPlugin = (options)=>({
                     const entryLocaleDetection = getLocaleDetectionOptions(entryName, options.localeDetection);
                     const { localePathRedirect, i18nextDetector = true, languages = [], fallbackLanguage = 'en', detection, ignoreRedirectRoutes } = entryLocaleDetection;
                     const legacyLocalisedUrls = Reflect.get(entryLocaleDetection, 'localisedUrls');
-                    const urlStrategy = options.resolveUrlStrategy?.(entryName);
-                    if (legacyLocalisedUrls && 'object' == typeof legacyLocalisedUrls && Object.keys(legacyLocalisedUrls).length > 0 && !urlStrategy) throw new Error('Mapped locale URLs require a URL strategy. Use the i18n integration server plugin or supply resolveUrlStrategy.');
+                    const urlStrategy = asI18nUrlStrategy(options.resolveUrlStrategy?.(entryName)) ?? resolveDefaultUrlStrategy(legacyLocalisedUrls);
                     const staticRoutePrefixes = options.staticRoutePrefixes;
                     const originUrlPath = route.urlPath;
                     const urlPath = originUrlPath.endsWith('/') ? `${originUrlPath}*` : `${originUrlPath}/*`;

package/dist/esm-node/server/mappedUrlStrategy.mjs

@@ -0,0 +1,2 @@
+import "node:module";
+export { createMappedUrlStrategy, resolveMappedUrlStrategy } from "../shared/mappedUrlStrategy.mjs";

package/dist/esm-node/server/redirectPolicy.mjs

@@ -1,4 +1,6 @@
 import "node:module";
+import { isDefaultLocaleRedirectSkipPath } from "../shared/mappedUrlStrategy.mjs";
+import { asI18nUrlStrategy } from "../shared/urlStrategy.mjs";
 const stripUrlPathPrefix = (pathname, urlPath)=>{
     const basePath = urlPath.replace('/*', '');
     if (!basePath || '/' === basePath) return pathname;
@@ -6,7 +8,8 @@ const stripUrlPathPrefix = (pathname, urlPath)=>{
 };
 const shouldIgnoreRedirect = (pathname, urlPath, ignoreRedirectRoutes, urlStrategy, languages = [])=>{
     const remainingPath = stripUrlPathPrefix(pathname, urlPath);
-    if (urlStrategy?.shouldSkipRedirect?.(remainingPath, languages)) return true;
+    if (isDefaultLocaleRedirectSkipPath(remainingPath, languages)) return true;
+    if (asI18nUrlStrategy(urlStrategy)?.shouldSkipRedirect?.(remainingPath, languages)) return true;
     if (!ignoreRedirectRoutes) return false;
     const segments = remainingPath.split('/').filter(Boolean);
     if (segments[0] && languages.some((language)=>language.toLowerCase() === segments[0].toLowerCase())) segments.shift();
@@ -38,7 +41,8 @@ const buildLocalizedUrl = (req, urlPath, language, languages, urlStrategy)=>{
     const segments = remainingPath.split('/').filter(Boolean);
     if (segments[0] && languages.some((item)=>item.toLowerCase() === segments[0].toLowerCase())) segments[0] = language;
     else segments.unshift(language);
-    const pathname = urlStrategy ? urlStrategy.localizePathname(remainingPath, language, languages) : `/${segments.join('/')}`;
+    const strategy = asI18nUrlStrategy(urlStrategy);
+    const pathname = strategy ? strategy.localizePathname(remainingPath, language, languages) : `/${segments.join('/')}`;
     return `${'/' === basePath ? '' : basePath}${pathname}${url.search}${url.hash}`;
 };
 const createLocaleRedirectResponse = (location)=>new Response(null, {

package/dist/esm-node/shared/mappedUrlStrategy.mjs

@@ -0,0 +1,20 @@
+import "node:module";
+import { canonicalTargetPathname, isDefaultLocaleRedirectSkipPath, localiseTargetPathname } from "@modern-js/i18n-runtime-extensions";
+const createMappedUrlStrategy = (localisedUrls)=>({
+        localizePathname: (pathname, language, languages)=>localiseTargetPathname(pathname, language, [
+                ...languages
+            ], localisedUrls),
+        canonicalPathname: (pathname, languages)=>canonicalTargetPathname(pathname, [
+                ...languages
+            ], localisedUrls),
+        shouldSkipRedirect: (pathname, languages)=>isDefaultLocaleRedirectSkipPath(pathname, [
+                ...languages
+            ])
+    });
+const resolveMappedUrlStrategy = (localeDetection)=>{
+    if (!localeDetection || 'object' != typeof localeDetection) return;
+    const localisedUrls = Reflect.get(localeDetection, 'localisedUrls');
+    if (!localisedUrls || 'object' != typeof localisedUrls || 0 === Object.keys(localisedUrls).length) return;
+    return createMappedUrlStrategy(localisedUrls);
+};
+export { createMappedUrlStrategy, isDefaultLocaleRedirectSkipPath, resolveMappedUrlStrategy };

package/dist/esm-node/shared/urlStrategy.mjs

@@ -1 +1,8 @@
 import "node:module";
+const asI18nUrlStrategy = (candidate)=>{
+    if (!candidate || 'object' != typeof candidate) return;
+    const strategy = candidate;
+    return 'function' == typeof strategy.localizePathname && 'function' == typeof strategy.canonicalPathname ? strategy : void 0;
+};
+const isUnusableI18nUrlStrategy = (candidate)=>Boolean(candidate) && 'object' == typeof candidate && void 0 === asI18nUrlStrategy(candidate);
+export { asI18nUrlStrategy, isUnusableI18nUrlStrategy };

package/dist/types/cli/localisedRoutes.d.ts

@@ -0,0 +1,18 @@
+import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
+import type { BaseLocaleDetectionOptions } from '../shared/type.js';
+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 declare const applyLocalisedRoutes: (routes: FileSystemRoutes, localeDetection: BaseLocaleDetectionOptions | undefined) => FileSystemRoutes;
+export {};

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

@@ -1,7 +1,7 @@
 import type { RuntimePlugin } from '@modern-js/runtime';
 import type React from 'react';
 import type { BaseBackendOptions, BaseLocaleDetectionOptions } from '../shared/type.js';
-import type { I18nUrlStrategy } from '../shared/urlStrategy.js';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
 import type { I18nInitOptions, I18nInstance } from './i18n/index.js';
 import { type I18nLanguageSynchronizationProps } from './providerComposition.js';
 export type { I18nLanguageSynchronizationProps } from './providerComposition.js';

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

@@ -1,4 +1,4 @@
-import type { I18nUrlStrategy } from '../shared/urlStrategy.js';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
 export { splitUrlTarget } from '@modern-js/runtime-utils/url';
 export declare const getPathname: (context: {
     ssrContext?: {

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,6 +1,6 @@
 import type { ServerPlugin } from '@modern-js/server-runtime';
 import type { LocaleDetectionOptions } from '../shared/type.js';
-import type { I18nUrlStrategy } from '../shared/urlStrategy.js';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
 export { collectApiPrefixes, matchesApiPrefix } from './apiPrefix.js';
 export interface I18nPluginOptions {
     localeDetection: LocaleDetectionOptions;

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,4 +1,4 @@
-import type { I18nUrlStrategy } from '../shared/urlStrategy.js';
+import { type I18nUrlStrategy } from '../shared/urlStrategy.js';
 interface LocaleRedirectRequest {
     url: string;
     header?: () => {

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

@@ -6,6 +6,16 @@ export interface BaseLocaleDetectionOptions {
     fallbackLanguage?: string;
     detection?: LanguageDetectorOptions;
     ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+    /**
+     * Canonical-path -> per-language path map, e.g.
+     * `{ '/products': { en: '/products', cs: '/produkty' } }`.
+     *
+     * 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?: boolean | Record<string, Record<string, string>>;
 }
 export interface LocaleDetectionOptions extends BaseLocaleDetectionOptions {
     localeDetectionByEntry?: Record<string, BaseLocaleDetectionOptions>;

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

@@ -5,3 +5,14 @@ export interface I18nUrlStrategy {
     /** 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.7",
+  "version": "3.9.0-ultramodern.9",
   "engines": {
     "node": ">=20"
   },
@@ -122,12 +122,13 @@
     }
   },
   "dependencies": {
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.7",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.7",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.7",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.9.0-ultramodern.7",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.7",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.7",
+    "@modern-js/i18n-runtime-extensions": "npm:@bleedingdev/modern-js-i18n-runtime-extensions@3.9.0-ultramodern.9",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.9",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.9",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.9",
+    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.9.0-ultramodern.9",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.9",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.9",
     "@swc/helpers": "^0.5.23",
     "i18next-browser-languagedetector": "^8.2.1",
     "i18next-chained-backend": "^5.0.6",
@@ -136,7 +137,7 @@
     "i18next-http-middleware": "^3.9.8"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.7",
+    "@modern-js/runtime": "3.9.0-ultramodern.9",
     "i18next": ">=25.7.4",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -151,8 +152,8 @@
     }
   },
   "devDependencies": {
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.0-ultramodern.7",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.7",
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.0-ultramodern.9",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.9",
     "@rslib/core": "1.0.0",
     "@types/node": "^26.4.1",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",

package/rstest.config.mts

@@ -29,6 +29,10 @@ export default {
       include: [
         'tests/i18nUtils.test.ts',
         'tests/localisedUrls.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/reactI18nextRuntimeBoundary.test.ts',

package/src/cli/index.ts

@@ -3,9 +3,12 @@ import path from 'node:path';
 import type { AppTools, CliPlugin } from '@modern-js/app-tools';
 import { getPublicDirRoutePrefixes } from '@modern-js/server-core';
 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 = (
@@ -112,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 ||
@@ -136,6 +155,28 @@ export const i18nPlugin = (
       };
     });
 
+    // 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,
+      ) as typeof routes,
+    }));
+
     api._internalServerPlugins(({ plugins }) => {
       const { serverRoutes, metaName } = api.getAppContext();
       const normalizedConfig = api.getNormalizedConfig();

package/src/cli/localisedRoutes.ts

@@ -0,0 +1,43 @@
+import {
+  applyLocalisedUrlsToRoutes,
+  resolveLocalisedUrlsConfig,
+} from '@modern-js/i18n-runtime-extensions';
+import type { 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,
+): FileSystemRoutes => {
+  const {
+    localePathRedirect,
+    languages = [],
+    localisedUrls,
+  } = localeDetection ?? {};
+  const resolved = resolveLocalisedUrlsConfig(localisedUrls);
+
+  if (!localePathRedirect || !languages.length || !resolved.enabled) {
+    return routes;
+  }
+
+  return applyLocalisedUrlsToRoutes(
+    routes,
+    languages,
+    resolved.map,
+  ) as FileSystemRoutes;
+};

package/src/runtime/core.tsx

@@ -1,10 +1,11 @@
 import type { RuntimePlugin } from '@modern-js/runtime';
 import type React from 'react';
+import { resolveMappedUrlStrategy } from '../shared/mappedUrlStrategy';
 import type {
   BaseBackendOptions,
   BaseLocaleDetectionOptions,
 } from '../shared/type';
-import type { I18nUrlStrategy } from '../shared/urlStrategy';
+import { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
 import type { I18nInitOptions, I18nInstance } from './i18n';
 import {
   type RuntimeContextWithI18n,
@@ -86,6 +87,21 @@ export const createI18nPlugin =
         ignoreRedirectRoutes,
       } = localeDetection || {};
       const { enabled: backendEnabled = false } = backend || {};
+      // A strategy configured in `modern.config.ts` reaches here through JSON,
+      // which drops its methods. Anything unusable is treated as absent so the
+      // built-in language-prefix behaviour applies instead of throwing.
+      //
+      // Falling back to `localeDetection.localisedUrls` makes mapped locale
+      // URLs work for a bare `appTools()` consumer: the map is plain data, so
+      // it survives the JSON boundary that a `urlStrategy` object does not.
+      // The server already derives its policy from the same field, and the two
+      // must agree — otherwise SSR renders `/cs/obchodni-podminky` and the
+      // hydrated `<Link>` navigates to `/cs/terms-of-service`, which 404s.
+      // An explicit, usable `urlStrategy` (supplied by a composing runtime
+      // plugin) still wins.
+      const resolvedUrlStrategy =
+        asI18nUrlStrategy(urlStrategy) ??
+        resolveMappedUrlStrategy(localeDetection);
       let latestI18nInstance: I18nInstance | undefined;
       let I18nextProvider: React.ComponentType<any> | null;
 
@@ -120,7 +136,7 @@ export const createI18nPlugin =
           languages,
           fallbackLanguage,
           ignoreRedirectRoutes,
-          urlStrategy,
+          urlStrategy: resolvedUrlStrategy,
           NavigationProvider,
           LanguageSynchronization,
           getLatestI18nInstance: () => latestI18nInstance,

package/src/runtime/utils.ts

@@ -1,7 +1,8 @@
 import { isBrowser } from '@modern-js/runtime';
 import { getGlobalBasename } from '@modern-js/runtime/context';
 import { splitUrlTarget } from '@modern-js/runtime-utils/url';
-import type { I18nUrlStrategy } from '../shared/urlStrategy';
+import { isDefaultLocaleRedirectSkipPath } from '../shared/mappedUrlStrategy';
+import { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
 
 export { splitUrlTarget } from '@modern-js/runtime-utils/url';
 
@@ -60,8 +61,9 @@ export const buildLocalizedUrl = (
   urlStrategy?: I18nUrlStrategy,
 ): string => {
   const { pathname, search, hash } = splitUrlTarget(target);
-  if (urlStrategy) {
-    return `${urlStrategy.localizePathname(pathname, language, languages)}${search}${hash}`;
+  const strategy = asI18nUrlStrategy(urlStrategy);
+  if (strategy) {
+    return `${strategy.localizePathname(pathname, language, languages)}${search}${hash}`;
   }
   const segments = pathname.split('/').filter(Boolean);
   if (
@@ -121,7 +123,14 @@ export const shouldIgnoreRedirect = (
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
   urlStrategy?: I18nUrlStrategy,
 ): boolean => {
-  if (urlStrategy?.shouldSkipRedirect?.(pathname, languages)) {
+  // Same native exclusions as the server: federation artifacts are never
+  // locale-redirected, with or without a configured strategy.
+  if (isDefaultLocaleRedirectSkipPath(pathname, languages)) {
+    return true;
+  }
+  if (
+    asI18nUrlStrategy(urlStrategy)?.shouldSkipRedirect?.(pathname, languages)
+  ) {
     return true;
   }
   if (!ignoreRedirectRoutes) {

package/src/server/defaultUrlStrategy.ts

@@ -0,0 +1,27 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
+import type { I18nUrlStrategy } from '../shared/urlStrategy';
+import { createMappedUrlStrategy } from './mappedUrlStrategy';
+
+/**
+ * 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 const createDefaultUrlStrategy = (
+  localisedUrls?: LocalisedUrlsOption,
+): I18nUrlStrategy => createMappedUrlStrategy(localisedUrls);
+
+/** A non-empty map is the only configuration that needs a derived policy. */
+export const resolveDefaultUrlStrategy = (
+  localisedUrls: unknown,
+): I18nUrlStrategy | undefined => {
+  if (
+    !localisedUrls ||
+    typeof localisedUrls !== 'object' ||
+    Object.keys(localisedUrls).length === 0
+  ) {
+    return undefined;
+  }
+  return createDefaultUrlStrategy(localisedUrls as LocalisedUrlsOption);
+};

package/src/server/index.ts

@@ -4,9 +4,10 @@ const { languageDetector } = honoPkg;
 
 import type { Context, Next, ServerPlugin } from '@modern-js/server-runtime';
 import type { LocaleDetectionOptions } from '../shared/type';
-import type { I18nUrlStrategy } from '../shared/urlStrategy';
+import { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
 import { getLocaleDetectionOptions } from '../shared/utils.js';
 import { collectApiPrefixes, matchesApiPrefix } from './apiPrefix.js';
+import { resolveDefaultUrlStrategy } from './defaultUrlStrategy.js';
 import { convertToHonoLanguageDetectorOptions } from './detectorOptions.js';
 import {
   buildLocalizedUrl,
@@ -70,17 +71,11 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
           entryLocaleDetection,
           'localisedUrls',
         );
-        const urlStrategy = options.resolveUrlStrategy?.(entryName);
-        if (
-          legacyLocalisedUrls &&
-          typeof legacyLocalisedUrls === 'object' &&
-          Object.keys(legacyLocalisedUrls).length > 0 &&
-          !urlStrategy
-        ) {
-          throw new Error(
-            'Mapped locale URLs require a URL strategy. Use the i18n integration server plugin or supply resolveUrlStrategy.',
-          );
-        }
+        // `localeDetection.localisedUrls` is self-sufficient: when no explicit
+        // strategy is supplied the plugin derives one from the map itself.
+        const urlStrategy =
+          asI18nUrlStrategy(options.resolveUrlStrategy?.(entryName)) ??
+          resolveDefaultUrlStrategy(legacyLocalisedUrls);
         const staticRoutePrefixes = options.staticRoutePrefixes;
         const originUrlPath = route.urlPath;
         const urlPath = originUrlPath.endsWith('/')

package/src/server/mappedUrlStrategy.ts

@@ -0,0 +1,10 @@
+/**
+ * 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';