@bleedingdev/modern-js-plugin-i18n 3.8.3-ultramodern.6 → 3.9.0-ultramodern.10

package/src/runtime/Link.tsx

@@ -104,11 +104,11 @@ export const Link = <TTo extends string = string>(
   } = props as LinkBaseProps & { to: string; params?: LinkParams };
 
   const adapter = useI18nRouterAdapter();
-  const { language, supportedLanguages, localisedUrls } = useModernI18n();
+  const { language, supportedLanguages, urlStrategy } = useModernI18n();
 
   const config: LocalizedPathsConfig = {
     languages: supportedLanguages,
-    localisedUrls,
+    urlStrategy,
   };
 
   const isExternal = EXTERNAL_TARGET_RE.test(to);
@@ -139,7 +139,7 @@ export const Link = <TTo extends string = string>(
       interpolated,
       language,
       supportedLanguages,
-      localisedUrls,
+      urlStrategy,
     );
     const hash = hashProp ?? (hashFromTo ? hashFromTo.slice(1) : '');
     const { searchString, searchObject } = normalizeSearch(
@@ -164,7 +164,7 @@ export const Link = <TTo extends string = string>(
     isBareHash,
     language,
     supportedLanguages,
-    localisedUrls,
+    urlStrategy,
   ]);
 
   const isActive = useMemo(() => {
@@ -190,7 +190,7 @@ export const Link = <TTo extends string = string>(
     adapter.location,
     activeOptions?.exact,
     supportedLanguages,
-    localisedUrls,
+    urlStrategy,
   ]);
 
   const resolvedActiveProps = splitActiveProps(isActive, activeProps);
@@ -214,7 +214,7 @@ export const Link = <TTo extends string = string>(
     );
   }
 
-  const { Link: RouterLink, hasRouter, framework } = adapter;
+  const { Link: RouterLink, hasRouter } = adapter;
 
   if (!hasRouter || !RouterLink) {
     const { replace: _replace, ...anchorProps } = rest;
@@ -252,43 +252,23 @@ export const Link = <TTo extends string = string>(
     ...(activeStyle as React.CSSProperties | undefined),
   };
 
-  if (framework === 'tanstack') {
-    // TanStack's prop is `preload`; map our react-router-flavored `prefetch`
-    // onto it (`'none'` -> `false`). An explicit native `preload` wins.
-    const tanstackPreload =
-      preload !== undefined
-        ? preload
-        : prefetch === undefined
-          ? undefined
-          : prefetch === 'none'
-            ? false
-            : prefetch;
-
-    // Pass hash/search natively: string-concatenated targets silently break
-    // TanStack navigation.
-    return (
-      <RouterLink
-        to={target.localizedPathname}
-        {...(target.searchObject ? { search: target.searchObject } : {})}
-        {...(target.hash ? { hash: target.hash } : {})}
-        {...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView })}
-        {...(tanstackPreload === undefined ? {} : { preload: tanstackPreload })}
-        {...rest}
-        {...activeRest}
-        {...activeAttributes}
-        className={mergedClassName}
-        style={mergedStyle}
-      >
-        {children}
-      </RouterLink>
-    );
-  }
+  const routerProps = adapter.createLinkProps?.({
+    pathname: target.localizedPathname,
+    href: target.href,
+    search: target.searchObject,
+    hash: target.hash,
+    hashScrollIntoView,
+    prefetch,
+    preload,
+  }) ?? {
+    to: target.href,
+    ...(prefetch === undefined ? {} : { prefetch }),
+    ...(preload === undefined ? {} : { preload }),
+  };
 
   return (
     <RouterLink
-      to={target.href}
-      {...(prefetch === undefined ? {} : { prefetch })}
-      {...(preload === undefined ? {} : { preload })}
+      {...routerProps}
       {...rest}
       {...activeRest}
       {...activeAttributes}

package/src/runtime/context.tsx

@@ -1,4 +1,4 @@
-import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
+import { RuntimeComponentResolverContext } from '@modern-js/runtime/context';
 import type { ComponentType, FC, ReactNode } from 'react';
 import {
   createContext,
@@ -7,6 +7,7 @@ import {
   useEffect,
   useMemo,
 } from 'react';
+import type { I18nUrlStrategy } from '../shared/urlStrategy';
 import {
   changeModernI18nLanguage,
   getPathLanguage,
@@ -16,10 +17,12 @@ import {
 } from './contextHelpers';
 import type { I18nInstance } from './i18n';
 import type { Resources } from './i18n/instance';
-import { getActualI18nextInstance } from './i18n/instance';
+
 import { useI18nRouterAdapter } from './routerAdapter';
 
-interface ModernI18nContextValue {
+export { getActualI18nextInstance } from './i18n/instance';
+
+export interface ModernI18nContextValue {
   language: string;
   i18nInstance: I18nInstance;
   // Plugin configuration for useModernI18n hook
@@ -27,7 +30,7 @@ interface ModernI18nContextValue {
   languages?: string[];
   localePathRedirect?: boolean;
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
-  localisedUrls?: LocalisedUrlsOption;
+  urlStrategy?: I18nUrlStrategy;
   // Callback to update language in context
   updateLanguage?: (newLang: string) => void;
   synchronizeLanguage?: (newLang: string) => void;
@@ -50,16 +53,15 @@ const getGlobalContext = <T,>(key: symbol, defaultValue: T) => {
   return globalStore[key];
 };
 
-const ModernI18nContext = getGlobalContext<ModernI18nContextValue | null>(
-  modernI18nContextKey,
-  null,
-);
-const ReactI18nextProviderContext = getGlobalContext<ComponentType<any> | null>(
-  reactI18nextProviderContextKey,
-  null,
-);
+export const ModernI18nContext =
+  getGlobalContext<ModernI18nContextValue | null>(modernI18nContextKey, null);
+export const ReactI18nextProviderContext =
+  getGlobalContext<ComponentType<any> | null>(
+    reactI18nextProviderContextKey,
+    null,
+  );
 
-interface ModernI18nProviderProps {
+export interface ModernI18nProviderProps {
   children: ReactNode;
   i18nextProvider?: ComponentType<any> | null;
   value: ModernI18nContextValue;
@@ -92,123 +94,22 @@ export interface FederatedI18nBoundaryProps {
   supportedLanguages?: string[];
 }
 
-/**
- * Keeps a federated surface's translation resources inside its delivery unit.
- * The host supplies only the active language; the remote owns and versions the
- * resources used below this boundary.
- */
-export const FederatedI18nBoundary: FC<FederatedI18nBoundaryProps> = ({
-  children,
-  defaultNamespace,
-  fallbackLanguage,
-  resources,
-  supportedLanguages,
-}) => {
-  const parent = useContext(ModernI18nContext);
-  const I18nextProvider = useContext(ReactI18nextProviderContext);
-  if (!parent) {
-    throw new Error(
-      'FederatedI18nBoundary must be used within ModernI18nProvider',
-    );
-  }
-
-  const languages =
-    supportedLanguages ?? parent.languages ?? Object.keys(resources);
-  const scopedInstance = useMemo(() => {
-    const parentInstance = getActualI18nextInstance(parent.i18nInstance);
-    const clone = parentInstance.cloneInstance?.({
-      defaultNS: defaultNamespace,
-      fallbackLng: fallbackLanguage ?? languages[0] ?? parent.language,
-      forkResourceStore: true,
-      initImmediate: false,
-      lng: parent.language,
-      ns: [defaultNamespace],
-      resources,
-      supportedLngs: languages,
-    });
-    if (!clone) {
-      throw new Error(
-        'FederatedI18nBoundary requires an i18n instance with cloneInstance support',
-      );
-    }
-    const resourceStore = clone.store;
-    const parentResourceStore = parentInstance.store;
-    const sharesNestedResourceState = Object.entries(
-      resourceStore?.data ?? {},
-    ).some(([language, namespaces]) => {
-      const parentNamespaces = parentResourceStore?.data?.[language];
-      return (
-        namespaces === parentNamespaces ||
-        Object.entries(namespaces).some(
-          ([namespace, resource]) =>
-            resource !== null &&
-            typeof resource === 'object' &&
-            resource === parentNamespaces?.[namespace],
-        )
-      );
-    });
-    if (
-      clone === parentInstance ||
-      resourceStore === parentResourceStore ||
-      resourceStore?.data === parentResourceStore?.data ||
-      sharesNestedResourceState
-    ) {
-      throw new Error(
-        'FederatedI18nBoundary cloneInstance did not isolate the host resource store',
-      );
-    }
-    if (
-      !resourceStore?.addResourceBundle ||
-      !clone.removeResourceBundle ||
-      !resourceStore.data
-    ) {
-      throw new Error(
-        'FederatedI18nBoundary requires an isolated mutable i18n resource store',
-      );
-    }
-    for (const [language, namespaces] of Object.entries(resourceStore.data)) {
-      for (const namespace of Object.keys(namespaces)) {
-        clone.removeResourceBundle(language, namespace);
-      }
-    }
-    for (const [language, namespaces] of Object.entries(resources)) {
-      for (const [namespace, resource] of Object.entries(namespaces)) {
-        resourceStore.addResourceBundle(
-          language,
-          namespace,
-          resource as Record<string, string>,
-          true,
-          true,
-        );
-      }
-    }
-    return clone;
-  }, [
-    defaultNamespace,
-    fallbackLanguage,
-    languages,
-    parent.i18nInstance,
-    parent.language,
-    resources,
-  ]);
-  const value = useMemo(
-    () => ({
-      ...parent,
-      i18nInstance: scopedInstance,
-      language: parent.language,
-      languages,
-    }),
-    [languages, parent, scopedInstance],
+const MissingFederatedI18nBoundary: FC<FederatedI18nBoundaryProps> = () => {
+  throw new Error(
+    'FederatedI18nBoundary requires the @modern-js/i18n-integration runtime plugin',
   );
+};
 
-  const scopedContent = (
-    <ModernI18nProvider value={value}>{children}</ModernI18nProvider>
-  );
-  return I18nextProvider ? (
-    <I18nextProvider i18n={scopedInstance}>{scopedContent}</I18nextProvider>
-  ) : (
-    scopedContent
-  );
+export const FederatedI18nBoundary: FC<FederatedI18nBoundaryProps> = props => {
+  const resolveComponent = useContext(RuntimeComponentResolverContext);
+  const Boundary =
+    resolveComponent?.(MissingFederatedI18nBoundary, {
+      name: 'i18n.FederatedI18nBoundary',
+    }) ?? MissingFederatedI18nBoundary;
+  if (Boundary === FederatedI18nBoundary) {
+    throw new Error('FederatedI18nBoundary resolver returned its own wrapper');
+  }
+  return <Boundary {...props} />;
 };
 
 export interface UseModernI18nReturn<
@@ -219,7 +120,7 @@ export interface UseModernI18nReturn<
   t: (key: string | string[], ...args: any[]) => string;
   i18nInstance: TInstance;
   supportedLanguages: string[];
-  localisedUrls?: LocalisedUrlsOption;
+  urlStrategy?: I18nUrlStrategy;
   isLanguageSupported: (lang: string) => boolean;
   // Indicates whether translation resources for current language are ready
   isResourcesReady: boolean;
@@ -258,7 +159,7 @@ export const useModernI18n = <
     languages,
     localePathRedirect,
     ignoreRedirectRoutes,
-    localisedUrls,
+    urlStrategy,
     updateLanguage,
     synchronizeLanguage,
   } = context;
@@ -295,7 +196,7 @@ export const useModernI18n = <
         updateLanguage,
         localePathRedirect,
         ignoreRedirectRoutes,
-        localisedUrls,
+        urlStrategy,
         languages,
         hasRouter,
         navigate,
@@ -306,7 +207,7 @@ export const useModernI18n = <
       updateLanguage,
       localePathRedirect,
       ignoreRedirectRoutes,
-      localisedUrls,
+      urlStrategy,
       languages,
       hasRouter,
       navigate,
@@ -341,7 +242,7 @@ export const useModernI18n = <
     // narrows to the concrete instance type via the TInstance type argument.
     i18nInstance: i18nInstance as TInstance,
     supportedLanguages: languages || [],
-    localisedUrls,
+    urlStrategy,
     isLanguageSupported,
     isResourcesReady,
   };

package/src/runtime/contextHelpers.ts

@@ -1,5 +1,5 @@
-import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
 import { isBrowser } from '@modern-js/runtime';
+import type { I18nUrlStrategy } from '../shared/urlStrategy';
 import type { I18nInstance } from './i18n';
 import type { SdkBackend } from './i18n/backend/sdk-backend';
 import { cacheUserLanguage } from './i18n/detection';
@@ -66,7 +66,7 @@ interface ChangeModernI18nLanguageOptions {
   updateLanguage?: (newLang: string) => void;
   localePathRedirect?: boolean;
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
-  localisedUrls?: LocalisedUrlsOption;
+  urlStrategy?: I18nUrlStrategy;
   languages?: string[];
   hasRouter: boolean;
   navigate?: Navigate | null;
@@ -82,7 +82,7 @@ export async function changeModernI18nLanguage(
     updateLanguage,
     localePathRedirect,
     ignoreRedirectRoutes,
-    localisedUrls,
+    urlStrategy,
     languages,
     hasRouter,
     navigate,
@@ -123,13 +123,14 @@ export async function changeModernI18nLanguage(
           relativePath,
           languages || [],
           ignoreRedirectRoutes,
+          urlStrategy,
         )
       ) {
         const newPath = buildLocalizedUrl(
           relativePath,
           newLang,
           languages || [],
-          localisedUrls,
+          urlStrategy,
         );
         const newUrl = entryPath + newPath + location.search + location.hash;
 
@@ -155,13 +156,14 @@ export async function changeModernI18nLanguage(
           relativePath,
           languages || [],
           ignoreRedirectRoutes,
+          urlStrategy,
         )
       ) {
         const newPath = buildLocalizedUrl(
           relativePath,
           newLang,
           languages || [],
-          localisedUrls,
+          urlStrategy,
         );
         const newUrl =
           entryPath + newPath + window.location.search + window.location.hash;

package/src/runtime/core.tsx

@@ -1,15 +1,24 @@
 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 { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
 import type { I18nInitOptions, I18nInstance } from './i18n';
+import { I18nRouterNavigationProvider } from './navigation';
 import {
   type RuntimeContextWithI18n,
   setupI18nBeforeRender,
 } from './pluginSetup';
-import { createI18nRootWrapper } from './providerComposition';
+import {
+  createI18nRootWrapper,
+  type I18nLanguageSynchronizationProps,
+} from './providerComposition';
+
+export type { I18nLanguageSynchronizationProps } from './providerComposition';
+
 import {
   type LoadReactI18nextIntegration,
   resolveReactI18nextIntegration,
@@ -17,16 +26,28 @@ import {
 import './types';
 
 export type { I18nSdkLoader, I18nSdkLoadOptions } from '../shared/type';
+export type { I18nUrlStrategy } from '../shared/urlStrategy';
 export type {
   I18nInitOptions,
   I18nInstance,
   Resources,
   TranslateFn,
 } from './i18n/instance';
+export {
+  I18nRouterNavigationProvider,
+  useIntegratedRouterAdapter,
+} from './navigation';
 export type {
   LoadReactI18nextIntegration,
   ReactI18nextIntegration,
 } from './reactI18next';
+export {
+  I18nNavigationProvider,
+  type I18nRouterAdapter,
+  type I18nRouterLinkTarget,
+  useI18nRouterAdapter,
+  useNativeI18nRouterAdapter,
+} from './routerAdapter';
 
 export interface I18nPluginOptions {
   entryName?: string;
@@ -37,6 +58,9 @@ export interface I18nPluginOptions {
   initOptions?: I18nInitOptions;
   htmlLangAttr?: boolean;
   reactI18next?: boolean;
+  urlStrategy?: I18nUrlStrategy;
+  NavigationProvider?: React.ComponentType<React.PropsWithChildren>;
+  LanguageSynchronization?: React.ComponentType<I18nLanguageSynchronizationProps>;
   [key: string]: any;
 }
 
@@ -55,6 +79,9 @@ export const createI18nPlugin =
         backend,
         htmlLangAttr = false,
         reactI18next = true,
+        urlStrategy,
+        NavigationProvider,
+        LanguageSynchronization,
       } = options;
       const {
         localePathRedirect = false,
@@ -63,9 +90,23 @@ export const createI18nPlugin =
         fallbackLanguage = 'en',
         detection,
         ignoreRedirectRoutes,
-        localisedUrls,
       } = 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;
 
@@ -100,7 +141,15 @@ export const createI18nPlugin =
           languages,
           fallbackLanguage,
           ignoreRedirectRoutes,
-          localisedUrls,
+          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,
         }),
@@ -128,12 +177,10 @@ export {
   type LinkProps,
 } from './Link';
 export {
-  canonicalPath,
   type LocalizedPathsConfig,
-  localizePath,
   type UseLocalizedLocationReturn,
   type UseLocalizedPathsReturn,
   useLocalizedLocation,
   useLocalizedPaths,
 } from './localizedPaths';
-export { buildLocalizedUrl, splitUrlTarget } from './utils';
+export { splitUrlTarget } from './utils';

package/src/runtime/hooks.ts

@@ -1,7 +1,7 @@
-import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions';
 import { isBrowser } from '@modern-js/runtime';
 import type React from 'react';
 import { useCallback, useEffect, useRef } from 'react';
+import type { I18nUrlStrategy } from '../shared/urlStrategy';
 import {
   cacheI18nLanguage,
   changeI18nInstanceLanguage,
@@ -54,9 +54,8 @@ export function createContextValue(
   languages: string[],
   localePathRedirect: boolean,
   ignoreRedirectRoutes: string[] | ((pathname: string) => boolean) | undefined,
-  localisedUrls: LocalisedUrlsOption | undefined,
   setLang: (lang: string) => void,
-  synchronizeLanguage: (lang: string) => void,
+  urlStrategy?: I18nUrlStrategy,
 ) {
   const instance = i18nInstance || createMinimalI18nInstance(lang);
   return {
@@ -66,9 +65,8 @@ export function createContextValue(
     languages,
     localePathRedirect,
     ignoreRedirectRoutes,
-    localisedUrls,
+    urlStrategy,
     updateLanguage: setLang,
-    synchronizeLanguage,
   };
 }
 
@@ -179,7 +177,7 @@ export function useClientSideRedirect(
   languages: string[],
   fallbackLanguage: string,
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
-  localisedUrls?: LocalisedUrlsOption,
+  urlStrategy?: I18nUrlStrategy,
 ) {
   const urlRef = useRef('');
   const { navigate, location, hasRouter } = useI18nRouterAdapter();
@@ -220,7 +218,14 @@ export function useClientSideRedirect(
     const entryPath = getEntryPath();
     const relativePath = currentPathname.replace(entryPath, '');
 
-    if (shouldIgnoreRedirect(relativePath, languages, ignoreRedirectRoutes)) {
+    if (
+      shouldIgnoreRedirect(
+        relativePath,
+        languages,
+        ignoreRedirectRoutes,
+        urlStrategy,
+      )
+    ) {
       return;
     }
 
@@ -241,7 +246,7 @@ export function useClientSideRedirect(
       relativePath,
       targetLanguage,
       languages,
-      localisedUrls,
+      urlStrategy,
     );
     const newUrl = entryPath + newPath + currentSearch + currentHash;
 
@@ -265,7 +270,7 @@ export function useClientSideRedirect(
     languages,
     fallbackLanguage,
     ignoreRedirectRoutes,
-    localisedUrls,
+    urlStrategy,
   ]);
 }
 

package/src/runtime/i18n/instance.ts

@@ -74,8 +74,7 @@ export type TranslateFn = (
 // declares a top-level `[key: string]: any` and overloaded call-signature
 // properties; both make i18next's `i18n` structurally unassignable to this
 // type, so the documented `i18nInstance: i18next` usage does not typecheck.
-// Do NOT restore upstream's shape when resolving a sync merge — the guard is
-// tests/type-fixture/i18nInstanceTypes.fixture.ts.
+// Do NOT restore upstream's shape when resolving a sync merge.
 export interface I18nInstance {
   language: string;
   isInitialized?: boolean;