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

package/src/runtime/context.tsx

@@ -1,4 +1,3 @@
-import { isBrowser } from '@modern-js/runtime';
 import type { FC, ReactNode } from 'react';
 import {
   createContext,
@@ -8,18 +7,19 @@ import {
   useMemo,
 } from 'react';
 import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import {
+  changeModernI18nLanguage,
+  getPathLanguage,
+  isI18nLanguageSupported,
+  isI18nResourcesReady,
+  translateI18n,
+} from './contextHelpers';
 import type { I18nInstance } from './i18n';
-import type { SdkBackend } from './i18n/backend/sdk-backend';
-import { cacheUserLanguage } from './i18n/detection';
+import type { Resources } from './i18n/instance';
+import { getActualI18nextInstance } from './i18n/instance';
 import { useI18nRouterAdapter } from './routerAdapter';
-import {
-  buildLocalizedUrl,
-  detectLanguageFromPath,
-  getEntryPath,
-  shouldIgnoreRedirect,
-} from './utils';
 
-export interface ModernI18nContextValue {
+interface ModernI18nContextValue {
   language: string;
   i18nInstance: I18nInstance;
   // Plugin configuration for useModernI18n hook
@@ -30,6 +30,7 @@ export interface ModernI18nContextValue {
   localisedUrls?: LocalisedUrlsOption;
   // Callback to update language in context
   updateLanguage?: (newLang: string) => void;
+  synchronizeLanguage?: (newLang: string) => void;
 }
 
 const modernI18nContextKey = Symbol.for(
@@ -51,7 +52,7 @@ const getModernI18nContext = () => {
 
 const ModernI18nContext = getModernI18nContext();
 
-export interface ModernI18nProviderProps {
+interface ModernI18nProviderProps {
   children: ReactNode;
   value: ModernI18nContextValue;
 }
@@ -67,7 +68,126 @@ export const ModernI18nProvider: FC<ModernI18nProviderProps> = ({
   );
 };
 
-export interface UseModernI18nReturn {
+export interface FederatedI18nBoundaryProps {
+  children: ReactNode;
+  defaultNamespace: string;
+  fallbackLanguage?: string;
+  resources: Resources;
+  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);
+  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],
+  );
+
+  return <ModernI18nProvider value={value}>{children}</ModernI18nProvider>;
+};
+
+interface UseModernI18nReturn {
   language: string;
   changeLanguage: (newLang: string) => Promise<void>;
   t: (key: string | string[], ...args: any[]) => string;
@@ -75,7 +195,7 @@ export interface UseModernI18nReturn {
   supportedLanguages: string[];
   localisedUrls?: LocalisedUrlsOption;
   isLanguageSupported: (lang: string) => boolean;
-  // Indicates if translation resources for current language are ready to use
+  // Indicates whether translation resources for current language are ready
   isResourcesReady: boolean;
 }
 
@@ -85,9 +205,9 @@ export interface UseModernI18nReturn {
  * This hook provides:
  * - Current language from URL params or i18n context
  * - changeLanguage function that updates both i18n instance and URL
- * - Direct access to the i18n instance
+ * - Direct access to i18n instance
  * - List of supported languages
- * - Helper function to check if a language is supported
+ * - Helper function to check if language is supported
  *
  * @param options - Optional configuration to override context settings
  * @returns Object containing i18n functionality and utilities
@@ -95,7 +215,7 @@ export interface UseModernI18nReturn {
 export const useModernI18n = (): UseModernI18nReturn => {
   const context = useContext(ModernI18nContext);
   if (!context) {
-    throw new Error('useModernI18n must be used within a ModernI18nProvider');
+    throw new Error('useModernI18n must be used within ModernI18nProvider');
   }
 
   const {
@@ -106,155 +226,47 @@ export const useModernI18n = (): UseModernI18nReturn => {
     ignoreRedirectRoutes,
     localisedUrls,
     updateLanguage,
+    synchronizeLanguage,
   } = context;
 
   const { navigate, location, hasRouter } = useI18nRouterAdapter();
 
-  const pathLanguage = useMemo(() => {
-    if (!localePathRedirect || !location?.pathname) {
-      return undefined;
-    }
-    const detected = detectLanguageFromPath(
-      location.pathname,
-      languages || [],
-      localePathRedirect,
-    );
-    return detected.detected ? detected.language : undefined;
-  }, [languages, localePathRedirect, location?.pathname]);
-
-  const currentLanguage = pathLanguage || contextLanguage;
+  const pathLanguage = useMemo(
+    () => getPathLanguage(location?.pathname, languages, localePathRedirect),
+    [languages, localePathRedirect, location?.pathname],
+  );
 
   useEffect(() => {
-    if (!pathLanguage || pathLanguage === contextLanguage) {
-      return;
+    if (pathLanguage) {
+      synchronizeLanguage?.(pathLanguage);
     }
+  }, [pathLanguage, synchronizeLanguage]);
 
-    updateLanguage?.(pathLanguage);
-    i18nInstance?.setLang?.(pathLanguage);
-    void i18nInstance?.changeLanguage?.(pathLanguage);
-
-    if (isBrowser()) {
-      const detectionOptions = i18nInstance.options?.detection;
-      cacheUserLanguage(i18nInstance, pathLanguage, detectionOptions);
-    }
-  }, [contextLanguage, i18nInstance, pathLanguage, updateLanguage]);
+  const currentLanguage = contextLanguage;
 
   /**
-   * Changes the current language and updates the URL accordingly.
+   * Changes the current language and updates URL accordingly.
    *
    * This function:
-   * 1. Updates the i18n instance language
-   * 2. Updates the URL by replacing the language prefix in the current path
-   * 3. Triggers a navigation to the new URL
+   * 1. Updates i18n instance language
+   * 2. Updates URL by replacing language prefix in the current path
+   * 3. Triggers navigation to the new URL
    *
    * @param newLang - The new language code to switch to
    */
   const changeLanguage = useCallback(
-    async (newLang: string) => {
-      try {
-        // Validate language
-        if (!newLang || typeof newLang !== 'string') {
-          throw new Error('Language must be a non-empty string');
-        }
-
-        await i18nInstance?.setLang?.(newLang);
-        await i18nInstance?.changeLanguage?.(newLang);
-
-        if (isBrowser()) {
-          const detectionOptions = i18nInstance.options?.detection;
-          cacheUserLanguage(i18nInstance, newLang, detectionOptions);
-        }
-
-        if (
-          localePathRedirect &&
-          isBrowser() &&
-          hasRouter &&
-          navigate &&
-          location
-        ) {
-          const currentPath = location.pathname;
-          const entryPath = getEntryPath();
-          const relativePath = currentPath.replace(entryPath, '');
-
-          // Check if the path already contains the target language
-          const pathLanguage = detectLanguageFromPath(
-            currentPath,
-            languages || [],
-            localePathRedirect,
-          );
-
-          // If path already has the target language, skip redirect
-          if (pathLanguage.detected && pathLanguage.language === newLang) {
-            return;
-          }
-
-          if (
-            !shouldIgnoreRedirect(
-              relativePath,
-              languages || [],
-              ignoreRedirectRoutes,
-            )
-          ) {
-            const newPath = buildLocalizedUrl(
-              relativePath,
-              newLang,
-              languages || [],
-              localisedUrls,
-            );
-            const newUrl =
-              entryPath + newPath + location.search + location.hash;
-
-            await navigate(newUrl, { replace: true });
-          }
-        } else if (localePathRedirect && isBrowser() && !hasRouter) {
-          const currentPath = window.location.pathname;
-          const entryPath = getEntryPath();
-          const relativePath = currentPath.replace(entryPath, '');
-
-          // Check if the path already contains the target language
-          const pathLanguage = detectLanguageFromPath(
-            currentPath,
-            languages || [],
-            localePathRedirect,
-          );
-
-          // If path already has the target language, skip redirect
-          if (pathLanguage.detected && pathLanguage.language === newLang) {
-            return;
-          }
-
-          if (
-            !shouldIgnoreRedirect(
-              relativePath,
-              languages || [],
-              ignoreRedirectRoutes,
-            )
-          ) {
-            const newPath = buildLocalizedUrl(
-              relativePath,
-              newLang,
-              languages || [],
-              localisedUrls,
-            );
-            const newUrl =
-              entryPath +
-              newPath +
-              window.location.search +
-              window.location.hash;
-
-            window.history.pushState(null, '', newUrl);
-          }
-        }
-
-        // Update language state after URL update
-        if (updateLanguage) {
-          updateLanguage(newLang);
-        }
-      } catch (error) {
-        console.error('Failed to change language:', error);
-        throw error;
-      }
-    },
+    (newLang: string) =>
+      changeModernI18nLanguage(newLang, {
+        i18nInstance,
+        updateLanguage,
+        localePathRedirect,
+        ignoreRedirectRoutes,
+        localisedUrls,
+        languages,
+        hasRouter,
+        navigate,
+        location,
+      }),
     [
       i18nInstance,
       updateLanguage,
@@ -269,72 +281,23 @@ export const useModernI18n = (): UseModernI18nReturn => {
   );
 
   const t = useCallback(
-    (key: string | string[], ...args: any[]) => {
-      if (typeof i18nInstance.t !== 'function') {
-        throw new Error('i18nInstance.t is required');
-      }
-
-      return i18nInstance.t(key, ...args) as string;
-    },
+    (key: string | string[], ...args: any[]) =>
+      translateI18n(i18nInstance, key, ...args),
     [currentLanguage, i18nInstance],
   );
 
-  // Helper function to check if a language is supported
+  // Helper function to check if language is supported
   const isLanguageSupported = useCallback(
-    (lang: string) => {
-      return languages?.includes(lang) || false;
-    },
+    (lang: string) => isI18nLanguageSupported(languages, lang),
     [languages],
   );
 
   // Check if current language resources are ready
-  // This checks if all required namespaces for the current language are loaded
-  const isResourcesReady = useMemo(() => {
-    if (!i18nInstance?.isInitialized) {
-      return false;
-    }
-
-    // Get backend instance
-    const backend = i18nInstance?.services?.backend as SdkBackend | undefined;
-
-    // If using SDK backend, check loading state
-    if (backend && typeof backend.isLoading === 'function') {
-      // Check if any resource for current language is loading
-      const loadingResources = backend.getLoadingResources();
-      const isCurrentLanguageLoading = loadingResources.some(
-        ({ language }) => language === currentLanguage,
-      );
-      if (isCurrentLanguageLoading) {
-        return false;
-      }
-    }
-
-    // Check if resources exist in store
-    const store = (i18nInstance as any).store;
-    if (!store?.data) {
-      return false;
-    }
-
-    const langData = store.data[currentLanguage];
-    if (!langData || typeof langData !== 'object') {
-      return false;
-    }
-
-    // Get required namespaces
-    const options = i18nInstance.options;
-    const namespaces = options?.ns || options?.defaultNS || ['translation'];
-    const requiredNamespaces = Array.isArray(namespaces)
-      ? namespaces
-      : [namespaces];
-
-    // Check if all required namespaces are loaded
-    return requiredNamespaces.every(ns => {
-      const nsData = langData[ns];
-      return (
-        nsData && typeof nsData === 'object' && Object.keys(nsData).length > 0
-      );
-    });
-  }, [currentLanguage, i18nInstance]);
+  // This checks if all required namespaces for current language are loaded
+  const isResourcesReady = useMemo(
+    () => isI18nResourcesReady(i18nInstance, currentLanguage),
+    [currentLanguage, i18nInstance],
+  );
 
   return {
     language: currentLanguage,

package/src/runtime/contextHelpers.ts

@@ -0,0 +1,242 @@
+import { isBrowser } from '@modern-js/runtime';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import type { I18nInstance } from './i18n';
+import type { SdkBackend } from './i18n/backend/sdk-backend';
+import { cacheUserLanguage } from './i18n/detection';
+import {
+  buildLocalizedUrl,
+  detectLanguageFromPath,
+  getEntryPath,
+  shouldIgnoreRedirect,
+} from './utils';
+
+type Navigate = (
+  url: string,
+  options?: {
+    replace?: boolean;
+  },
+) => Promise<void> | void;
+
+type LocationLike = {
+  pathname: string;
+  search: string;
+  hash: string;
+};
+
+export function getPathLanguage(
+  pathname: string | undefined,
+  languages: string[] | undefined,
+  localePathRedirect: boolean | undefined,
+): string | undefined {
+  if (!localePathRedirect || !pathname) {
+    return undefined;
+  }
+
+  const detected = detectLanguageFromPath(
+    pathname,
+    languages || [],
+    localePathRedirect,
+  );
+  return detected.detected ? detected.language : undefined;
+}
+
+export function cacheI18nLanguage(
+  i18nInstance: I18nInstance,
+  language: string,
+) {
+  if (isBrowser()) {
+    const detectionOptions = i18nInstance.options?.detection;
+    cacheUserLanguage(i18nInstance, language, detectionOptions);
+  }
+}
+
+export async function changeI18nInstanceLanguage(
+  i18nInstance: I18nInstance,
+  language: string,
+): Promise<void> {
+  if (i18nInstance.setLang) {
+    await i18nInstance.setLang(language);
+  } else {
+    await i18nInstance.changeLanguage?.(language);
+  }
+}
+
+interface ChangeModernI18nLanguageOptions {
+  i18nInstance: I18nInstance;
+  updateLanguage?: (newLang: string) => void;
+  localePathRedirect?: boolean;
+  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+  localisedUrls?: LocalisedUrlsOption;
+  languages?: string[];
+  hasRouter: boolean;
+  navigate?: Navigate | null;
+  location?: LocationLike | null;
+}
+
+export async function changeModernI18nLanguage(
+  newLang: string,
+  options: ChangeModernI18nLanguageOptions,
+): Promise<void> {
+  const {
+    i18nInstance,
+    updateLanguage,
+    localePathRedirect,
+    ignoreRedirectRoutes,
+    localisedUrls,
+    languages,
+    hasRouter,
+    navigate,
+    location,
+  } = options;
+
+  try {
+    if (!newLang || typeof newLang !== 'string') {
+      throw new Error('Language must be non-empty string');
+    }
+
+    await changeI18nInstanceLanguage(i18nInstance, newLang);
+    cacheI18nLanguage(i18nInstance, newLang);
+
+    if (
+      localePathRedirect &&
+      isBrowser() &&
+      hasRouter &&
+      navigate &&
+      location
+    ) {
+      const currentPath = location.pathname;
+      const entryPath = getEntryPath();
+      const relativePath = currentPath.replace(entryPath, '');
+      const pathLanguage = detectLanguageFromPath(
+        currentPath,
+        languages || [],
+        localePathRedirect,
+      );
+
+      if (pathLanguage.detected && pathLanguage.language === newLang) {
+        updateLanguage?.(newLang);
+        return;
+      }
+
+      if (
+        !shouldIgnoreRedirect(
+          relativePath,
+          languages || [],
+          ignoreRedirectRoutes,
+        )
+      ) {
+        const newPath = buildLocalizedUrl(
+          relativePath,
+          newLang,
+          languages || [],
+          localisedUrls,
+        );
+        const newUrl = entryPath + newPath + location.search + location.hash;
+
+        await navigate(newUrl, { replace: true });
+      }
+    } else if (localePathRedirect && isBrowser() && !hasRouter) {
+      const currentPath = window.location.pathname;
+      const entryPath = getEntryPath();
+      const relativePath = currentPath.replace(entryPath, '');
+      const pathLanguage = detectLanguageFromPath(
+        currentPath,
+        languages || [],
+        localePathRedirect,
+      );
+
+      if (pathLanguage.detected && pathLanguage.language === newLang) {
+        updateLanguage?.(newLang);
+        return;
+      }
+
+      if (
+        !shouldIgnoreRedirect(
+          relativePath,
+          languages || [],
+          ignoreRedirectRoutes,
+        )
+      ) {
+        const newPath = buildLocalizedUrl(
+          relativePath,
+          newLang,
+          languages || [],
+          localisedUrls,
+        );
+        const newUrl =
+          entryPath + newPath + window.location.search + window.location.hash;
+
+        window.history.pushState(null, '', newUrl);
+      }
+    }
+
+    if (updateLanguage) {
+      updateLanguage(newLang);
+    }
+  } catch (error) {
+    console.error('Failed change language:', error);
+    throw error;
+  }
+}
+
+export function translateI18n(
+  i18nInstance: I18nInstance,
+  key: string | string[],
+  ...args: unknown[]
+): string {
+  if (typeof i18nInstance.t !== 'function') {
+    throw new Error('i18nInstance.t required');
+  }
+
+  return i18nInstance.t(key, ...args) as string;
+}
+
+export function isI18nLanguageSupported(
+  languages: string[] | undefined,
+  lang: string,
+): boolean {
+  return languages?.includes(lang) || false;
+}
+
+export function isI18nResourcesReady(
+  i18nInstance: I18nInstance,
+  currentLanguage: string,
+): boolean {
+  if (!i18nInstance?.isInitialized) {
+    return false;
+  }
+
+  const backend = i18nInstance?.services?.backend as SdkBackend | undefined;
+  if (backend && typeof backend.isLoading === 'function') {
+    const loadingResources = backend.getLoadingResources();
+    const isCurrentLanguageLoading = loadingResources.some(
+      ({ language }) => language === currentLanguage,
+    );
+    if (isCurrentLanguageLoading) {
+      return false;
+    }
+  }
+
+  const store = i18nInstance.store;
+  if (!store?.data) {
+    return false;
+  }
+
+  const langData = store.data[currentLanguage];
+  if (!langData || typeof langData !== 'object') {
+    return false;
+  }
+
+  const options = i18nInstance.options;
+  const namespaces = options?.ns || options?.defaultNS || ['translation'];
+  const requiredNamespaces = Array.isArray(namespaces)
+    ? namespaces
+    : [namespaces];
+
+  return requiredNamespaces.every(ns => {
+    const nsData = langData[ns];
+    return (
+      nsData && typeof nsData === 'object' && Object.keys(nsData).length > 0
+    );
+  });
+}