@bleedingdev/modern-js-i18n-runtime-extensions 3.9.0-ultramodern.3 → 3.9.0-ultramodern.5

package/dist/esm-node/localisedUrls/routes.mjs

@@ -102,6 +102,14 @@ const transformLocalisedRoute = (route, parentCanonicalPath, parentLocalisedPath
     const children = 'children' in route && route.children ? route.children.flatMap((child)=>transformLocalisedRoute(child, canonicalPath, routeLocalisedPaths, languages, localisedUrls)) : void 0;
     const baseRoute = {
         ...route,
+        ...!isFrameworkInternalRoutePath(canonicalPath) ? {
+            modernLocalisedRoute: {
+                id: route.id,
+                path: route.path,
+                canonicalPath,
+                paths: localisedUrlEntry
+            }
+        } : {},
         ...children ? {
             children
         } : {}

package/dist/esm-node/paths.mjs

@@ -0,0 +1,13 @@
+import "node:module";
+import { splitUrlTarget } from "@modern-js/runtime-utils/url";
+import { canonicalTargetPathname, localiseTargetPathname } from "./localisedUrls/index.mjs";
+const buildLocalizedUrl = (target, language, languages, localisedUrls)=>{
+    const { pathname, search, hash } = splitUrlTarget(target);
+    return `${localiseTargetPathname(pathname, language, languages, localisedUrls)}${search}${hash}`;
+};
+const localizePath = (target, language, config)=>buildLocalizedUrl(target, language, config.languages, config.localisedUrls);
+const canonicalPath = (target, config)=>{
+    const { pathname, search, hash } = splitUrlTarget(target);
+    return `${canonicalTargetPathname(pathname, config.languages, config.localisedUrls)}${search}${hash}`;
+};
+export { buildLocalizedUrl, canonicalPath, localizePath };

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from './language-sync/controller.js';
 export * from './language-sync/react.js';
+export * from './localeRedirectPolicy.js';
 export * from './localisedUrls/index.js';

package/dist/types/localeRedirectPolicy.d.ts

@@ -0,0 +1,22 @@
+import type { LocalisedUrlsOption } from './localisedUrls/index.js';
+interface LocaleRedirectRequest {
+    url: string;
+    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 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?: LocalisedUrlsOption) => string;
+export declare const createLocaleRedirectResponse: (location: string) => Response;
+export {};

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

@@ -5,5 +5,6 @@ export { buildPathFromPattern, matchPathPattern } from './patterns.js';
 export type { LocaleRedirectSkipRule } from './redirect.js';
 export { DEFAULT_LOCALE_REDIRECT_SKIP_RULES, isDefaultLocaleRedirectSkipPath, matchesPathPrefix, shouldSkipLocaleRedirect, } from './redirect.js';
 export { resolveCanonicalLocalisedPath, resolveLocalisedPath } from './resolve.js';
+export { canonicaliseLocalisedRoutes, createLocalisedRouteRewrite, } from './routeIdentity.js';
 export { applyLocalisedUrlsToRoutes, validateLocalisedUrls } from './routes.js';
 export type { LocalisedRoute, LocalisedUrlPathMap, LocalisedUrlsMap, LocalisedUrlsOption, ResolvedLocalisedUrlsConfig, } from './types.js';

package/dist/types/localisedUrls/routeIdentity.d.ts

@@ -0,0 +1,24 @@
+interface RouteIdentity {
+    id?: string;
+    path?: string;
+    canonicalPath: string;
+    paths?: Record<string, string>;
+}
+interface RouteNode {
+    id?: string;
+    path?: string;
+    children?: RouteNode[];
+    modernLocalisedRoute?: RouteIdentity;
+}
+/** Restore one source route identity for routers with strict route-ID hooks. */
+export declare function canonicaliseLocalisedRoutes<T extends RouteNode>(routes: T[]): T[];
+/** Use the router's URL rewrite seam; browser URLs retain their locale spelling. */
+export declare function createLocalisedRouteRewrite(routes: RouteNode[]): {
+    input: ({ url }: {
+        url: URL;
+    }) => URL;
+    output: ({ url }: {
+        url: URL;
+    }) => URL;
+} | undefined;
+export {};

package/dist/types/paths.d.ts

@@ -0,0 +1,9 @@
+import { type LocalisedUrlsOption } from './localisedUrls/index.js';
+export interface LocalizedPathsConfig {
+    languages: string[];
+    localisedUrls?: LocalisedUrlsOption;
+}
+/** Synchronous mapped URL construction, independent of React/plugin setup. */
+export declare const buildLocalizedUrl: (target: string, language: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;
+export declare const localizePath: (target: string, language: string, config: LocalizedPathsConfig) => string;
+export declare const canonicalPath: (target: string, config: LocalizedPathsConfig) => string;

package/package.json

@@ -17,7 +17,7 @@
     "modern.js",
     "i18n"
   ],
-  "version": "3.9.0-ultramodern.3",
+  "version": "3.9.0-ultramodern.5",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
@@ -30,13 +30,24 @@
       },
       "default": "./dist/esm/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./paths": {
+      "types": "./dist/types/paths.d.ts",
+      "node": {
+        "import": "./dist/esm-node/paths.mjs",
+        "require": "./dist/cjs/paths.js"
+      },
+      "default": "./dist/esm/paths.mjs"
+    }
   },
   "typesVersions": {
     "*": {
       ".": [
         "./dist/types/index.d.ts",
         "./src/index.ts"
+      ],
+      "paths": [
+        "./dist/types/paths.d.ts"
       ]
     }
   },
@@ -44,14 +55,15 @@
     "node": ">=26.7.0"
   },
   "dependencies": {
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.5",
     "i18next-browser-languagedetector": "^8.2.1"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.3",
+    "@modern-js/runtime": "3.9.0-ultramodern.5",
     "react": "^19.2.8"
   },
   "devDependencies": {
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.3",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.5",
     "@rslib/core": "1.0.0",
     "@scripts/rstest-config": "2.66.0",
     "@types/node": "^26.4.1",

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './language-sync/controller';
 export * from './language-sync/react';
+export * from './localeRedirectPolicy';
 export * from './localisedUrls/index';

package/src/localeRedirectPolicy.ts

@@ -0,0 +1,127 @@
+import type { LocalisedUrlsOption } from './localisedUrls/index';
+import {
+  isDefaultLocaleRedirectSkipPath,
+  localiseTargetPathname,
+  matchesPathPrefix,
+  shouldSkipLocaleRedirect,
+  stripLanguagePrefix,
+} from './localisedUrls/index';
+
+interface LocaleRedirectRequest {
+  url: string;
+  header: () => {
+    host?: string;
+  };
+}
+
+const stripUrlPathPrefix = (pathname: string, urlPath: string): string => {
+  const basePath = urlPath.replace('/*', '');
+
+  if (!basePath || basePath === '/') {
+    return pathname;
+  }
+
+  const remainingPath = pathname.startsWith(basePath)
+    ? pathname.slice(basePath.length)
+    : pathname;
+
+  return remainingPath || '/';
+};
+
+/**
+ * Check if pathname should ignore automatic locale redirect.
+ */
+export const shouldIgnoreRedirect = (
+  pathname: string,
+  urlPath: string,
+  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
+): boolean => {
+  const remainingPath = stripUrlPathPrefix(pathname, urlPath);
+
+  return shouldSkipLocaleRedirect(remainingPath, [], ignoreRedirectRoutes);
+};
+
+/**
+ * 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 const isStaticResourceRequest = (
+  pathname: string,
+  staticRoutePrefixes: string[],
+  languages: string[] = [],
+): boolean => {
+  if (isDefaultLocaleRedirectSkipPath(pathname, languages)) {
+    return true;
+  }
+
+  const matchesStaticRoutePrefix = (targetPathname: string): boolean =>
+    staticRoutePrefixes.some(prefix =>
+      matchesPathPrefix(targetPathname, prefix),
+    );
+
+  if (matchesStaticRoutePrefix(pathname)) {
+    return true;
+  }
+
+  const pathWithoutLanguage = stripLanguagePrefix(pathname, languages);
+
+  return (
+    pathWithoutLanguage !== pathname &&
+    matchesStaticRoutePrefix(pathWithoutLanguage)
+  );
+};
+
+export const getLanguageFromPath = (
+  req: LocaleRedirectRequest,
+  urlPath: string,
+  languages: string[],
+): string | null => {
+  const url = new URL(req.url, `http://${req.header().host}`);
+  const pathname = url.pathname;
+  const remainingPath = stripUrlPathPrefix(pathname, urlPath);
+  const segments = remainingPath.split('/').filter(Boolean);
+  const firstSegment = segments[0];
+
+  if (languages.includes(firstSegment)) {
+    return firstSegment;
+  }
+
+  return null;
+};
+
+export const buildLocalizedUrl = (
+  req: LocaleRedirectRequest,
+  urlPath: string,
+  language: string,
+  languages: string[],
+  localisedUrls?: LocalisedUrlsOption,
+): string => {
+  const url = new URL(req.url);
+  const pathname = url.pathname;
+  const basePath = urlPath.replace('/*', '');
+  const remainingPath = stripUrlPathPrefix(pathname, urlPath);
+
+  const newPathname = localiseTargetPathname(
+    remainingPath,
+    language,
+    languages,
+    localisedUrls,
+  );
+  const suffix = `${url.search}${url.hash}`;
+  const localizedUrl =
+    basePath === '/' ? newPathname + suffix : basePath + newPathname + suffix;
+
+  return localizedUrl;
+};
+
+export const createLocaleRedirectResponse = (location: string): Response =>
+  new Response(null, {
+    status: 302,
+    headers: {
+      'Cache-Control': 'private, no-store',
+      Location: location,
+      Vary: 'Accept-Language, Cookie',
+    },
+  });

package/src/localisedUrls/index.ts

@@ -14,6 +14,10 @@ export {
   shouldSkipLocaleRedirect,
 } from './redirect';
 export { resolveCanonicalLocalisedPath, resolveLocalisedPath } from './resolve';
+export {
+  canonicaliseLocalisedRoutes,
+  createLocalisedRouteRewrite,
+} from './routeIdentity';
 export { applyLocalisedUrlsToRoutes, validateLocalisedUrls } from './routes';
 export type {
   LocalisedRoute,

package/src/localisedUrls/routeIdentity.ts

@@ -0,0 +1,107 @@
+import { normalisePathPattern } from './normalise';
+import { buildPathFromPattern, matchPathPattern } from './patterns';
+
+interface RouteIdentity {
+  id?: string;
+  path?: string;
+  canonicalPath: string;
+  paths?: Record<string, string>;
+}
+
+interface RouteNode {
+  id?: string;
+  path?: string;
+  children?: RouteNode[];
+  modernLocalisedRoute?: RouteIdentity;
+}
+
+/** Restore one source route identity for routers with strict route-ID hooks. */
+export function canonicaliseLocalisedRoutes<T extends RouteNode>(
+  routes: T[],
+): T[] {
+  const seen = new Set<string>();
+  return routes.flatMap(route => {
+    const identity = route.modernLocalisedRoute;
+    const key = identity?.id ?? identity?.path;
+    if (key !== undefined) {
+      if (seen.has(key)) return [];
+      seen.add(key);
+    }
+    return [
+      {
+        ...route,
+        ...(identity ? { id: identity.id, path: identity.path } : {}),
+        ...(route.children
+          ? { children: canonicaliseLocalisedRoutes(route.children) }
+          : {}),
+      },
+    ];
+  });
+}
+
+type PathRewrite = { from: string; to: string };
+
+function rewritePath(url: URL, mappings: PathRewrite[]) {
+  for (const { from, to } of mappings) {
+    const params = matchPathPattern(url.pathname, from);
+    if (params) {
+      url.pathname = buildPathFromPattern(to, params);
+      break;
+    }
+  }
+  return url;
+}
+
+/** Use the router's URL rewrite seam; browser URLs retain their locale spelling. */
+export function createLocalisedRouteRewrite(routes: RouteNode[]) {
+  const input: PathRewrite[] = [];
+  const output: PathRewrite[] = [];
+  const visit = (nodes: RouteNode[], parent: string) => {
+    for (const route of nodes) {
+      const fullPath = normalisePathPattern(`${parent}/${route.path ?? ''}`);
+      const identity = route.modernLocalisedRoute;
+      if (identity?.paths && fullPath.endsWith(identity.canonicalPath)) {
+        const prefix = fullPath.slice(0, -identity.canonicalPath.length);
+        const hasLocale = prefix
+          .split('/')
+          .some(segment => /^:(?:lang|locale|language)\??$/.test(segment));
+        for (const [language, localisedPath] of Object.entries(
+          identity.paths,
+        )) {
+          const localePrefix = prefix
+            .split('/')
+            .map(segment =>
+              /^:(?:lang|locale|language)\??$/.test(segment)
+                ? language
+                : segment,
+            )
+            .join('/');
+          const canonical = normalisePathPattern(
+            `${localePrefix}/${identity.canonicalPath}`,
+          );
+          const localised = normalisePathPattern(
+            `${localePrefix}/${localisedPath}`,
+          );
+          if (canonical !== localised) {
+            input.push({ from: localised, to: canonical });
+            if (hasLocale) output.push({ from: canonical, to: localised });
+          }
+        }
+      }
+      if (route.children) visit(route.children, fullPath);
+    }
+  };
+  visit(canonicaliseLocalisedRoutes(routes), '');
+  if (input.length === 0) return undefined;
+  const specificity = (pattern: string) =>
+    pattern
+      .split('/')
+      .filter(segment => segment && !segment.startsWith(':') && segment !== '*')
+      .length;
+  for (const mappings of [input, output])
+    mappings.sort((a, b) => specificity(b.from) - specificity(a.from));
+  return {
+    input: ({ url }: { url: URL }) => rewritePath(url, input),
+    output: ({ url }: { url: URL }) => rewritePath(url, output),
+  };
+}

package/src/localisedUrls/routes.ts

@@ -291,6 +291,16 @@ const transformLocalisedRoute = (
 
   const baseRoute = {
     ...route,
+    ...(!isFrameworkInternalRoutePath(canonicalPath)
+      ? {
+          modernLocalisedRoute: {
+            id: route.id,
+            path: route.path,
+            canonicalPath,
+            paths: localisedUrlEntry,
+          },
+        }
+      : {}),
     ...(children ? { children } : {}),
   } as LocalisedRoute;
 

package/src/paths.ts

@@ -0,0 +1,37 @@
+import { splitUrlTarget } from '@modern-js/runtime-utils/url';
+import {
+  canonicalTargetPathname,
+  type LocalisedUrlsOption,
+  localiseTargetPathname,
+} from './localisedUrls';
+
+export interface LocalizedPathsConfig {
+  languages: string[];
+  localisedUrls?: LocalisedUrlsOption;
+}
+
+/** Synchronous mapped URL construction, independent of React/plugin setup. */
+export const buildLocalizedUrl = (
+  target: string,
+  language: string,
+  languages: string[],
+  localisedUrls?: LocalisedUrlsOption,
+): string => {
+  const { pathname, search, hash } = splitUrlTarget(target);
+  return `${localiseTargetPathname(pathname, language, languages, localisedUrls)}${search}${hash}`;
+};
+
+export const localizePath = (
+  target: string,
+  language: string,
+  config: LocalizedPathsConfig,
+): string =>
+  buildLocalizedUrl(target, language, config.languages, config.localisedUrls);
+
+export const canonicalPath = (
+  target: string,
+  config: LocalizedPathsConfig,
+): string => {
+  const { pathname, search, hash } = splitUrlTarget(target);
+  return `${canonicalTargetPathname(pathname, config.languages, config.localisedUrls)}${search}${hash}`;
+};

package/tests/localeRedirectPolicy.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from '@rstest/core';
+import {
+  buildLocalizedUrl,
+  createLocaleRedirectResponse,
+  getLanguageFromPath,
+  isStaticResourceRequest,
+  shouldIgnoreRedirect,
+} from '../src/localeRedirectPolicy';
+
+const languages = ['en', 'cs'];
+const request = (url: string) => ({
+  url,
+  header: () => ({ host: 'example.com' }),
+});
+
+describe('locale redirect resource policy', () => {
+  test('exempts default static and federation routes, including locale prefixes', () => {
+    const paths = [
+      '/backend-mf-manifest.json',
+      '/backendRemoteEntry.cjs',
+      '/mf-manifest.json',
+      '/mf-stats.json',
+      '/remoteEntry.js',
+      '/static/app.js',
+      '/upload/avatar.png',
+    ];
+
+    for (const pathname of paths) {
+      expect(isStaticResourceRequest(pathname, [], languages)).toBe(true);
+      expect(isStaticResourceRequest(`/cs${pathname}`, [], languages)).toBe(
+        true,
+      );
+      expect(shouldIgnoreRedirect(`/store${pathname}`, '/store/*')).toBe(true);
+    }
+  });
+
+  test('configured static prefixes match complete path segments with or without a locale', () => {
+    for (const pathname of ['/assets', '/assets/app.js', '/en/assets/app.js']) {
+      expect(isStaticResourceRequest(pathname, ['/assets/'], languages)).toBe(
+        true,
+      );
+    }
+    for (const pathname of [
+      '/assets-extra/app.js',
+      '/cs/assets-extra/app.js',
+    ]) {
+      expect(isStaticResourceRequest(pathname, ['/assets'], languages)).toBe(
+        false,
+      );
+    }
+    expect(
+      isStaticResourceRequest('/fr/assets/app.js', ['/assets'], languages),
+    ).toBe(false);
+    expect(
+      isStaticResourceRequest('/remoteEntry.js/product', [], languages),
+    ).toBe(false);
+    expect(isStaticResourceRequest('/static-product', [])).toBe(false);
+  });
+
+  test('custom ignore lists operate after stripping the mount path', () => {
+    expect(
+      shouldIgnoreRedirect('/store/health/live', '/store/*', ['/health']),
+    ).toBe(true);
+    expect(
+      shouldIgnoreRedirect('/store/healthy', '/store/*', ['/health']),
+    ).toBe(false);
+    expect(shouldIgnoreRedirect('/store/products', '/store/*')).toBe(false);
+  });
+
+  test('custom callbacks receive the remaining pathname and default exemptions take priority', () => {
+    const seen: string[] = [];
+    const ignore = (pathname: string) => {
+      seen.push(pathname);
+      return pathname === '/health';
+    };
+
+    expect(shouldIgnoreRedirect('/store/health', '/store/*', ignore)).toBe(
+      true,
+    );
+    expect(shouldIgnoreRedirect('/store/products', '/store/*', ignore)).toBe(
+      false,
+    );
+    expect(
+      shouldIgnoreRedirect('/store/static/app.js', '/store/*', ignore),
+    ).toBe(true);
+    expect(seen).toEqual(['/health', '/products']);
+  });
+
+  test('preserves startsWith mount removal and empty remaining path behavior', () => {
+    expect(shouldIgnoreRedirect('/storefront', '/store/*', ['/front'])).toBe(
+      true,
+    );
+    expect(shouldIgnoreRedirect('/store', '/store/*', ['/'])).toBe(true);
+    expect(shouldIgnoreRedirect('/health', '', ['/health'])).toBe(true);
+    expect(shouldIgnoreRedirect('/health', '/', ['/health'])).toBe(true);
+    expect(shouldIgnoreRedirect('/health', '/other/*', ['/health'])).toBe(true);
+  });
+});
+
+describe('locale redirect URL policy', () => {
+  test('detects a configured first language segment for relative or absolute URLs', () => {
+    expect(
+      getLanguageFromPath(
+        request('/store/cs/products?x=1'),
+        '/store/*',
+        languages,
+      ),
+    ).toBe('cs');
+    expect(
+      getLanguageFromPath(
+        request('https://example.com/en/products'),
+        '/',
+        languages,
+      ),
+    ).toBe('en');
+    expect(getLanguageFromPath(request('/cs/products'), '', languages)).toBe(
+      'cs',
+    );
+    expect(
+      getLanguageFromPath(request('/storecs/products'), '/store/*', languages),
+    ).toBe('cs');
+  });
+
+  test('retains case-sensitive language detection and does not search later segments', () => {
+    for (const pathname of [
+      '/store',
+      '/store/CS/products',
+      '/store/fr/products',
+      '/store/products/cs',
+    ]) {
+      expect(
+        getLanguageFromPath(request(pathname), '/store/*', languages),
+      ).toBeNull();
+    }
+  });
+
+  test('switches localized dynamic paths while preserving mount, query and hash', () => {
+    expect(
+      buildLocalizedUrl(
+        request(
+          'https://example.com/store/en/products/red%20tractor?q=a%2Fb&sort=price#details',
+        ),
+        '/store/*',
+        'cs',
+        languages,
+        { '/products/:slug': { en: '/products/:slug', cs: '/produkty/:slug' } },
+      ),
+    ).toBe('/store/cs/produkty/red%20tractor?q=a%2Fb&sort=price#details');
+  });
+
+  test('supports root and empty mounts and missing locale mapping', () => {
+    for (const mount of ['/', '', '/*']) {
+      expect(
+        buildLocalizedUrl(
+          request('https://example.com/products?x=1#top'),
+          mount,
+          'cs',
+          languages,
+        ),
+      ).toBe('/cs/products?x=1#top');
+    }
+    expect(
+      buildLocalizedUrl(
+        request('https://example.com/store'),
+        '/store/*',
+        'cs',
+        languages,
+        false,
+      ),
+    ).toBe('/store/cs');
+  });
+
+  test('preserves the existing nonmatching and partial mount behavior', () => {
+    expect(
+      buildLocalizedUrl(
+        request('https://example.com/products'),
+        '/store/*',
+        'cs',
+        languages,
+      ),
+    ).toBe('/store/cs/products');
+    expect(
+      buildLocalizedUrl(
+        request('https://example.com/storefront'),
+        '/store/*',
+        'cs',
+        languages,
+      ),
+    ).toBe('/store/cs/front');
+  });
+
+  test('returns a non-cacheable temporary redirect with language negotiation headers', async () => {
+    const response = createLocaleRedirectResponse(
+      '/cs/produkty?sort=price#details',
+    );
+
+    expect(response.status).toBe(302);
+    expect(response.headers.get('Location')).toBe(
+      '/cs/produkty?sort=price#details',
+    );
+    expect(response.headers.get('Cache-Control')).toBe('private, no-store');
+    expect(response.headers.get('Vary')).toBe('Accept-Language, Cookie');
+    expect(await response.text()).toBe('');
+  });
+});