@bleedingdev/modern-js-plugin-i18n 3.5.0-ultramodern.4 → 3.5.0-ultramodern.41

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,
+        }),
+      );
     },
   });
 

package/src/runtime/hooks.ts

@@ -21,8 +21,19 @@ import {
 
 interface RuntimeContextWithI18n extends TRuntimeContext {
   i18nInstance?: I18nInstance;
+  // Present when the context actually is the internal runtime context;
+  // getPathname only ever reads this on the server.
+  ssrContext?: { request?: { pathname?: string } };
 }
 
+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 = {
     language,
@@ -94,7 +105,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 +190,7 @@ export function useClientSideRedirect(
     }
 
     try {
-      const ssrData = (window as any)._SSR_DATA;
+      const ssrData = (window as WindowWithSSRData)._SSR_DATA;
       if (ssrData) {
         return;
       }

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) {

package/src/runtime/i18n/detection/cache.ts

@@ -0,0 +1,189 @@
+import type {
+  I18nInitOptions,
+  I18nInstance,
+  LanguageDetectorOptions,
+} from '../instance';
+
+interface DetectorCacheEntry {
+  instance: I18nInstance;
+  isTemporary: boolean;
+  configKey: string;
+}
+
+type DetectorCleanupInstance = I18nInstance & {
+  removeAllListeners?: () => void;
+  off?: (event: string) => void;
+  services?: I18nInstance['services'] & {
+    backendConnector?: {
+      backend?: {
+        stop?: () => void;
+        close?: () => void;
+      };
+    };
+  };
+};
+
+export const detectorInstanceCache = new WeakMap<
+  I18nInstance,
+  DetectorCacheEntry
+>();
+
+const DETECTOR_SAFE_OPTION_KEYS: string[] = [
+  'lowerCaseLng',
+  'nonExplicitSupportedLngs',
+  'load',
+  'partialBundledLanguages',
+  'returnNull',
+  'returnEmptyString',
+  'returnObjects',
+  'joinArrays',
+  'keySeparator',
+  'nsSeparator',
+  'pluralSeparator',
+  'contextSeparator',
+  'fallbackNS',
+  'ns',
+  'defaultNS',
+  'debug',
+];
+
+/**
+ * Stable stringify that sorts object keys to ensure consistent output
+ * regardless of property order
+ */
+const stableStringify = (value: unknown): string => {
+  if (value === null || value === undefined) {
+    return JSON.stringify(value);
+  }
+
+  if (typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    // Arrays maintain their order
+    return `[${value.map(item => stableStringify(item)).join(',')}]`;
+  }
+
+  // For objects, sort keys and recursively stringify values
+  const record = value as Record<string, unknown>;
+  const sortedKeys = Object.keys(record).sort();
+  const sortedEntries = sortedKeys.map(key => {
+    const stringifiedValue = stableStringify(record[key]);
+    return `${JSON.stringify(key)}:${stringifiedValue}`;
+  });
+
+  return `{${sortedEntries.join(',')}}`;
+};
+
+export const buildDetectorConfigKey = (
+  languages: string[],
+  fallbackLanguage: string,
+  mergedDetection: LanguageDetectorOptions,
+): string => {
+  return stableStringify({
+    languages,
+    fallbackLanguage,
+    detection: mergedDetection,
+  });
+};
+
+export const pickSafeDetectionOptions = (
+  userInitOptions?: I18nInitOptions,
+): Partial<I18nInitOptions> & Record<string, unknown> => {
+  if (!userInitOptions) {
+    return {};
+  }
+  const safeOptions: Partial<I18nInitOptions> & Record<string, unknown> = {};
+  for (const key of DETECTOR_SAFE_OPTION_KEYS) {
+    const value = (userInitOptions as Record<string, unknown>)[key];
+    if (value !== undefined) {
+      safeOptions[key] = value;
+    }
+  }
+  if (userInitOptions.interpolation) {
+    safeOptions.interpolation = { ...userInitOptions.interpolation };
+  }
+  return safeOptions;
+};
+
+const cleanupDetectorCacheEntry = (entry?: DetectorCacheEntry) => {
+  if (!entry || !entry.isTemporary) {
+    return;
+  }
+  const instance = entry.instance as DetectorCleanupInstance;
+  try {
+    instance?.removeAllListeners?.();
+  } catch (error) {
+    void error;
+  }
+  try {
+    instance?.off?.('*');
+  } catch (error) {
+    void error;
+  }
+  try {
+    instance?.services?.backendConnector?.backend?.stop?.();
+  } catch (error) {
+    void error;
+  }
+  try {
+    instance?.services?.backendConnector?.backend?.close?.();
+  } catch (error) {
+    void error;
+  }
+};
+
+export const createDetectorInstance = (
+  baseInstance: I18nInstance,
+  configKey: string,
+): { instance: I18nInstance; isTemporary: boolean } => {
+  const cached = detectorInstanceCache.get(baseInstance);
+  if (cached && cached.configKey === configKey) {
+    return { instance: cached.instance, isTemporary: cached.isTemporary };
+  }
+
+  if (cached) {
+    cleanupDetectorCacheEntry(cached);
+    detectorInstanceCache.delete(baseInstance);
+  }
+
+  const createNewInstance = (): {
+    instance: I18nInstance;
+    isTemporary: boolean;
+  } => {
+    if (typeof baseInstance.createInstance === 'function') {
+      try {
+        const created = baseInstance.createInstance();
+        if (created) {
+          return { instance: created, isTemporary: true };
+        }
+      } catch (error) {
+        void error;
+      }
+    }
+
+    if (typeof baseInstance.cloneInstance === 'function') {
+      try {
+        const cloned = baseInstance.cloneInstance();
+        if (cloned) {
+          return { instance: cloned, isTemporary: true };
+        }
+      } catch (error) {
+        void error;
+      }
+    }
+
+    return { instance: baseInstance, isTemporary: false };
+  };
+
+  const created = createNewInstance();
+  if (created.isTemporary) {
+    detectorInstanceCache.set(baseInstance, {
+      instance: created.instance,
+      isTemporary: true,
+      configKey,
+    });
+  }
+  return created;
+};