@bleedingdev/modern-js-plugin-i18n 3.4.0-ultramodern.1 → 3.4.0-ultramodern.2

package/dist/types/runtime/index.d.ts

@@ -1,25 +1,3 @@
-import { type RuntimePlugin } from '@modern-js/runtime';
-import type { BaseBackendOptions, BaseLocaleDetectionOptions } from '../shared/type';
-import type { I18nInitOptions, I18nInstance } from './i18n';
-import './types';
-export type { I18nSdkLoader, I18nSdkLoadOptions } from '../shared/type';
-export type { Resources } from './i18n/instance';
-export interface I18nPluginOptions {
-    entryName?: string;
-    localeDetection?: BaseLocaleDetectionOptions;
-    backend?: BaseBackendOptions;
-    i18nInstance?: I18nInstance;
-    changeLanguage?: (lang: string) => void;
-    initOptions?: I18nInitOptions;
-    htmlLangAttr?: boolean;
-    reactI18next?: boolean;
-    [key: string]: any;
-}
-export declare const i18nPlugin: (options: I18nPluginOptions) => RuntimePlugin;
-export type { AllowedLinkTarget, CanonicalRoutePath, UltramodernCanonicalRoutes, } from './canonicalRoutes';
-export { useModernI18n } from './context';
-export { I18nLink, type I18nLinkProps } from './I18nLink';
-export { Link, type LinkActiveOptions, type LinkBaseProps, type LinkParams, type LinkProps, } from './Link';
-export { canonicalPath, type LocalizedPathsConfig, localizePath, type UseLocalizedLocationReturn, type UseLocalizedPathsReturn, useLocalizedLocation, useLocalizedPaths, } from './localizedPaths';
-export { buildLocalizedUrl, splitUrlTarget } from './utils';
+export * from './core';
+export declare const i18nPlugin: (options: import("./core").I18nPluginOptions) => import("@modern-js/runtime").RuntimePlugin;
 export default i18nPlugin;

package/dist/types/runtime/no-react-i18next.d.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export declare const i18nPlugin: (options: import("./core").I18nPluginOptions) => import("@modern-js/runtime").RuntimePlugin;
+export default i18nPlugin;

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.4.0-ultramodern.1",
+  "version": "3.4.0-ultramodern.2",
   "engines": {
     "node": ">=20"
   },
@@ -48,6 +48,13 @@
       },
       "default": "./dist/esm/runtime/index.mjs"
     },
+    "./runtime/no-react-i18next": {
+      "types": "./dist/types/runtime/no-react-i18next.d.ts",
+      "node": {
+        "module": "./dist/esm/runtime/no-react-i18next.mjs"
+      },
+      "default": "./dist/esm/runtime/no-react-i18next.mjs"
+    },
     "./server": {
       "types": "./dist/types/server/index.d.ts",
       "node": {
@@ -72,6 +79,9 @@
       "runtime": [
         "./dist/types/runtime/index.d.ts"
       ],
+      "runtime/no-react-i18next": [
+        "./dist/types/runtime/no-react-i18next.d.ts"
+      ],
       "server": [
         "./dist/types/server/index.d.ts"
       ],
@@ -87,15 +97,15 @@
     "i18next-fs-backend": "^2.6.6",
     "i18next-http-backend": "^4.0.0",
     "i18next-http-middleware": "^3.9.7",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.4.0-ultramodern.1",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.4.0-ultramodern.1",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.4.0-ultramodern.1",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.4.0-ultramodern.1",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.4.0-ultramodern.1",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.4.0-ultramodern.1"
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.4.0-ultramodern.2",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.4.0-ultramodern.2",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.4.0-ultramodern.2",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.4.0-ultramodern.2",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.4.0-ultramodern.2",
+    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.4.0-ultramodern.2"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.4.0-ultramodern.1",
+    "@modern-js/runtime": "3.4.0-ultramodern.2",
     "i18next": ">=26.3.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
@@ -111,7 +121,7 @@
   },
   "devDependencies": {
     "@rslib/core": "0.23.0",
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.0.1",
     "@typescript/native-preview": "7.0.0-dev.20260624.1",
     "i18next": "26.3.2",
     "react": "^19.2.7",
@@ -119,8 +129,8 @@
     "react-i18next": "17.0.8",
     "ts-node": "^10.9.2",
     "typescript": "^6.0.3",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.4.0-ultramodern.1",
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.4.0-ultramodern.1"
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.4.0-ultramodern.2",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.4.0-ultramodern.2"
   },
   "sideEffects": false,
   "publishConfig": {

package/rstest.config.mts

@@ -31,6 +31,7 @@ export default {
         'tests/localisedUrls.test.ts',
         'tests/linkTypes.test.ts',
         'tests/backendDefaults.test.ts',
+        'tests/reactI18nextRuntimeBoundary.test.ts',
       ],
       extends: commonConfig,
     }),

package/src/cli/index.ts

@@ -126,10 +126,15 @@ export const i18nPlugin = (
         backend: backendOptions,
         ...extendedConfig,
       };
+      const runtimePluginPath =
+        customPlugin?.runtime?.path ||
+        (config.reactI18next === false
+          ? `@${metaName}/plugin-i18n/runtime/no-react-i18next`
+          : `@${metaName}/plugin-i18n/runtime`);
 
       plugins.push({
         name: customPlugin?.runtime?.name || 'i18n',
-        path: customPlugin?.runtime?.path || `@${metaName}/plugin-i18n/runtime`,
+        path: runtimePluginPath,
         config,
       });
       return {

package/src/runtime/core.tsx

@@ -0,0 +1,335 @@
+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 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 { useI18nextBackend } from './i18n/backend/middleware';
+import {
+  detectLanguageWithPriority,
+  exportServerLngToWindow,
+  mergeDetectionOptions,
+} from './i18n/detection';
+import { useI18nextLanguageDetector } from './i18n/detection/middleware';
+import { getI18nextInstanceForProvider } from './i18n/instance';
+import {
+  changeI18nLanguage,
+  ensureLanguageMatch,
+  initializeI18nInstance,
+  setupClonedInstance,
+} from './i18n/utils';
+import { getPathname } from './utils';
+import './types';
+
+export type { I18nSdkLoader, I18nSdkLoadOptions } from '../shared/type';
+export type { Resources } from './i18n/instance';
+
+export interface I18nPluginOptions {
+  entryName?: string;
+  localeDetection?: BaseLocaleDetectionOptions;
+  backend?: BaseBackendOptions;
+  i18nInstance?: I18nInstance;
+  changeLanguage?: (lang: string) => void;
+  initOptions?: I18nInitOptions;
+  htmlLangAttr?: boolean;
+  reactI18next?: boolean;
+  [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,
+  ): ((options: I18nPluginOptions) => RuntimePlugin) =>
+  (options: I18nPluginOptions): RuntimePlugin => ({
+    name: '@modern-js/plugin-i18n',
+    setup: api => {
+      const {
+        entryName,
+        i18nInstance: userI18nInstance,
+        initOptions,
+        localeDetection,
+        backend,
+        htmlLangAttr = false,
+        reactI18next = true,
+      } = options;
+      const {
+        localePathRedirect = false,
+        i18nextDetector = true,
+        languages = [],
+        fallbackLanguage = 'en',
+        detection,
+        ignoreRedirectRoutes,
+        localisedUrls,
+      } = localeDetection || {};
+      const { enabled: backendEnabled = false } = backend || {};
+      let latestI18nInstance: I18nInstance | undefined;
+      let I18nextProvider: React.ComponentType<any> | null;
+
+      const resolveReactI18nextIntegration = async () => {
+        if (!reactI18next) {
+          return null;
+        }
+        return loadReactI18nextIntegration?.() ?? null;
+      };
+
+      api.onBeforeRender(async context => {
+        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(
+          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,
+          });
+        };
+      });
+
+      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;
+        };
+      });
+    },
+  });
+
+export type {
+  AllowedLinkTarget,
+  CanonicalRoutePath,
+  UltramodernCanonicalRoutes,
+} from './canonicalRoutes';
+export { useModernI18n } from './context';
+export { I18nLink, type I18nLinkProps } from './I18nLink';
+export {
+  Link,
+  type LinkActiveOptions,
+  type LinkBaseProps,
+  type LinkParams,
+  type LinkProps,
+} from './Link';
+export {
+  canonicalPath,
+  type LocalizedPathsConfig,
+  localizePath,
+  type UseLocalizedLocationReturn,
+  type UseLocalizedPathsReturn,
+  useLocalizedLocation,
+  useLocalizedPaths,
+} from './localizedPaths';
+export { buildLocalizedUrl, splitUrlTarget } from './utils';