@bleedingdev/modern-js-plugin-i18n 3.5.0-ultramodern.30 → 3.5.0-ultramodern.31

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: RuntimeContextWithI18n) => {
-        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(
+        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: React.ComponentType<any>) => {
-        return (props: Record<string, unknown>) => {
-          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/i18n/detection/cache.ts

@@ -0,0 +1,175 @@
+import type {
+  I18nInitOptions,
+  I18nInstance,
+  LanguageDetectorOptions,
+} from '../instance';
+
+interface DetectorCacheEntry {
+  instance: I18nInstance;
+  isTemporary: boolean;
+  configKey: string;
+}
+
+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: any): 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 sortedKeys = Object.keys(value).sort();
+  const sortedEntries = sortedKeys.map(key => {
+    const stringifiedValue = stableStringify(value[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, any> => {
+  if (!userInitOptions) {
+    return {};
+  }
+  const safeOptions: Partial<I18nInitOptions> & Record<string, any> = {};
+  for (const key of DETECTOR_SAFE_OPTION_KEYS) {
+    const value = (userInitOptions as any)[key];
+    if (value !== undefined) {
+      safeOptions[key] = value;
+    }
+  }
+  if ((userInitOptions as any).interpolation) {
+    safeOptions.interpolation = { ...(userInitOptions as any).interpolation };
+  }
+  return safeOptions;
+};
+
+const cleanupDetectorCacheEntry = (entry?: DetectorCacheEntry) => {
+  if (!entry || !entry.isTemporary) {
+    return;
+  }
+  const instance = entry.instance as any;
+  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;
+};

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

@@ -0,0 +1,157 @@
+import { isBrowser } from '@modern-js/runtime';
+import type { I18nInitOptions, I18nInstance } from '../instance';
+
+import {
+  buildDetectorConfigKey,
+  createDetectorInstance,
+  detectorInstanceCache,
+  pickSafeDetectionOptions,
+} from './cache';
+
+import { mergeDetectionOptions } from './initOptions';
+
+import { getSupportedLanguage, isLanguageSupported } from './language';
+
+import { detectLanguage, useI18nextLanguageDetector } from './middleware';
+
+import type { BaseLanguageDetectionOptions } from './types';
+
+/**
+ * Initialize i18n instance for detector if needed
+ */
+interface DetectorInitResult {
+  detectorInstance: I18nInstance;
+  isTemporary: boolean;
+}
+
+const initializeI18nForDetector = async (
+  i18nInstance: I18nInstance,
+  options: BaseLanguageDetectionOptions,
+): Promise<DetectorInitResult> => {
+  const mergedDetection = mergeDetectionOptions(
+    options.i18nextDetector,
+    options.detection,
+    options.localePathRedirect,
+    options.userInitOptions,
+  );
+
+  const configKey = buildDetectorConfigKey(
+    options.languages,
+    options.fallbackLanguage,
+    mergedDetection,
+  );
+
+  const { instance, isTemporary } = createDetectorInstance(
+    i18nInstance,
+    configKey,
+  );
+
+  const safeUserOptions = pickSafeDetectionOptions(options.userInitOptions);
+
+  // Only initialize detection capability, don't load any resources to avoid conflicts with subsequent backend initialization
+  const initOptions: I18nInitOptions = {
+    ...safeUserOptions,
+    fallbackLng: options.fallbackLanguage,
+    supportedLngs: options.languages,
+    detection: mergedDetection,
+    initImmediate: true,
+    interpolation: {
+      ...(safeUserOptions?.interpolation || {}),
+      escapeValue: safeUserOptions?.interpolation?.escapeValue ?? false,
+    },
+    react: {
+      useSuspense: false,
+    },
+  };
+
+  // Ensure the detector instance has the language detection plugin loaded
+  useI18nextLanguageDetector(instance);
+
+  if (!instance.isInitialized) {
+    await instance.init(initOptions);
+  } else if (isTemporary) {
+    await instance.init(initOptions);
+  }
+
+  return { detectorInstance: instance, isTemporary };
+};
+
+/**
+ * Priority 3: Detect language using i18next detector
+ */
+export const detectLanguageFromI18nextDetector = async (
+  i18nInstance: I18nInstance,
+  options: BaseLanguageDetectionOptions & { ssrContext?: any },
+): Promise<string | undefined> => {
+  if (!options.i18nextDetector) {
+    return undefined;
+  }
+
+  // Merge detection options to pass to detector
+  const mergedDetection = mergeDetectionOptions(
+    options.i18nextDetector,
+    options.detection,
+    options.localePathRedirect,
+    options.userInitOptions,
+  );
+
+  const { detectorInstance, isTemporary } = await initializeI18nForDetector(
+    i18nInstance,
+    options,
+  );
+
+  try {
+    const request = options.ssrContext?.request;
+    if (!isBrowser() && !request) {
+      return undefined;
+    }
+
+    const detectorLang = detectLanguage(
+      detectorInstance,
+      request as any,
+      mergedDetection,
+    );
+
+    // Use getSupportedLanguage to get the matching supported language
+    // This handles both exact match and base language code match (e.g., 'zh-CN' -> 'zh')
+    if (detectorLang) {
+      const supportedLang = getSupportedLanguage(
+        detectorLang,
+        options.languages,
+      );
+      if (supportedLang) {
+        return supportedLang;
+      }
+    }
+
+    // Fallback to instance's current language if detector didn't detect
+    if (detectorInstance.isInitialized && detectorInstance.language) {
+      const currentLang = detectorInstance.language;
+      if (isLanguageSupported(currentLang, options.languages)) {
+        return currentLang;
+      }
+    }
+  } catch (error) {
+    // Silently ignore errors
+  } finally {
+    // Clean up temporary instance to avoid affecting subsequent formal initialization
+    if (isTemporary && detectorInstance !== i18nInstance) {
+      // Temporary instance is saved in cache for reuse
+      detectorInstanceCache.set(i18nInstance, {
+        instance: detectorInstance,
+        isTemporary: true,
+        configKey: buildDetectorConfigKey(
+          options.languages,
+          options.fallbackLanguage,
+          mergedDetection,
+        ),
+      });
+    } else if (detectorInstance === i18nInstance) {
+      // As a fallback, prevent i18nInstance from being polluted by detector init
+      (i18nInstance as any).isInitialized = false;
+      delete (i18nInstance as any).language;
+    }
+  }
+
+  return undefined;
+};