@modern-js/plugin-i18n 2.69.7 → 3.0.0-alpha.1

package/src/runtime/context.tsx

@@ -0,0 +1,256 @@
+import { isBrowser } from '@modern-js/runtime';
+import { createContext, useCallback, useContext, useMemo } from 'react';
+import type { FC, ReactNode } from 'react';
+import type { I18nInstance } from './i18n';
+import type { SdkBackend } from './i18n/backend/sdk-backend';
+import { cacheUserLanguage } from './i18n/detection';
+import {
+  buildLocalizedUrl,
+  getEntryPath,
+  shouldIgnoreRedirect,
+  useRouterHooks,
+} from './utils';
+
+export interface ModernI18nContextValue {
+  language: string;
+  i18nInstance: I18nInstance;
+  // Plugin configuration for useModernI18n hook
+  entryName?: string;
+  languages?: string[];
+  localePathRedirect?: boolean;
+  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+  // Callback to update language in context
+  updateLanguage?: (newLang: string) => void;
+}
+
+const ModernI18nContext = createContext<ModernI18nContextValue | null>(null);
+
+export interface ModernI18nProviderProps {
+  children: ReactNode;
+  value: ModernI18nContextValue;
+}
+
+export const ModernI18nProvider: FC<ModernI18nProviderProps> = ({
+  children,
+  value,
+}) => {
+  return (
+    <ModernI18nContext.Provider value={value}>
+      {children}
+    </ModernI18nContext.Provider>
+  );
+};
+
+export interface UseModernI18nReturn {
+  language: string;
+  changeLanguage: (newLang: string) => Promise<void>;
+  i18nInstance: I18nInstance;
+  supportedLanguages: string[];
+  isLanguageSupported: (lang: string) => boolean;
+  // Indicates if translation resources for current language are ready to use
+  isResourcesReady: boolean;
+}
+
+/**
+ * Hook for accessing i18n functionality in Modern.js applications.
+ *
+ * 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
+ * - List of supported languages
+ * - Helper function to check if a language is supported
+ *
+ * @param options - Optional configuration to override context settings
+ * @returns Object containing i18n functionality and utilities
+ */
+export const useModernI18n = (): UseModernI18nReturn => {
+  const context = useContext(ModernI18nContext);
+  if (!context) {
+    throw new Error('useModernI18n must be used within a ModernI18nProvider');
+  }
+
+  const {
+    language: contextLanguage,
+    i18nInstance,
+    languages,
+    localePathRedirect,
+    ignoreRedirectRoutes,
+    updateLanguage,
+  } = context;
+
+  // Get router hooks safely
+  const { navigate, location, hasRouter } = useRouterHooks();
+
+  // Get current language from context (which reflects the actual current language)
+  // URL params might be stale after language changes, so we prioritize the context language
+  const currentLanguage = contextLanguage;
+
+  /**
+   * Changes the current language and updates the 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
+   *
+   * @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, '');
+
+          if (
+            !shouldIgnoreRedirect(
+              relativePath,
+              languages || [],
+              ignoreRedirectRoutes,
+            )
+          ) {
+            const newPath = buildLocalizedUrl(
+              relativePath,
+              newLang,
+              languages || [],
+            );
+            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, '');
+
+          if (
+            !shouldIgnoreRedirect(
+              relativePath,
+              languages || [],
+              ignoreRedirectRoutes,
+            )
+          ) {
+            const newPath = buildLocalizedUrl(
+              relativePath,
+              newLang,
+              languages || [],
+            );
+            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;
+      }
+    },
+    [
+      i18nInstance,
+      updateLanguage,
+      localePathRedirect,
+      ignoreRedirectRoutes,
+      languages,
+      hasRouter,
+      navigate,
+      location,
+    ],
+  );
+
+  // Helper function to check if a language is supported
+  const isLanguageSupported = useCallback(
+    (lang: string) => {
+      return languages?.includes(lang) || false;
+    },
+    [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]);
+
+  return {
+    language: currentLanguage,
+    changeLanguage,
+    i18nInstance,
+    supportedLanguages: languages || [],
+    isLanguageSupported,
+    isResourcesReady,
+  };
+};

package/src/runtime/hooks.ts

@@ -0,0 +1,274 @@
+import { isBrowser } from '@modern-js/runtime';
+import type { TRuntimeContext } from '@modern-js/runtime';
+import type React from 'react';
+import { useEffect, useRef } from 'react';
+import type { I18nInstance } from './i18n';
+import { cacheUserLanguage } from './i18n/detection';
+import {
+  buildLocalizedUrl,
+  detectLanguageFromPath,
+  getEntryPath,
+  getPathname,
+  shouldIgnoreRedirect,
+  useRouterHooks,
+} from './utils';
+
+interface RuntimeContextWithI18n extends TRuntimeContext {
+  i18nInstance?: I18nInstance;
+}
+
+function createMinimalI18nInstance(language: string): I18nInstance {
+  const minimalInstance: I18nInstance = {
+    language,
+    isInitialized: false,
+    init: () => Promise.resolve(undefined),
+    use: () => {},
+    createInstance: () => minimalInstance,
+    services: {},
+  };
+  return minimalInstance;
+}
+
+export function createContextValue(
+  lang: string,
+  i18nInstance: I18nInstance | undefined,
+  entryName: string | undefined,
+  languages: string[],
+  localePathRedirect: boolean,
+  ignoreRedirectRoutes: string[] | ((pathname: string) => boolean) | undefined,
+  setLang: (lang: string) => void,
+) {
+  const instance = i18nInstance || createMinimalI18nInstance(lang);
+  return {
+    language: lang,
+    i18nInstance: instance,
+    entryName,
+    languages,
+    localePathRedirect,
+    ignoreRedirectRoutes,
+    updateLanguage: setLang,
+  };
+}
+
+export function useSdkResourcesLoader(
+  i18nInstance: I18nInstance | undefined,
+  setForceUpdate: React.Dispatch<React.SetStateAction<number>>,
+) {
+  useEffect(() => {
+    if (!i18nInstance || !isBrowser()) {
+      return;
+    }
+
+    const handleSdkResourcesLoaded = (event: Event) => {
+      const customEvent = event as CustomEvent<{
+        language: string;
+        namespace: string;
+      }>;
+      const { language, namespace } = customEvent.detail;
+
+      const triggerUpdate = (retryCount = 0) => {
+        const store = (i18nInstance as any).store;
+        const hasResource = store?.data?.[language]?.[namespace];
+
+        if (hasResource || retryCount >= 10) {
+          if (store?.data?.[language]?.[namespace]) {
+            if (typeof store.emit === 'function') {
+              store.emit('added', language, namespace);
+            }
+          }
+
+          if (typeof i18nInstance.emit === 'function') {
+            i18nInstance.emit('loaded', { language, namespace });
+            i18nInstance.emit('loaded', language, namespace);
+          }
+
+          if (typeof i18nInstance.reloadResources === 'function') {
+            i18nInstance
+              .reloadResources(language, namespace)
+              .then(() => {
+                if (typeof i18nInstance.emit === 'function') {
+                  i18nInstance.emit('loaded', { language, namespace });
+                }
+                setForceUpdate(prev => prev + 1);
+              })
+              .catch(() => {
+                // Ignore errors from reloadResources
+              });
+          }
+
+          if (typeof i18nInstance.emit === 'function') {
+            i18nInstance.emit('languageChanged', language);
+          }
+
+          setForceUpdate(prev => prev + 1);
+        } else {
+          setTimeout(() => triggerUpdate(retryCount + 1), 10);
+        }
+      };
+
+      triggerUpdate();
+    };
+
+    window.addEventListener(
+      'i18n-sdk-resources-loaded',
+      handleSdkResourcesLoaded,
+    );
+
+    return () => {
+      window.removeEventListener(
+        'i18n-sdk-resources-loaded',
+        handleSdkResourcesLoaded,
+      );
+    };
+  }, [i18nInstance, setForceUpdate]);
+}
+
+/**
+ * Hook to handle client-side redirect for locale path redirect in static deployments
+ * This ensures that when users access paths without language prefix, they are redirected
+ * to the localized version of the path
+ *
+ * Note: This hook only runs in CSR (Client-Side Rendering) scenarios.
+ * In SSR/SSG scenarios, server-side middleware handles redirects, so this hook is skipped.
+ * We use process.env.MODERN_TARGET to ensure this code is only included in browser bundles.
+ */
+export function useClientSideRedirect(
+  i18nInstance: I18nInstance | undefined,
+  localePathRedirect: boolean,
+  languages: string[],
+  fallbackLanguage: string,
+  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
+) {
+  const hasRedirectedRef = useRef(false);
+  // Get router hooks safely
+  const { navigate, location, hasRouter } = useRouterHooks();
+
+  useEffect(() => {
+    if (process.env.MODERN_TARGET !== 'browser') {
+      return;
+    }
+    if (!localePathRedirect || !i18nInstance) {
+      return;
+    }
+
+    try {
+      const ssrData = (window as any)._SSR_DATA;
+      if (ssrData) {
+        return;
+      }
+    } catch {
+      // Ignore errors when checking SSR data
+    }
+
+    if (hasRedirectedRef.current) {
+      return;
+    }
+
+    if (!i18nInstance.isInitialized) {
+      return;
+    }
+
+    // Use router location if available, otherwise fallback to window.location
+    const currentPathname =
+      hasRouter && location ? location.pathname : window.location.pathname;
+    const currentSearch =
+      hasRouter && location ? location.search : window.location.search;
+    const currentHash =
+      hasRouter && location ? location.hash : window.location.hash;
+
+    const entryPath = getEntryPath();
+    const relativePath = currentPathname.replace(entryPath, '');
+
+    if (shouldIgnoreRedirect(relativePath, languages, ignoreRedirectRoutes)) {
+      return;
+    }
+
+    const pathDetection = detectLanguageFromPath(
+      currentPathname,
+      languages,
+      localePathRedirect,
+    );
+
+    if (pathDetection.detected) {
+      return;
+    }
+
+    const targetLanguage =
+      i18nInstance.language || fallbackLanguage || languages[0] || 'en';
+
+    const newPath = buildLocalizedUrl(relativePath, targetLanguage, languages);
+    const newUrl = entryPath + newPath + currentSearch + currentHash;
+
+    if (newUrl !== currentPathname + currentSearch + currentHash) {
+      hasRedirectedRef.current = true;
+
+      // Use navigate if router is available (similar to changeLanguage implementation)
+      if (hasRouter && navigate && location) {
+        navigate(newUrl, { replace: true });
+      } else {
+        // Fallback to window.location.replace for non-router scenarios
+        // This ensures the new URL is properly recognized and translations are reloaded
+        window.location.replace(newUrl);
+      }
+    }
+  }, [
+    navigate,
+    location,
+    hasRouter,
+    localePathRedirect,
+    i18nInstance,
+    languages,
+    fallbackLanguage,
+    ignoreRedirectRoutes,
+  ]);
+}
+
+export function useLanguageSync(
+  i18nInstance: I18nInstance | undefined,
+  localePathRedirect: boolean,
+  languages: string[],
+  runtimeContextRef: React.MutableRefObject<RuntimeContextWithI18n>,
+  prevLangRef: React.MutableRefObject<string>,
+  setLang: (lang: string) => void,
+) {
+  useEffect(() => {
+    if (!i18nInstance) {
+      return;
+    }
+
+    if (localePathRedirect) {
+      const currentPathname = getPathname(runtimeContextRef.current);
+      const pathDetection = detectLanguageFromPath(
+        currentPathname,
+        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);
+          }
+        }
+      }
+    } else {
+      const instanceLang = i18nInstance.language;
+      if (instanceLang && instanceLang !== prevLangRef.current) {
+        prevLangRef.current = instanceLang;
+        setLang(instanceLang);
+      }
+    }
+  }, [
+    i18nInstance,
+    localePathRedirect,
+    languages,
+    runtimeContextRef,
+    prevLangRef,
+    setLang,
+  ]);
+}

package/src/runtime/i18n/backend/config.ts

@@ -0,0 +1,10 @@
+import { deepMerge } from '../../../shared/deepMerge';
+import type { BackendOptions } from '../instance';
+
+export function mergeBackendOptions(
+  defaultOptions: BackendOptions,
+  cliOptions: BackendOptions = {},
+  userOptions?: BackendOptions,
+): BackendOptions {
+  return deepMerge(deepMerge(defaultOptions, cliOptions), userOptions ?? {});
+}

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

@@ -0,0 +1,31 @@
+export const DEFAULT_I18NEXT_BACKEND_OPTIONS = {
+  loadPath: './locales/{{lng}}/{{ns}}.json',
+  addPath: './locales/{{lng}}/{{ns}}.json',
+};
+
+function convertPath(path: string | undefined): string | undefined {
+  if (!path) {
+    return path;
+  }
+  // If it's an absolute path (starts with /), convert to relative path
+  if (path.startsWith('/')) {
+    return `.${path}`;
+  }
+  return path;
+}
+
+export function convertBackendOptions<
+  T extends { loadPath?: string; addPath?: string },
+>(options: T): T {
+  if (!options) {
+    return options;
+  }
+  const converted = { ...options };
+  if (converted.loadPath) {
+    converted.loadPath = convertPath(converted.loadPath);
+  }
+  if (converted.addPath) {
+    converted.addPath = convertPath(converted.addPath);
+  }
+  return converted;
+}

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

@@ -0,0 +1,37 @@
+export const DEFAULT_I18NEXT_BACKEND_OPTIONS = {
+  loadPath: '/locales/{{lng}}/{{ns}}.json',
+  addPath: '/locales/{{lng}}/{{ns}}.json',
+};
+
+declare global {
+  interface Window {
+    __assetPrefix__?: string;
+  }
+}
+
+function convertPath(path: string | undefined): string | undefined {
+  if (!path) {
+    return path;
+  }
+  // If it's an absolute path (starts with /), convert to relative path
+  if (path.startsWith('/')) {
+    return `${window.__assetPrefix__ || ''}${path}`;
+  }
+  return path;
+}
+
+export function convertBackendOptions<
+  T extends { loadPath?: string; addPath?: string },
+>(options: T): T {
+  if (!options) {
+    return options;
+  }
+  const converted = { ...options };
+  if (converted.loadPath) {
+    converted.loadPath = convertPath(converted.loadPath);
+  }
+  if (converted.addPath) {
+    converted.addPath = convertPath(converted.addPath);
+  }
+  return converted;
+}