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

package/src/runtime/routerAdapter.tsx

@@ -1,14 +1,8 @@
+import { I18nNavigationContext } from '@modern-js/plugin-i18n/runtime/contexts';
 import { isBrowser, RuntimeContext } from '@modern-js/runtime';
-import {
-  getRouterRuntimeState,
-  InternalRuntimeContext,
-  type TInternalRuntimeContext,
-  type TRuntimeContext,
-} from '@modern-js/runtime/context';
+import { InternalRuntimeContext } from '@modern-js/runtime/context';
 import type React from 'react';
-import { useCallback, useContext, useSyncExternalStore } from 'react';
-
-type I18nRouterFramework = 'react-router' | 'tanstack' | string;
+import { useContext } from 'react';
 
 interface I18nRouterLocation {
   pathname: string;
@@ -16,14 +10,9 @@ interface I18nRouterLocation {
   hash: string;
 }
 
-interface I18nRouterNavigateOptions {
-  replace?: boolean;
-  state?: unknown;
-}
-
 type I18nRouterNavigate = (
   href: string,
-  options?: I18nRouterNavigateOptions,
+  options?: { replace?: boolean; state?: unknown },
 ) => void | Promise<void>;
 
 type I18nRouterLink = React.ComponentType<{
@@ -32,345 +21,82 @@ type I18nRouterLink = React.ComponentType<{
   [key: string]: unknown;
 }>;
 
-interface I18nRouterAdapter {
-  framework?: I18nRouterFramework;
+export interface I18nRouterLinkTarget {
+  pathname: string;
+  href: string;
+  search?: Record<string, unknown>;
+  hash?: string;
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+  prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  preload?: unknown;
+}
+
+export interface I18nRouterAdapter {
+  framework?: string;
   hasRouter: boolean;
   location: I18nRouterLocation | null;
   navigate: I18nRouterNavigate | null;
   Link: I18nRouterLink | null;
   params: Record<string, string>;
-}
-
-type RuntimeContextWithRouter = TRuntimeContext & {
-  router?: {
-    useInRouterContext?: () => boolean;
-    useRouter?: (options?: { warn?: boolean }) => unknown;
-    useLocation?: () => unknown;
-    useNavigate?: () => I18nRouterNavigate;
-    useParams?: () => Record<string, string>;
-    useHref?: () => unknown;
-    Link?: I18nRouterLink;
-  };
-};
-
-type InternalRuntimeContextWithRouter = TInternalRuntimeContext & {
-  router?: RuntimeContextWithRouter['router'];
-};
-
-type RouterInstance = {
-  navigate?: (...args: any[]) => unknown;
-  state?: {
-    location?: unknown;
-    matches?: Array<{ params?: Record<string, string> }>;
-  };
-  stores?: {
-    location?: {
-      get?: () => unknown;
-      subscribe?: (listener: () => void) => () => void;
-    };
-    matches?: {
-      get?: () => Array<{ params?: Record<string, string> }>;
-    };
-  };
-  subscribe?:
-    | ((listener: () => void) => () => void)
-    | ((eventType: string, listener: () => void) => () => void);
-};
-
-const normalizeUrlPart = (value: unknown, prefix: '?' | '#'): string => {
-  if (typeof value !== 'string' || !value) {
-    return '';
-  }
-  return value.startsWith(prefix) ? value : `${prefix}${value}`;
-};
-
-const normalizeLocation = (location: unknown): I18nRouterLocation | null => {
-  if (!location || typeof location !== 'object') {
-    return null;
-  }
-
-  const locationValue = location as {
-    pathname?: unknown;
-    search?: unknown;
-    searchStr?: unknown;
-    hash?: unknown;
-  };
-
-  if (typeof locationValue.pathname !== 'string') {
-    return null;
-  }
-
-  return {
-    pathname: locationValue.pathname,
-    search: normalizeUrlPart(
-      typeof locationValue.search === 'string'
-        ? locationValue.search
-        : locationValue.searchStr,
-      '?',
-    ),
-    hash: normalizeUrlPart(locationValue.hash, '#'),
-  };
-};
-
-const getWindowLocation = (): I18nRouterLocation | null => {
-  if (!isBrowser()) {
-    return null;
-  }
-
-  return {
-    pathname: window.location.pathname,
-    search: window.location.search,
-    hash: window.location.hash,
+  /** Convert an already resolved target to the selected router's own props. */
+  createLinkProps?: (target: I18nRouterLinkTarget) => {
+    to: string;
+    [key: string]: unknown;
   };
-};
-
-const getRouterFramework = (
-  runtimeContext: RuntimeContextWithRouter,
-  internalContext: InternalRuntimeContextWithRouter,
-  inReactRouter: boolean,
-): I18nRouterFramework | undefined => {
-  const framework =
-    getRouterRuntimeState(internalContext)?.framework ||
-    getRouterRuntimeState(runtimeContext)?.framework;
-
-  if (framework) {
-    return framework;
-  }
-
-  if (internalContext.router?.useRouter || runtimeContext.router?.useRouter) {
-    return 'tanstack';
-  }
-
-  if (
-    internalContext.router?.useLocation ||
-    internalContext.router?.useHref ||
-    runtimeContext.router?.useLocation ||
-    runtimeContext.router?.useHref
-  ) {
-    return 'react-router';
-  }
-
-  if (inReactRouter) {
-    return 'react-router';
-  }
-
-  return undefined;
-};
-
-const getRouterInstance = (
-  internalContext: InternalRuntimeContextWithRouter,
-  contextRouter?: RouterInstance | null,
-): RouterInstance | null => {
-  if (contextRouter) {
-    return contextRouter;
-  }
-
-  const router = getRouterRuntimeState(internalContext)?.instance;
-  if (!router || typeof router !== 'object') {
-    return null;
-  }
-  return router as RouterInstance;
-};
-
-const getRouterStateLocation = (
-  internalContext: InternalRuntimeContextWithRouter,
-  contextRouter?: RouterInstance | null,
-): I18nRouterLocation | null => {
-  const router = getRouterInstance(internalContext, contextRouter);
-  return (
-    normalizeLocation(router?.stores?.location?.get?.()) ||
-    normalizeLocation(router?.state?.location)
-  );
-};
-
-const getRouterParams = (
-  internalContext: InternalRuntimeContextWithRouter,
-  contextRouter?: RouterInstance | null,
-): Record<string, string> => {
-  const router = getRouterInstance(internalContext, contextRouter);
-  const matches = router?.stores?.matches?.get?.() || router?.state?.matches;
-  if (!Array.isArray(matches)) {
-    return {};
-  }
-
-  return matches.reduce<Record<string, string>>((params, match) => {
-    if (match?.params) {
-      Object.assign(params, match.params);
-    }
-    return params;
-  }, {});
-};
+}
 
-const getRouterSnapshot = (
-  internalContext: InternalRuntimeContextWithRouter,
-  contextRouter?: RouterInstance | null,
-) => {
-  const location = getRouterStateLocation(internalContext, contextRouter);
-  const params = getRouterParams(internalContext, contextRouter);
-  return JSON.stringify([
-    location?.pathname ?? '',
-    location?.search ?? '',
-    location?.hash ?? '',
-    Object.entries(params).sort(([left], [right]) => left.localeCompare(right)),
-  ]);
-};
+export const I18nNavigationProvider = ({
+  children,
+  value,
+}: React.PropsWithChildren<{ value: I18nRouterAdapter }>) => (
+  <I18nNavigationContext.Provider value={value}>
+    {children}
+  </I18nNavigationContext.Provider>
+);
+
+interface NativeRouterApi {
+  useInRouterContext?: () => boolean;
+  useNavigate?: () => I18nRouterNavigate;
+  useLocation?: () => I18nRouterLocation;
+  useParams?: () => Record<string, string>;
+  Link?: I18nRouterLink;
+}
 
-export const useI18nRouterAdapter = (): I18nRouterAdapter => {
-  const runtimeContext = useContext(RuntimeContext) as RuntimeContextWithRouter;
-  const internalContext = useContext(
-    InternalRuntimeContext,
-  ) as InternalRuntimeContextWithRouter;
-  const routerApi = internalContext.router || runtimeContext.router;
-  const inReactRouter = routerApi?.useInRouterContext?.() ?? false;
-  const reactRouterNavigate = inReactRouter
-    ? (routerApi?.useNavigate?.() ?? null)
-    : null;
-  const reactRouterLocation = inReactRouter
+/** Read native router hooks only when their own provider is present. */
+export const useNativeI18nRouterAdapter = (): I18nRouterAdapter => {
+  const runtimeContext = useContext(RuntimeContext);
+  const internalContext = useContext(InternalRuntimeContext);
+  const routerApi = (internalContext.router || runtimeContext.router) as
+    | NativeRouterApi
+    | undefined;
+  const hasRouter = routerApi?.useInRouterContext?.() ?? false;
+  const navigate = hasRouter ? (routerApi?.useNavigate?.() ?? null) : null;
+  const routerLocation = hasRouter
     ? (routerApi?.useLocation?.() ?? null)
     : null;
-  const reactRouterParams = inReactRouter
-    ? (routerApi?.useParams?.() ?? {})
-    : {};
-  const framework = getRouterFramework(
-    runtimeContext,
-    internalContext,
-    inReactRouter,
-  );
-  const contextUseRouter =
-    !inReactRouter && framework === 'tanstack'
-      ? internalContext.router?.useRouter || runtimeContext.router?.useRouter
-      : undefined;
-  const contextRouter = contextUseRouter
-    ? (contextUseRouter({ warn: false }) as RouterInstance | null)
-    : null;
-  const hasRouter =
-    framework === 'tanstack' ||
-    framework === 'react-router' ||
-    Boolean(reactRouterNavigate);
-
-  const subscribeToRouter = useCallback(
-    (update: () => void) => {
-      const router = getRouterInstance(internalContext, contextRouter);
-      if (!router) {
-        return () => undefined;
-      }
-
-      const unsubscribers: Array<() => void> = [];
-
-      if (
-        framework === 'react-router' &&
-        !inReactRouter &&
-        typeof router.subscribe === 'function'
-      ) {
-        const subscribe = router.subscribe as (
-          this: RouterInstance,
-          listener: () => void,
-        ) => () => void;
-        const unsubscribe = subscribe.call(router, update);
-        if (typeof unsubscribe === 'function') {
-          unsubscribers.push(unsubscribe);
-        }
-      }
-
-      if (
-        framework === 'tanstack' &&
-        typeof router.stores?.location?.subscribe === 'function'
-      ) {
-        const unsubscribe = router.stores.location.subscribe(update);
-        if (typeof unsubscribe === 'function') {
-          unsubscribers.push(unsubscribe);
-        }
-      }
-
-      if (framework === 'tanstack' && typeof router.subscribe === 'function') {
-        const subscribe = router.subscribe as (
-          this: RouterInstance,
-          eventType: string,
-          listener: () => void,
-        ) => () => void;
-        for (const eventType of ['onBeforeNavigate', 'onBeforeLoad']) {
-          const unsubscribe = subscribe.call(router, eventType, update);
-          if (typeof unsubscribe === 'function') {
-            unsubscribers.push(unsubscribe);
-          }
-        }
-      }
-
-      return () => {
-        for (const unsubscribe of unsubscribers) {
-          unsubscribe();
-        }
-      };
-    },
-    [contextRouter, framework, inReactRouter, internalContext],
-  );
-  const getSnapshot = useCallback(
-    () => getRouterSnapshot(internalContext, contextRouter),
-    [contextRouter, internalContext],
-  );
-  useSyncExternalStore(subscribeToRouter, getSnapshot, getSnapshot);
-
-  const navigate = useCallback<I18nRouterNavigate>(
-    (href, options) => {
-      const router = getRouterInstance(internalContext, contextRouter);
-      const activeFramework = getRouterFramework(
-        runtimeContext,
-        internalContext,
-        inReactRouter,
-      );
-
-      if (activeFramework === 'tanstack') {
-        if (typeof router?.navigate === 'function') {
-          return router.navigate({
-            to: href,
-            replace: options?.replace,
-            ...(options?.state === undefined ? {} : { state: options.state }),
-          }) as void | Promise<void>;
-        }
-        throw new Error('TanStack router instance is not available.');
-      }
-
-      if (reactRouterNavigate) {
-        return reactRouterNavigate(href, options);
-      }
-
-      if (activeFramework === 'react-router') {
-        if (typeof router?.navigate === 'function') {
-          return router.navigate(href, options) as void | Promise<void>;
-        }
-        throw new Error('React Router instance is not available.');
-      }
-    },
-    [
-      contextRouter,
-      internalContext,
-      inReactRouter,
-      reactRouterNavigate,
-      runtimeContext,
-    ],
-  );
-
+  const params = hasRouter ? (routerApi?.useParams?.() ?? {}) : {};
   const location =
-    (reactRouterLocation
-      ? normalizeLocation(reactRouterLocation)
-      : getRouterStateLocation(internalContext, contextRouter)) ||
-    getWindowLocation();
-  const params = inReactRouter
-    ? (reactRouterParams as Record<string, string>)
-    : getRouterParams(internalContext, contextRouter);
-  const Link =
-    framework === 'tanstack'
-      ? internalContext.router?.Link || runtimeContext.router?.Link || null
-      : framework === 'react-router' || inReactRouter
-        ? (routerApi?.Link ?? null)
-        : null;
+    routerLocation ??
+    (isBrowser()
+      ? {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+        }
+      : null);
 
   return {
-    framework,
+    framework: hasRouter ? 'react-router' : undefined,
     hasRouter,
+    navigate,
     location,
-    navigate: hasRouter ? navigate : null,
-    Link,
     params,
+    Link: hasRouter ? (routerApi?.Link ?? null) : null,
   };
 };
+
+export const useI18nRouterAdapter = (): I18nRouterAdapter => {
+  const provided = useContext(I18nNavigationContext);
+  const native = useNativeI18nRouterAdapter();
+  return provided ?? native;
+};

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,10 +1,10 @@
-import {
-  type LocalisedUrlsOption,
-  localiseTargetPathname,
-  shouldSkipLocaleRedirect,
-} from '@modern-js/i18n-runtime-extensions';
 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';
+import { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
+
+export { splitUrlTarget } from '@modern-js/runtime-utils/url';
 
 // Structural parameter: hooks.ts passes a public-TRuntimeContext-based
 // context while core.tsx passes the internal one; both carry the request
@@ -47,24 +47,6 @@ export const getLanguageFromPath = (
   return fallbackLanguage;
 };
 
-/**
- * Split a link target into its pathname, search and hash parts without
- * relying on `new URL` (SSR-hot path; targets are relative).
- */
-export const splitUrlTarget = (
-  target: string,
-): { pathname: string; search: string; hash: string } => {
-  const hashIndex = target.indexOf('#');
-  const hash = hashIndex >= 0 ? target.slice(hashIndex) : '';
-  const beforeHash = hashIndex >= 0 ? target.slice(0, hashIndex) : target;
-  const searchIndex = beforeHash.indexOf('?');
-  const search = searchIndex >= 0 ? beforeHash.slice(searchIndex) : '';
-  const pathname =
-    searchIndex >= 0 ? beforeHash.slice(0, searchIndex) : beforeHash;
-
-  return { pathname, search, hash };
-};
-
 /**
  * Helper function to build localized URL
  * @param target - The language-agnostic target; may include `?search` and `#hash`
@@ -76,15 +58,23 @@ export const buildLocalizedUrl = (
   target: string,
   language: string,
   languages: string[],
-  localisedUrls?: LocalisedUrlsOption,
+  urlStrategy?: I18nUrlStrategy,
 ): string => {
   const { pathname, search, hash } = splitUrlTarget(target);
-  const localizedPathname = localiseTargetPathname(
-    pathname,
-    language,
-    languages,
-    localisedUrls,
-  );
+  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);
+  }
+  const localizedPathname = `/${segments.join('/')}`;
 
   return `${localizedPathname}${search}${hash}`;
 };
@@ -131,6 +121,34 @@ export const shouldIgnoreRedirect = (
   pathname: string,
   languages: string[],
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
+  urlStrategy?: I18nUrlStrategy,
 ): boolean => {
-  return shouldSkipLocaleRedirect(pathname, languages, ignoreRedirectRoutes);
+  // 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) {
+    return false;
+  }
+  const segments = pathname.split('/').filter(Boolean);
+  if (
+    segments[0] &&
+    languages.some(item => item.toLowerCase() === segments[0].toLowerCase())
+  ) {
+    segments.shift();
+  }
+  const normalizedPath = `/${segments.join('/')}`;
+  return typeof ignoreRedirectRoutes === 'function'
+    ? ignoreRedirectRoutes(normalizedPath)
+    : ignoreRedirectRoutes.some(
+        pattern =>
+          normalizedPath === pattern ||
+          normalizedPath.startsWith(`${pattern}/`),
+      );
 };

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

@@ -1,12 +1,13 @@
-import { resolveLocalisedUrlsConfig } from '@modern-js/i18n-runtime-extensions';
 import * as honoPkg from '@modern-js/server-core/hono';
 
 const { languageDetector } = honoPkg;
 
 import type { Context, Next, ServerPlugin } from '@modern-js/server-runtime';
 import type { LocaleDetectionOptions } from '../shared/type';
+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,
@@ -21,6 +22,7 @@ export { collectApiPrefixes, matchesApiPrefix } from './apiPrefix.js';
 export interface I18nPluginOptions {
   localeDetection: LocaleDetectionOptions;
   staticRoutePrefixes: string[];
+  resolveUrlStrategy?: (entryName: string) => I18nUrlStrategy | undefined;
 }
 
 export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
@@ -53,6 +55,10 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
         if (!options.localeDetection) {
           return;
         }
+        const entryLocaleDetection = getLocaleDetectionOptions(
+          entryName,
+          options.localeDetection,
+        );
         const {
           localePathRedirect,
           i18nextDetector = true,
@@ -60,8 +66,16 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
           fallbackLanguage = 'en',
           detection,
           ignoreRedirectRoutes,
-          localisedUrls,
-        } = getLocaleDetectionOptions(entryName, options.localeDetection);
+        } = entryLocaleDetection;
+        const legacyLocalisedUrls = Reflect.get(
+          entryLocaleDetection,
+          'localisedUrls',
+        );
+        // `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('/')
@@ -87,6 +101,18 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
                   return await next();
                 }
 
+                if (
+                  shouldIgnoreRedirect(
+                    pathname,
+                    urlPath,
+                    ignoreRedirectRoutes,
+                    urlStrategy,
+                    languages,
+                  )
+                ) {
+                  return await next();
+                }
+
                 // For static resource requests, skip language detection
                 if (
                   isStaticResourceRequest(
@@ -138,7 +164,13 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
 
               // Check if this route should ignore automatic redirect
               if (
-                shouldIgnoreRedirect(pathname, urlPath, ignoreRedirectRoutes)
+                shouldIgnoreRedirect(
+                  pathname,
+                  urlPath,
+                  ignoreRedirectRoutes,
+                  urlStrategy,
+                  languages,
+                )
               ) {
                 return await next();
               }
@@ -168,19 +200,17 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
                   originUrlPath,
                   targetLanguage,
                   languages,
-                  localisedUrls,
+                  urlStrategy,
                 );
                 return createLocaleRedirectResponse(localizedUrl);
               }
-              const localisedUrlsConfig =
-                resolveLocalisedUrlsConfig(localisedUrls);
-              if (localisedUrlsConfig.enabled) {
+              if (urlStrategy) {
                 const expectedUrl = buildLocalizedUrl(
                   c.req,
                   originUrlPath,
                   language,
                   languages,
-                  localisedUrls,
+                  urlStrategy,
                 );
                 if (expectedUrl !== `${pathname}${url.search}${url.hash}`) {
                   return createLocaleRedirectResponse(expectedUrl);