@bleedingdev/modern-js-plugin-i18n 3.9.0-ultramodern.8 → 3.9.3-ultramodern.1

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@bleedingdev/modern-js-plugin-i18n",
   "description": "A Progressive React Framework for modern web development.",
-  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "homepage": "https://github.com/ultramodernjs/ultramodern.js#readme",
   "bugs": {
-    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+    "url": "https://github.com/ultramodernjs/ultramodern.js/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "url": "git+https://github.com/ultramodernjs/ultramodern.js.git",
     "directory": "packages/runtime/plugin-i18n"
   },
   "license": "MIT",
@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.9.0-ultramodern.8",
+  "version": "3.9.3-ultramodern.1",
   "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": {
@@ -104,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"
       ],
@@ -122,22 +132,23 @@
     }
   },
   "dependencies": {
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.8",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.8",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.8",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.9.0-ultramodern.8",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.0-ultramodern.8",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.8",
+    "@modern-js/i18n-runtime-extensions": "npm:@bleedingdev/modern-js-i18n-runtime-extensions@3.9.3-ultramodern.1",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.3-ultramodern.1",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.3-ultramodern.1",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.3-ultramodern.1",
+    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.9.3-ultramodern.1",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.9.3-ultramodern.1",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.3-ultramodern.1",
     "@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.8",
-    "i18next": ">=25.7.4",
+    "@modern-js/runtime": "3.9.3-ultramodern.1",
+    "i18next": ">=25.10.10",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-i18next": ">=15.7.4"
@@ -151,26 +162,34 @@
     }
   },
   "devDependencies": {
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.0-ultramodern.8",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.8",
-    "@rslib/core": "1.0.0",
-    "@types/node": "^26.4.1",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.3-ultramodern.1",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.3-ultramodern.1",
+    "@modern-js/runtime-extensions": "npm:@bleedingdev/modern-js-runtime-extensions@3.9.3-ultramodern.1",
+    "@rslib/core": "1.0.3",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.6.3",
     "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"
+    "typescript": "7.0.2"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "dev": "rslib build --watch",
     "build": "rslib build",
-    "test": "rstest --passWithNoTests"
+    "test": "rstest"
+  },
+  "ultramodern": {
+    "sourceName": "@modern-js/plugin-i18n"
   }
 }

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,29 @@ 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,
+        entrypoint,
+      ) as typeof routes,
+    }));
+
     api._internalServerPlugins(({ plugins }) => {
       const { serverRoutes, metaName } = api.getAppContext();
       const normalizedConfig = api.getNormalizedConfig();

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;
+};

package/src/runtime/context.tsx

@@ -1,12 +1,6 @@
 import { RuntimeComponentResolverContext } from '@modern-js/runtime/context';
 import type { ComponentType, FC, ReactNode } from 'react';
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-} from 'react';
+import { useCallback, useContext, useEffect, useMemo } from 'react';
 import type { I18nUrlStrategy } from '../shared/urlStrategy';
 import {
   changeModernI18nLanguage,
@@ -19,6 +13,10 @@ import type { I18nInstance } from './i18n';
 import type { Resources } from './i18n/instance';
 
 import { useI18nRouterAdapter } from './routerAdapter';
+import {
+  ModernI18nContext,
+  ReactI18nextProviderContext,
+} from './sharedContexts';
 
 export { getActualI18nextInstance } from './i18n/instance';
 
@@ -36,30 +34,7 @@ export interface ModernI18nContextValue {
   synchronizeLanguage?: (newLang: string) => void;
 }
 
-const modernI18nContextKey = Symbol.for(
-  '@modern-js/plugin-i18n/runtime/ModernI18nContext',
-);
-const reactI18nextProviderContextKey = Symbol.for(
-  '@modern-js/plugin-i18n/runtime/ReactI18nextProviderContext',
-);
-
-type GlobalContextStore<T> = typeof globalThis & {
-  [key: symbol]: ReturnType<typeof createContext<T>> | undefined;
-};
-
-const getGlobalContext = <T,>(key: symbol, defaultValue: T) => {
-  const globalStore = globalThis as GlobalContextStore<T>;
-  globalStore[key] ??= createContext<T>(defaultValue);
-  return globalStore[key];
-};
-
-export const ModernI18nContext =
-  getGlobalContext<ModernI18nContextValue | null>(modernI18nContextKey, null);
-export const ReactI18nextProviderContext =
-  getGlobalContext<ComponentType<any> | null>(
-    reactI18nextProviderContextKey,
-    null,
-  );
+export { ModernI18nContext, ReactI18nextProviderContext };
 
 export interface ModernI18nProviderProps {
   children: ReactNode;

package/src/runtime/contexts.ts

@@ -0,0 +1,16 @@
+import type { ComponentType } from 'react';
+import { createContext } from 'react';
+import type { ModernI18nContextValue } from './context';
+import type { I18nRouterAdapter } from './routerAdapter';
+
+// Every other i18n runtime module imports these through
+// `@modern-js/plugin-i18n/runtime/contexts` so Module Federation shares one
+// copy of them. Their values stay provider-owned.
+export const ModernI18nContext = createContext<ModernI18nContextValue | null>(
+  null,
+);
+export const ReactI18nextProviderContext =
+  createContext<ComponentType<any> | null>(null);
+export const I18nNavigationContext = createContext<I18nRouterAdapter | null>(
+  null,
+);

package/src/runtime/core.tsx

@@ -1,11 +1,13 @@
 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 { I18nRouterNavigationProvider } from './navigation';
 import {
   type RuntimeContextWithI18n,
   setupI18nBeforeRender,
@@ -31,6 +33,10 @@ export type {
   Resources,
   TranslateFn,
 } from './i18n/instance';
+export {
+  I18nRouterNavigationProvider,
+  useIntegratedRouterAdapter,
+} from './navigation';
 export type {
   LoadReactI18nextIntegration,
   ReactI18nextIntegration,
@@ -86,6 +92,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,8 +141,14 @@ export const createI18nPlugin =
           languages,
           fallbackLanguage,
           ignoreRedirectRoutes,
-          urlStrategy,
-          NavigationProvider,
+          urlStrategy: resolvedUrlStrategy,
+          // The selected router, not react-router, is what a localized `<Link>`
+          // has to navigate through, and the i18n language has to follow a
+          // client-side navigation to a mapped URL. Both need the actual router
+          // instance, so a bare `appTools()` consumer gets the integrated
+          // adapter by default; a composing runtime plugin can still replace it.
+          NavigationProvider:
+            NavigationProvider ?? I18nRouterNavigationProvider,
           LanguageSynchronization,
           getLatestI18nInstance: () => latestI18nInstance,
           getI18nextProvider: () => I18nextProvider,

package/src/runtime/i18n/detection/middleware.node.ts

@@ -1,4 +1,5 @@
 import { LanguageDetector } from 'i18next-http-middleware';
+import { detectLanguageFromRequest } from '../../../shared/detection.js';
 import type { I18nInstance, LanguageDetectorOptions } from '../instance';
 
 type HttpDetectorInit = (
@@ -13,6 +14,20 @@ type HttpDetectorDetect = (
   detectionOrder?: unknown,
 ) => string | string[] | undefined;
 
+type DetectionRequest = Parameters<typeof detectLanguageFromRequest>[0];
+
+const isDetectionRequest = (request: unknown): request is DetectionRequest => {
+  if (!request || typeof request !== 'object') {
+    return false;
+  }
+
+  const { url, headers } = request as {
+    url?: unknown;
+    headers?: unknown;
+  };
+  return typeof url === 'string' && !!headers && typeof headers === 'object';
+};
+
 export const cacheUserLanguage = (
   _i18nInstance: I18nInstance,
   _language: string,
@@ -21,15 +36,18 @@ export const cacheUserLanguage = (
   return;
 };
 
-/**
- * Read language directly from storage (localStorage/cookie)
- * Not available in Node.js environment, returns undefined
- */
 export const readLanguageFromStorage = (
-  _detectionOptions?: LanguageDetectorOptions,
+  detectionOptions?: LanguageDetectorOptions,
+  request?: unknown,
+  languages: string[] = [],
 ): string | undefined => {
-  // In Node.js environment, storage-based detection is not available
-  return undefined;
+  if (!isDetectionRequest(request)) {
+    return undefined;
+  }
+
+  return (
+    detectLanguageFromRequest(request, languages, detectionOptions) ?? undefined
+  );
 };
 /**
  * Register LanguageDetector plugin to i18n instance

package/src/runtime/i18n/detection/middleware.ts

@@ -30,6 +30,8 @@ export const useI18nextLanguageDetector = (i18nInstance: I18nInstance) => {
  */
 export const readLanguageFromStorage = (
   detectionOptions?: LanguageDetectorOptions,
+  _request?: unknown,
+  _languages?: string[],
 ): string | undefined => {
   try {
     const options = detectionOptions || {};

package/src/runtime/i18n/detection/priority.ts

@@ -59,6 +59,8 @@ export const detectLanguageWithPriority = async (
           localePathRedirect,
           userInitOptions,
         ),
+        ssrContext?.request,
+        languages,
       );
     } else {
       detectedLanguage = await detectLanguageFromI18nextDetector(i18nInstance, {

package/src/runtime/navigation.tsx

@@ -0,0 +1,20 @@
+import { createI18nRouterNavigation } from '@modern-js/i18n-runtime-extensions/router-navigation';
+import {
+  I18nNavigationProvider,
+  type I18nRouterAdapter,
+  useNativeI18nRouterAdapter,
+} from './routerAdapter';
+
+/**
+ * The seam, and only the seam. The selected-router navigation adapter is a
+ * fork subsystem, so it lives in the fork-owned
+ * `@modern-js/i18n-runtime-extensions` and is attached here through the
+ * `NavigationProvider` extension point this package already exposes. The
+ * factory takes this package's own primitives as arguments, so the fork
+ * package never imports back into it and the dependency stays one-way.
+ */
+export const { I18nRouterNavigationProvider, useIntegratedRouterAdapter } =
+  createI18nRouterNavigation<I18nRouterAdapter>({
+    I18nNavigationProvider,
+    useNativeI18nRouterAdapter,
+  });

package/src/runtime/routerAdapter.tsx

@@ -1,7 +1,8 @@
+import { I18nNavigationContext } from '@modern-js/plugin-i18n/runtime/contexts';
 import { isBrowser, RuntimeContext } from '@modern-js/runtime';
 import { InternalRuntimeContext } from '@modern-js/runtime/context';
 import type React from 'react';
-import { createContext, useContext } from 'react';
+import { useContext } from 'react';
 
 interface I18nRouterLocation {
   pathname: string;
@@ -44,16 +45,6 @@ export interface I18nRouterAdapter {
   };
 }
 
-const navigationContextKey = Symbol.for(
-  '@modern-js/plugin-i18n/runtime/I18nNavigationContext',
-);
-// Only the React context identity is shared. Its values remain provider-owned.
-const contextStore = globalThis as typeof globalThis & {
-  [navigationContextKey]?: React.Context<I18nRouterAdapter | null>;
-};
-const I18nNavigationContext = (contextStore[navigationContextKey] ??=
-  createContext<I18nRouterAdapter | null>(null));
-
 export const I18nNavigationProvider = ({
   children,
   value,

package/src/runtime/sharedContexts.ts

@@ -0,0 +1,8 @@
+// Upstream-owned runtime modules take the i18n contexts from this fork-owned
+// module, which reaches them through the shared
+// `@modern-js/plugin-i18n/runtime/contexts` request. That keeps the fork
+// import edge out of the upstream-owned files.
+export {
+  ModernI18nContext,
+  ReactI18nextProviderContext,
+} from '@modern-js/plugin-i18n/runtime/contexts';

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';