@bleedingdev/modern-js-plugin-i18n 3.5.0-ultramodern.6 → 3.5.0-ultramodern.75

package/src/runtime/core.tsx

@@ -1,64 +1,27 @@
-import {
-  isBrowser,
-  RuntimeContext,
-  type RuntimePlugin,
-} from '@modern-js/runtime';
-import { Helmet } from '@modern-js/runtime/head';
-import type { TInternalRuntimeContext } from '@modern-js/runtime/internal';
-import { merge } from '@modern-js/runtime-utils/merge';
+import type { RuntimePlugin } from '@modern-js/runtime';
 import type React from 'react';
-import { useContext, useEffect, useMemo, useRef, useState } from 'react';
 import type {
   BaseBackendOptions,
   BaseLocaleDetectionOptions,
 } from '../shared/type';
-import { ModernI18nProvider } from './context';
-import {
-  createContextValue,
-  useClientSideRedirect,
-  useLanguageSync,
-  useSdkResourcesLoader,
-} from './hooks';
 import type { I18nInitOptions, I18nInstance } from './i18n';
-import { getI18nInstance } from './i18n';
-import { mergeBackendOptions } from './i18n/backend';
 import {
-  detectLanguageWithPriority,
-  exportServerLngToWindow,
-  mergeDetectionOptions,
-} from './i18n/detection';
-import { useI18nextLanguageDetector } from './i18n/detection/middleware';
-import { getI18nextInstanceForProvider } from './i18n/instance';
-import { getPathname } from './utils';
+  type RuntimeContextWithI18n,
+  setupI18nBeforeRender,
+} from './pluginSetup';
+import { createI18nRootWrapper } from './providerComposition';
+import {
+  type LoadReactI18nextIntegration,
+  resolveReactI18nextIntegration,
+} from './reactI18next';
 import './types';
 
 export type { I18nSdkLoader, I18nSdkLoadOptions } from '../shared/type';
 export type { Resources } from './i18n/instance';
-
-type I18nLifecycleHelpers = {
-  useI18nextBackend: typeof import('./i18n/backend/middleware')['useI18nextBackend'];
-  changeI18nLanguage: typeof import('./i18n/utils')['changeI18nLanguage'];
-  ensureLanguageMatch: typeof import('./i18n/utils')['ensureLanguageMatch'];
-  initializeI18nInstance: typeof import('./i18n/utils')['initializeI18nInstance'];
-  setupClonedInstance: typeof import('./i18n/utils')['setupClonedInstance'];
-};
-
-let i18nLifecycleHelpersPromise: Promise<I18nLifecycleHelpers> | undefined;
-
-function loadI18nLifecycleHelpers(): Promise<I18nLifecycleHelpers> {
-  i18nLifecycleHelpersPromise ??= Promise.all([
-    import('./i18n/backend/middleware'),
-    import('./i18n/utils'),
-  ]).then(([backendMiddleware, utils]) => ({
-    useI18nextBackend: backendMiddleware.useI18nextBackend,
-    changeI18nLanguage: utils.changeI18nLanguage,
-    ensureLanguageMatch: utils.ensureLanguageMatch,
-    initializeI18nInstance: utils.initializeI18nInstance,
-    setupClonedInstance: utils.setupClonedInstance,
-  }));
-
-  return i18nLifecycleHelpersPromise;
-}
+export type {
+  LoadReactI18nextIntegration,
+  ReactI18nextIntegration,
+} from './reactI18next';
 
 export interface I18nPluginOptions {
   entryName?: string;
@@ -72,19 +35,6 @@ export interface I18nPluginOptions {
   [key: string]: any;
 }
 
-interface RuntimeContextWithI18n extends TInternalRuntimeContext {
-  i18nInstance?: I18nInstance;
-  changeLanguage?: (lang: string) => Promise<void>;
-}
-
-export interface ReactI18nextIntegration {
-  I18nextProvider: React.ComponentType<any> | null;
-  initReactI18next: any | null;
-}
-
-export type LoadReactI18nextIntegration =
-  () => Promise<ReactI18nextIntegration | null>;
-
 export const createI18nPlugin =
   (
     loadReactI18nextIntegration?: LoadReactI18nextIntegration,
@@ -114,223 +64,42 @@ export const createI18nPlugin =
       let latestI18nInstance: I18nInstance | undefined;
       let I18nextProvider: React.ComponentType<any> | null;
 
-      const resolveReactI18nextIntegration = async () => {
-        if (!reactI18next) {
-          return null;
-        }
-        return loadReactI18nextIntegration?.() ?? null;
-      };
-
-      api.onBeforeRender(async context => {
-        const {
-          useI18nextBackend,
-          changeI18nLanguage,
-          ensureLanguageMatch,
-          initializeI18nInstance,
-          setupClonedInstance,
-        } = await loadI18nLifecycleHelpers();
-        let i18nInstance = await getI18nInstance(userI18nInstance);
-        const { i18n: otherConfig } = api.getRuntimeConfig();
-        const { initOptions: otherInitOptions } = otherConfig || {};
-        const userInitOptions = merge(
-          otherInitOptions || {},
-          initOptions || {},
-        );
-        const reactI18nextIntegration = await resolveReactI18nextIntegration();
-        I18nextProvider = reactI18nextIntegration?.I18nextProvider ?? null;
-        if (reactI18nextIntegration?.initReactI18next) {
-          i18nInstance.use(reactI18nextIntegration.initReactI18next);
-        }
-
-        const pathname = getPathname(context);
-
-        if (i18nextDetector) {
-          useI18nextLanguageDetector(i18nInstance);
-        }
-
-        const mergedDetection = mergeDetectionOptions(
+      api.onBeforeRender(async (context: RuntimeContextWithI18n) => {
+        latestI18nInstance = await setupI18nBeforeRender(context, {
+          api,
+          userI18nInstance,
+          initOptions,
+          backend,
+          backendEnabled,
           i18nextDetector,
           detection,
           localePathRedirect,
-          userInitOptions,
-        );
-        const mergedBackend = mergeBackendOptions(backend, userInitOptions);
-
-        // Register Backend BEFORE detectLanguageWithPriority
-        // This is critical because detectLanguageWithPriority may trigger init()
-        // through i18next detector, and backend must be registered before init()
-        // Register backend if:
-        // 1. enabled is true (explicitly or auto-detected), OR
-        // 2. SDK is configured (allows standalone SDK usage even without locales directory)
-        const hasSdkConfig =
-          typeof userInitOptions?.backend?.sdk === 'function' ||
-          (mergedBackend?.sdk && typeof mergedBackend.sdk === 'function');
-        if (mergedBackend && (backendEnabled || hasSdkConfig)) {
-          useI18nextBackend(i18nInstance, mergedBackend);
-        }
-
-        const { finalLanguage } = await detectLanguageWithPriority(
-          i18nInstance,
-          {
-            languages,
-            fallbackLanguage,
-            localePathRedirect,
-            i18nextDetector,
-            detection,
-            userInitOptions,
-            mergedBackend,
-            pathname,
-            ssrContext: context.ssrContext,
-          },
-        );
-
-        await initializeI18nInstance(
-          i18nInstance,
-          finalLanguage,
-          fallbackLanguage,
           languages,
-          mergedDetection,
-          mergedBackend,
-          userInitOptions,
-        );
-
-        if (!isBrowser() && i18nInstance.cloneInstance) {
-          i18nInstance = i18nInstance.cloneInstance();
-          await setupClonedInstance(
-            i18nInstance,
-            finalLanguage,
-            fallbackLanguage,
-            languages,
-            backendEnabled,
-            backend,
-            i18nextDetector,
-            detection,
-            localePathRedirect,
-            userInitOptions,
-          );
-        }
-
-        if (localePathRedirect) {
-          await ensureLanguageMatch(i18nInstance, finalLanguage);
-        }
-
-        if (!isBrowser()) {
-          exportServerLngToWindow(context, finalLanguage);
-        }
-        context.i18nInstance = i18nInstance;
-        latestI18nInstance = i18nInstance;
-
-        // Add changeLanguage method to context for other runtime plugins to use
-        context.changeLanguage = async (newLang: string) => {
-          await changeI18nLanguage(i18nInstance, newLang, {
-            detectionOptions: mergedDetection,
-          });
-        };
+          fallbackLanguage,
+          resolveReactI18nextIntegration: () =>
+            resolveReactI18nextIntegration(
+              reactI18next,
+              loadReactI18nextIntegration,
+            ),
+          setI18nextProvider: provider => {
+            I18nextProvider = provider;
+          },
+        });
       });
 
-      api.wrapRoot(App => {
-        return props => {
-          const runtimeContext = useContext(
-            RuntimeContext,
-          ) as RuntimeContextWithI18n;
-          const i18nInstance =
-            runtimeContext.i18nInstance || latestI18nInstance;
-          const initialLang = useMemo(
-            () =>
-              i18nInstance?.language ||
-              (localeDetection?.fallbackLanguage ?? 'en'),
-            [i18nInstance?.language, localeDetection?.fallbackLanguage],
-          );
-          const [lang, setLang] = useState(initialLang);
-          const [forceUpdate, setForceUpdate] = useState(0);
-          const prevLangRef = useRef(lang);
-          const runtimeContextRef = useRef(runtimeContext);
-          runtimeContextRef.current = runtimeContext;
-
-          useEffect(() => {
-            if (i18nInstance?.language) {
-              const translator = (i18nInstance as any).translator;
-              if (translator) {
-                translator.language = i18nInstance.language;
-              }
-            }
-          }, [i18nInstance?.language]);
-
-          useEffect(() => {
-            prevLangRef.current = lang;
-          }, [lang]);
-
-          useSdkResourcesLoader(i18nInstance, setForceUpdate);
-          useLanguageSync(
-            i18nInstance,
-            localePathRedirect,
-            languages,
-            runtimeContextRef,
-            prevLangRef,
-            setLang,
-          );
-          // Handle client-side redirect for static deployments
-          // Note: This hook only executes in browser environment and skips SSR scenarios
-          useClientSideRedirect(
-            i18nInstance,
-            localePathRedirect,
-            languages,
-            fallbackLanguage,
-            ignoreRedirectRoutes,
-            localisedUrls,
-          );
-
-          const contextValue = useMemo(
-            () =>
-              createContextValue(
-                lang,
-                i18nInstance,
-                entryName,
-                languages,
-                localePathRedirect,
-                ignoreRedirectRoutes,
-                localisedUrls,
-                setLang,
-              ),
-            [
-              lang,
-              i18nInstance,
-              entryName,
-              languages,
-              localePathRedirect,
-              ignoreRedirectRoutes,
-              localisedUrls,
-              forceUpdate,
-            ],
-          );
-
-          const children = (props as React.PropsWithChildren).children;
-          const appContent = (
-            <>
-              {Boolean(htmlLangAttr) && <Helmet htmlAttributes={{ lang }} />}
-              <ModernI18nProvider value={contextValue}>
-                {App ? <App {...props}>{children}</App> : children}
-              </ModernI18nProvider>
-            </>
-          );
-
-          if (!i18nInstance) {
-            return appContent;
-          }
-
-          if (I18nextProvider) {
-            const i18nextInstanceForProvider =
-              getI18nextInstanceForProvider(i18nInstance);
-            return (
-              <I18nextProvider i18n={i18nextInstanceForProvider}>
-                {appContent}
-              </I18nextProvider>
-            );
-          }
-
-          return appContent;
-        };
-      });
+      api.wrapRoot(
+        createI18nRootWrapper({
+          entryName,
+          htmlLangAttr,
+          localePathRedirect,
+          languages,
+          fallbackLanguage,
+          ignoreRedirectRoutes,
+          localisedUrls,
+          getLatestI18nInstance: () => latestI18nInstance,
+          getI18nextProvider: () => I18nextProvider,
+        }),
+      );
     },
   });
 
@@ -339,7 +108,11 @@ export type {
   CanonicalRoutePath,
   UltramodernCanonicalRoutes,
 } from './canonicalRoutes';
-export { useModernI18n } from './context';
+export {
+  FederatedI18nBoundary,
+  type FederatedI18nBoundaryProps,
+  useModernI18n,
+} from './context';
 export { I18nLink, type I18nLinkProps } from './I18nLink';
 export {
   Link,

package/src/runtime/hooks.ts

@@ -1,27 +1,32 @@
-import type { TRuntimeContext } from '@modern-js/runtime';
 import { isBrowser } from '@modern-js/runtime';
 import type React from 'react';
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import {
+  cacheI18nLanguage,
+  changeI18nInstanceLanguage,
+} from './contextHelpers';
 import type { I18nInstance } from './i18n';
 import {
   getI18nSdkBackendId,
   I18N_SDK_RESOURCES_LOADED_EVENT,
   type I18nSdkResourcesLoadedEventDetail,
 } from './i18n/backend/sdk-event';
-import { cacheUserLanguage } from './i18n/detection';
 import { useI18nRouterAdapter } from './routerAdapter';
 import {
   buildLocalizedUrl,
   detectLanguageFromPath,
   getEntryPath,
-  getPathname,
   shouldIgnoreRedirect,
 } from './utils';
 
-interface RuntimeContextWithI18n extends TRuntimeContext {
-  i18nInstance?: I18nInstance;
-}
+type WindowWithSSRData = Window & {
+  _SSR_DATA?: unknown;
+};
+
+type ResourceStoreWithEvents = NonNullable<I18nInstance['store']> & {
+  emit?: (event: string, ...args: unknown[]) => void;
+};
 
 function createMinimalI18nInstance(language: string): I18nInstance {
   const minimalInstance: I18nInstance = {
@@ -44,6 +49,7 @@ export function createContextValue(
   ignoreRedirectRoutes: string[] | ((pathname: string) => boolean) | undefined,
   localisedUrls: LocalisedUrlsOption | undefined,
   setLang: (lang: string) => void,
+  synchronizeLanguage: (lang: string) => void,
 ) {
   const instance = i18nInstance || createMinimalI18nInstance(lang);
   return {
@@ -55,6 +61,7 @@ export function createContextValue(
     ignoreRedirectRoutes,
     localisedUrls,
     updateLanguage: setLang,
+    synchronizeLanguage,
   };
 }
 
@@ -94,7 +101,7 @@ export function useSdkResourcesLoader(
       }
 
       const triggerUpdate = (retryCount = 0) => {
-        const store = (i18nInstance as any).store;
+        const store = i18nInstance.store as ResourceStoreWithEvents | undefined;
         const hasResource = store?.data?.[language]?.[namespace];
 
         if (hasResource || retryCount >= 10) {
@@ -179,7 +186,7 @@ export function useClientSideRedirect(
     }
 
     try {
-      const ssrData = (window as any)._SSR_DATA;
+      const ssrData = (window as WindowWithSSRData)._SSR_DATA;
       if (ssrData) {
         return;
       }
@@ -260,36 +267,88 @@ export function useLanguageSync(
   i18nInstance: I18nInstance | undefined,
   localePathRedirect: boolean,
   languages: string[],
-  runtimeContextRef: React.MutableRefObject<RuntimeContextWithI18n>,
+  pathname: string | undefined,
   prevLangRef: React.MutableRefObject<string>,
   setLang: (lang: string) => void,
 ) {
+  const latestRequestRef = useRef(0);
+  const syncQueueRef = useRef(Promise.resolve());
+  const isMountedRef = useRef(false);
+  const desiredLanguageRef = useRef<string | undefined>(undefined);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      latestRequestRef.current += 1;
+    };
+  }, []);
+
+  useEffect(() => {
+    desiredLanguageRef.current = undefined;
+    latestRequestRef.current += 1;
+    syncQueueRef.current = Promise.resolve();
+  }, [i18nInstance]);
+
+  const synchronizeLanguage = useCallback(
+    (currentLang: string) => {
+      if (
+        !i18nInstance ||
+        !currentLang ||
+        desiredLanguageRef.current === currentLang
+      ) {
+        return;
+      }
+
+      desiredLanguageRef.current = currentLang;
+      const requestId = ++latestRequestRef.current;
+      syncQueueRef.current = syncQueueRef.current.then(async () => {
+        if (requestId !== latestRequestRef.current || !isMountedRef.current) {
+          return;
+        }
+
+        try {
+          if (i18nInstance.language !== currentLang) {
+            await changeI18nInstanceLanguage(i18nInstance, currentLang);
+          }
+
+          if (requestId !== latestRequestRef.current || !isMountedRef.current) {
+            return;
+          }
+
+          prevLangRef.current = currentLang;
+          setLang(currentLang);
+          cacheI18nLanguage(i18nInstance, currentLang);
+        } catch (error) {
+          if (requestId === latestRequestRef.current && isMountedRef.current) {
+            desiredLanguageRef.current = undefined;
+            console.error(
+              `Failed to synchronize i18n language "${currentLang}".`,
+              error,
+            );
+          }
+        }
+      });
+    },
+    [i18nInstance, prevLangRef, setLang],
+  );
+
   useEffect(() => {
     if (!i18nInstance) {
       return;
     }
 
     if (localePathRedirect) {
-      const currentPathname = getPathname(runtimeContextRef.current);
       const pathDetection = detectLanguageFromPath(
-        currentPathname,
+        pathname || '',
         languages,
         localePathRedirect,
       );
       if (pathDetection.detected && pathDetection.language) {
-        const currentLang = pathDetection.language;
-        if (currentLang !== prevLangRef.current) {
-          prevLangRef.current = currentLang;
-          setLang(currentLang);
-          i18nInstance.setLang?.(currentLang);
-          i18nInstance.changeLanguage?.(currentLang);
-          if (isBrowser()) {
-            const detectionOptions = i18nInstance.options?.detection;
-            cacheUserLanguage(i18nInstance, currentLang, detectionOptions);
-          }
-        }
+        synchronizeLanguage(pathDetection.language);
       }
     } else {
+      latestRequestRef.current += 1;
       const instanceLang = i18nInstance.language;
       if (instanceLang && instanceLang !== prevLangRef.current) {
         prevLangRef.current = instanceLang;
@@ -300,8 +359,11 @@ export function useLanguageSync(
     i18nInstance,
     localePathRedirect,
     languages,
-    runtimeContextRef,
+    pathname,
     prevLangRef,
     setLang,
+    synchronizeLanguage,
   ]);
+
+  return synchronizeLanguage;
 }

package/src/runtime/i18n/backend/defaults.node.ts

@@ -1,5 +1,5 @@
-import fs from 'fs';
-import nodePath from 'path';
+import fs from 'node:fs';
+import nodePath from 'node:path';
 
 /**
  * Conventional locales roots, in the same priority order as the CLI plugin's

package/src/runtime/i18n/backend/middleware.common.ts

@@ -9,6 +9,7 @@ import { SdkBackend } from './sdk-backend';
 
 type BackendConfigWithChained = BaseBackendOptions &
   Partial<ChainedBackendConfig>;
+type BackendConstructor = new (...args: never[]) => unknown;
 
 function checkBackendConfig(backend?: BackendConfigWithChained) {
   const hasSdk = backend?.sdk && typeof backend.sdk === 'function';
@@ -20,7 +21,7 @@ function checkBackendConfig(backend?: BackendConfigWithChained) {
 
 function buildChainedBackendConfig(
   backend: BackendConfigWithChained,
-  BackendWithSave: new (...args: any[]) => any,
+  BackendWithSave: BackendConstructor,
 ) {
   const cacheHitMode = backend.cacheHitMode || 'refreshAndUpdateStore';
 
@@ -51,7 +52,7 @@ function buildChainedBackendConfig(
 function setupChainedBackend(
   i18nInstance: I18nInstance,
   backend: BackendConfigWithChained,
-  BackendWithSave: new (...args: any[]) => any,
+  BackendWithSave: BackendConstructor,
 ) {
   i18nInstance.use(ChainedBackend);
   const actualInstance = getActualI18nextInstance(i18nInstance);
@@ -86,8 +87,8 @@ function cleanBackendConfig(backend: BackendConfigWithChained) {
  */
 export function useI18nextBackendCommon(
   i18nInstance: I18nInstance,
-  BackendWithSave: new (...args: any[]) => any,
-  BackendBase: new (...args: any[]) => any,
+  BackendWithSave: BackendConstructor,
+  BackendBase: BackendConstructor,
   backend?: BackendConfigWithChained,
 ) {
   if (!backend) {