@bleedingdev/modern-js-i18n-runtime-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/package.json

@@ -17,7 +17,7 @@
     "modern.js",
     "i18n"
   ],
-  "version": "3.9.0-ultramodern.2",
+  "version": "3.9.0-ultramodern.20",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
@@ -30,13 +30,35 @@
       },
       "default": "./dist/esm/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./router-navigation": {
+      "types": "./dist/types/router-navigation/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/router-navigation/index.mjs",
+        "require": "./dist/cjs/router-navigation/index.js"
+      },
+      "default": "./dist/esm/router-navigation/index.mjs"
+    },
+    "./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"
+      ],
+      "router-navigation": [
+        "./dist/types/router-navigation/index.d.ts"
       ]
     }
   },
@@ -44,20 +66,22 @@
     "node": ">=26.7.0"
   },
   "dependencies": {
+    "@modern-js/runtime-extensions": "npm:@bleedingdev/modern-js-runtime-extensions@3.9.0-ultramodern.20",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.20",
     "i18next-browser-languagedetector": "^8.2.1"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.2",
+    "@modern-js/runtime": "3.9.0-ultramodern.20",
     "react": "^19.2.8"
   },
   "devDependencies": {
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.2",
-    "@rslib/core": "1.0.0",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.20",
+    "@rslib/core": "1.0.2",
     "@scripts/rstest-config": "2.66.0",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -66,6 +90,6 @@
   "scripts": {
     "dev": "rslib build --watch",
     "build": "rslib build",
-    "test": "rstest --passWithNoTests"
+    "test": "rstest"
   }
 }

package/src/index.ts

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

package/src/localeRedirectPolicy.ts

@@ -0,0 +1,127 @@
+import type { LocalisedUrlsOption } from '@modern-js/runtime-extensions/localised-urls';
+import {
+  isDefaultLocaleRedirectSkipPath,
+  localiseTargetPathname,
+  matchesPathPrefix,
+  shouldSkipLocaleRedirect,
+  stripLanguagePrefix,
+} from '@modern-js/runtime-extensions/localised-urls';
+
+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/paths.ts

@@ -0,0 +1,37 @@
+import {
+  canonicalTargetPathname,
+  type LocalisedUrlsOption,
+  localiseTargetPathname,
+} from '@modern-js/runtime-extensions/localised-urls';
+import { splitUrlTarget } from '@modern-js/runtime-utils/url';
+
+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/src/router-navigation/adapter.tsx

@@ -0,0 +1,120 @@
+import { RuntimeContext } from '@modern-js/runtime';
+import { InternalRuntimeContext } from '@modern-js/runtime/context';
+import {
+  getRouterRuntimeState,
+  type RouterLinkTarget,
+  type RouterNavigationCapability,
+  type RouterNavigationSnapshot,
+  subscribeRouterRuntimeState,
+} from '@modern-js/runtime-extensions/router-state';
+import type React from 'react';
+import { useCallback, useContext, useSyncExternalStore } from 'react';
+
+export interface I18nRouterNavigationDependencies<
+  Adapter extends I18nRouterAdapterShape,
+> {
+  I18nNavigationProvider: React.ComponentType<
+    React.PropsWithChildren<{ value: Adapter }>
+  >;
+  useNativeI18nRouterAdapter: () => Adapter;
+}
+
+export type I18nRouterLinkTarget = RouterLinkTarget;
+
+export interface I18nRouterAdapterShape {
+  framework?: string;
+  hasRouter: boolean;
+  location: RouterNavigationSnapshot['location'] | null;
+  navigate: RouterNavigationCapability['navigate'] | null;
+  Link: RouterNavigationCapability['Link'] | null;
+  params: Record<string, string>;
+  createLinkProps?: RouterNavigationCapability['createLinkProps'];
+}
+
+const subscribeNone = () => () => {};
+const getEmptySnapshot = () => null;
+
+/** The router provider owns navigation; this seam only observes its capability. */
+export const createI18nRouterNavigation = <
+  Adapter extends I18nRouterAdapterShape,
+>({
+  I18nNavigationProvider,
+  useNativeI18nRouterAdapter,
+}: I18nRouterNavigationDependencies<Adapter>) => {
+  // The injected context accepts null to preserve native-router fallback.
+  const NavigationProvider = I18nNavigationProvider as React.ComponentType<
+    React.PropsWithChildren<{ value: Adapter | null }>
+  >;
+  const useIntegratedRouterAdapter = (): Adapter => {
+    const runtimeContext = useContext(RuntimeContext);
+    const internalContext = useContext(InternalRuntimeContext);
+    const native = useNativeI18nRouterAdapter();
+    const getCapability = useCallback(
+      () =>
+        getRouterRuntimeState(internalContext)?.navigation ??
+        getRouterRuntimeState(runtimeContext)?.navigation,
+      [internalContext, runtimeContext],
+    );
+    const subscribeCapability = useCallback(
+      (update: () => void) => {
+        const stopInternal = subscribeRouterRuntimeState(
+          internalContext,
+          update,
+        );
+        const stopPublic =
+          internalContext === runtimeContext
+            ? undefined
+            : subscribeRouterRuntimeState(runtimeContext, update);
+        return () => {
+          stopInternal();
+          stopPublic?.();
+        };
+      },
+      [internalContext, runtimeContext],
+    );
+    // Separate subscriptions handle both delayed installation/replacement and
+    // navigation inside the currently selected provider, without hook guessing.
+    const capability = useSyncExternalStore(
+      subscribeCapability,
+      getCapability,
+      getCapability,
+    );
+    const snapshot = useSyncExternalStore(
+      capability?.subscribe ?? subscribeNone,
+      capability?.getSnapshot ?? getEmptySnapshot,
+      capability?.getSnapshot ?? getEmptySnapshot,
+    );
+    if (native.hasRouter || !capability || !snapshot) {
+      return native;
+    }
+    const internalState = getRouterRuntimeState(internalContext);
+    return {
+      framework:
+        internalState?.navigation === capability
+          ? internalState.framework
+          : getRouterRuntimeState(runtimeContext)?.framework,
+      hasRouter: true,
+      ...snapshot,
+      navigate: capability.navigate,
+      Link: capability.Link,
+      createLinkProps: capability.createLinkProps,
+    } as Adapter;
+  };
+
+  const I18nRouterNavigationProvider = ({
+    children,
+  }: React.PropsWithChildren) => {
+    const value = useIntegratedRouterAdapter();
+    const native = useNativeI18nRouterAdapter();
+    // Keep the router subtree mounted when a capability arrives or disappears.
+    return (
+      <NavigationProvider
+        value={value.hasRouter && !native.hasRouter ? value : null}
+      >
+        {children}
+      </NavigationProvider>
+    );
+  };
+
+  return { useIntegratedRouterAdapter, I18nRouterNavigationProvider };
+};

package/src/router-navigation/index.ts

@@ -0,0 +1,6 @@
+export {
+  createI18nRouterNavigation,
+  type I18nRouterAdapterShape,
+  type I18nRouterLinkTarget,
+  type I18nRouterNavigationDependencies,
+} from './adapter';

package/tests/languageSyncController.test.ts

@@ -80,7 +80,6 @@ describe('latest language synchronization coordinator', () => {
 
     binding.request('cs');
     binding.request('de');
-    expect(pending.map(change => change.language)).toEqual(['cs', 'de']);
 
     pending[1].resolve();
     await pending[1].promise;
@@ -91,7 +90,6 @@ describe('latest language synchronization coordinator', () => {
     await pending[0].promise;
     await flush();
     expect(target.language).toBe('cs');
-    expect(pending.map(change => change.language)).toEqual(['cs', 'de', 'de']);
 
     pending[2].resolve();
     await pending[2].promise;
@@ -100,81 +98,6 @@ describe('latest language synchronization coordinator', () => {
     expect(commits.at(-1)).toBe('de');
   });
 
-  test('repairs a shared singleton after the starting mount leaves', async () => {
-    const target = { language: 'en' };
-    const { changeLanguage, pending } = deferredChanger(target);
-    const commits: string[] = [];
-    const first = createLatestLanguageSyncBinding<Target>();
-    const second = createLatestLanguageSyncBinding<Target>();
-    for (const binding of [first, second]) {
-      binding.updateCallbacks({
-        changeLanguage,
-        commitLanguage: (_target, language) => commits.push(language),
-        readLanguage: current => current.language,
-      });
-    }
-
-    first.activate(target);
-    first.request('cs');
-    first.deactivate();
-    second.activate(target);
-    second.request('de');
-
-    pending[1].resolve();
-    await pending[1].promise;
-    await flush();
-    pending[0].resolve();
-    await pending[0].promise;
-    await flush();
-
-    expect(pending.map(change => change.language)).toEqual(['cs', 'de', 'de']);
-    pending[2].resolve();
-    await pending[2].promise;
-    await flush();
-    expect(target.language).toBe('de');
-    expect(commits.at(-1)).toBe('de');
-  });
-
-  test('supersedes a hung same-language attempt and repairs it after a later route', async () => {
-    rstest.useFakeTimers();
-    const target = { language: 'en' };
-    const { changeLanguage, pending } = deferredChanger(target);
-    const commits: string[] = [];
-    const binding = createLatestLanguageSyncBinding<Target>({
-      attemptTimeoutMs: 100,
-      retryDelayMs: () => 10,
-    });
-    binding.updateCallbacks({
-      changeLanguage,
-      commitLanguage: (_target, language) => commits.push(language),
-      readLanguage: current => current.language,
-    });
-    binding.activate(target);
-    binding.request('cs');
-
-    await rstest.advanceTimersByTimeAsync(110);
-    expect(pending.map(change => change.language)).toEqual(['cs', 'cs']);
-    pending[1].resolve();
-    await pending[1].promise;
-    await flush();
-    expect(commits.at(-1)).toBe('cs');
-
-    binding.request('de');
-    pending[2].resolve();
-    await pending[2].promise;
-    await flush();
-    expect(target.language).toBe('de');
-
-    pending[0].resolve();
-    await pending[0].promise;
-    await flush();
-    expect(pending.at(-1)?.language).toBe('de');
-    pending.at(-1)?.resolve();
-    await pending.at(-1)?.promise;
-    await flush();
-    expect(target.language).toBe('de');
-  });
-
   test('bounds permanent failures and reports the final consequence once', async () => {
     rstest.useFakeTimers();
     const target = { language: 'en' };

package/tests/localeRedirectPolicy.test.ts

@@ -0,0 +1,173 @@
+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',
+      // A manifest may name a root entry; the federation layer serves these.
+      '/remoteEntry.catalog.js',
+      '/backendRemoteEntry.catalog-v2.cjs',
+      '/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);
+    }
+    // Only the entry itself, not a page or asset that merely starts like one.
+    for (const pathname of [
+      '/remoteEntry.catalog.js.map',
+      '/remoteEntry.catalog/js',
+      '/products/remoteEntry.js',
+    ]) {
+      expect(isStaticResourceRequest(pathname, [], languages)).toBe(false);
+    }
+  });
+
+  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);
+  });
+});
+
+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('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('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('');
+  });
+});

package/tests/paths.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from '@rstest/core';
+import { canonicalPath, localizePath } from '../src/paths';
+
+const config = {
+  languages: ['en', 'cs'],
+  localisedUrls: {
+    '/products/:slug': { en: '/products/:slug', cs: '/produkty/:slug' },
+  },
+};
+
+describe('@modern-js/i18n-runtime-extensions/paths', () => {
+  test('localises the pathname while leaving query and hash verbatim', () => {
+    expect(
+      localizePath(
+        '/products/red-shoe?tag=boots&tag=sale#details',
+        'cs',
+        config,
+      ),
+    ).toBe('/cs/produkty/red-shoe?tag=boots&tag=sale#details');
+    expect(
+      canonicalPath('/CS/produkty/red-shoe?tag=boots#details', config),
+    ).toBe('/products/red-shoe?tag=boots#details');
+  });
+});