chore: rename enableLocaleDetection to localePathRedirect (#7857)

Author: caohuilin

packages/runtime/plugin-i18n/src/runtime/context.tsx

@@ -10,7 +10,7 @@ export interface ModernI18nContextValue {
   // Plugin configuration for useModernI18n hook
   entryName?: string;
   languages?: string[];
-  enableLocaleDetection?: boolean;
+  localePathRedirect?: boolean;
   // Callback to update language in context
   updateLanguage?: (newLang: string) => void;
 }
@@ -33,12 +33,6 @@ export const ModernI18nProvider: FC<ModernI18nProviderProps> = ({
   );
 };
 
-export interface UseModernI18nOptions {
-  entryName?: string;
-  languages?: string[];
-  enableLocaleDetection?: boolean;
-}
-
 export interface UseModernI18nReturn {
   language: string;
   changeLanguage: (newLang: string) => Promise<void>;
@@ -86,9 +80,7 @@ const useRouterHooks = () => {
  * @param options - Optional configuration to override context settings
  * @returns Object containing i18n functionality and utilities
  */
-export const useModernI18n = (
-  options: UseModernI18nOptions = {},
-): UseModernI18nReturn => {
+export const useModernI18n = (): UseModernI18nReturn => {
   const context = useContext(ModernI18nContext);
   if (!context) {
     throw new Error('useModernI18n must be used within a ModernI18nProvider');
@@ -97,19 +89,12 @@ export const useModernI18n = (
   const {
     language: contextLanguage,
     i18nInstance,
-    entryName: contextEntryName,
-    languages: contextLanguages,
-    enableLocaleDetection: contextEnableLocaleDetection,
+    entryName,
+    languages,
+    localePathRedirect,
     updateLanguage,
   } = context;
 
-  // Merge context options with passed options (passed options take precedence)
-  const {
-    entryName = contextEntryName,
-    languages = contextLanguages || [],
-    enableLocaleDetection = contextEnableLocaleDetection || false,
-  } = options;
-
   // Get router hooks safely
   const { navigate, location, hasRouter } = useRouterHooks();
 
@@ -140,7 +125,7 @@ export const useModernI18n = (
 
         // Update URL if locale detection is enabled, we're in browser, and router is available
         if (
-          enableLocaleDetection &&
+          localePathRedirect &&
           isBrowser() &&
           hasRouter &&
           navigate &&
@@ -151,19 +136,27 @@ export const useModernI18n = (
           const relativePath = currentPath.replace(entryPath, '');
 
           // Build new path with updated language
-          const newPath = buildLocalizedUrl(relativePath, newLang, languages);
+          const newPath = buildLocalizedUrl(
+            relativePath,
+            newLang,
+            languages || [],
+          );
           const newUrl = entryPath + newPath + location.search + location.hash;
 
           // Navigate to new URL
           navigate(newUrl, { replace: true });
-        } else if (enableLocaleDetection && isBrowser() && !hasRouter) {
+        } else if (localePathRedirect && isBrowser() && !hasRouter) {
           // Fallback: use window.history API when router is not available
           const currentPath = window.location.pathname;
           const entryPath = getEntryPath(entryName);
           const relativePath = currentPath.replace(entryPath, '');
 
           // Build new path with updated language
-          const newPath = buildLocalizedUrl(relativePath, newLang, languages);
+          const newPath = buildLocalizedUrl(
+            relativePath,
+            newLang,
+            languages || [],
+          );
           const newUrl =
             entryPath + newPath + window.location.search + window.location.hash;
 
@@ -183,7 +176,7 @@ export const useModernI18n = (
     [
       i18nInstance,
       updateLanguage,
-      enableLocaleDetection,
+      localePathRedirect,
       entryName,
       languages,
       hasRouter,
@@ -195,7 +188,7 @@ export const useModernI18n = (
   // Helper function to check if a language is supported
   const isLanguageSupported = useCallback(
     (lang: string) => {
-      return languages.includes(lang);
+      return languages?.includes(lang) || false;
     },
     [languages],
   );
@@ -204,7 +197,7 @@ export const useModernI18n = (
     language: currentLanguage,
     changeLanguage,
     i18nInstance,
-    supportedLanguages: languages,
+    supportedLanguages: languages || [],
     isLanguageSupported,
   };
 };

packages/runtime/plugin-i18n/src/runtime/index.tsx

@@ -26,20 +26,19 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
     const {
       entryName,
       i18nInstance: userI18nInstance,
-      changeLanguage,
       initOptions: userInitOptions,
       localeDetection,
     } = options;
     const {
-      enable: enableLocaleDetection,
+      localePathRedirect,
       languages = [],
       fallbackLanguage = 'en',
     } = localeDetection || {};
     let I18nextProvider: React.FunctionComponent<any> | null;
 
     // Helper function to detect language from path
     const detectLanguageFromPath = (pathname: string) => {
-      if (enableLocaleDetection) {
+      if (localePathRedirect) {
         const relativePath = pathname.replace(getEntryPath(entryName), '');
         const detectedLang = getLanguageFromPath(
           relativePath,
@@ -61,7 +60,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
       }
       // Always detect language from path for consistency between SSR and client
       let initialLanguage = fallbackLanguage;
-      if (enableLocaleDetection) {
+      if (localePathRedirect) {
         if (isBrowser()) {
           // In browser, get from window.location
           initialLanguage = detectLanguageFromPath(window.location.pathname);
@@ -83,7 +82,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
       if (!isBrowser() && i18nInstance.cloneInstance) {
         i18nInstance = i18nInstance.cloneInstance();
       }
-      if (enableLocaleDetection && i18nInstance.language !== initialLanguage) {
+      if (localePathRedirect && i18nInstance.language !== initialLanguage) {
         // If instance is already initialized but language doesn't match the path, update it
         await i18nInstance.changeLanguage(initialLanguage);
       }
@@ -112,7 +111,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
 
         // Initialize language from URL on mount (only when localeDetection is enabled)
         useEffect(() => {
-          if (enableLocaleDetection) {
+          if (localePathRedirect) {
             const currentPathname = getCurrentPathname();
             const currentLang = detectLanguageFromPath(currentPathname);
             if (currentLang !== lang) {
@@ -130,7 +129,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
           i18nInstance,
           entryName,
           languages,
-          enableLocaleDetection,
+          localePathRedirect,
           updateLanguage: setLang,
         };
 

packages/runtime/plugin-i18n/src/server/index.ts

@@ -81,15 +81,15 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
           return;
         }
         const {
-          enable,
+          localePathRedirect,
           languages = [],
           fallbackLanguage = 'en',
         } = getLocaleDetectionOptions(entryName, options.localeDetection);
         const originUrlPath = route.urlPath;
         const urlPath = originUrlPath.endsWith('/')
           ? `${originUrlPath}*`
           : `${originUrlPath}/*`;
-        if (enable) {
+        if (localePathRedirect) {
           middlewares.push({
             name: 'i18n-server-middleware',
             path: urlPath,

packages/runtime/plugin-i18n/src/utils/config.ts

@@ -2,8 +2,8 @@
  * Base locale detection configuration for a single entry
  */
 export interface BaseLocaleDetectionOptions {
-  /** Whether locale detection is enabled for this entry */
-  enable?: boolean;
+  /** Whether to enable locale detection from path and automatic redirect */
+  localePathRedirect?: boolean;
   /** List of supported languages */
   languages?: string[];
   /** Fallback language when detection fails */
@@ -38,7 +38,15 @@ export const getLocaleDetectionOptions = (
 
   if (hasEntryConfig(localeDetection)) {
     const { localeDetectionByEntry, ...globalConfig } = localeDetection;
-    return localeDetectionByEntry?.[entryName] || globalConfig;
+    const entryConfig = localeDetectionByEntry?.[entryName];
+    // Merge entry-specific config with global config, entry config takes precedence
+    if (entryConfig) {
+      return {
+        ...globalConfig,
+        ...entryConfig,
+      };
+    }
+    return globalConfig;
   }
 
   return localeDetection;

pnpm-lock.yaml

@@ -6,12 +6,12 @@ export default defineConfig({
     appTools(),
     i18nPlugin({
       localeDetection: {
-        enable: true,
+        localePathRedirect: true,
         languages: ['zh', 'en'],
         fallbackLanguage: 'en',
         localeDetectionByEntry: {
           index: {
-            enable: false,
+            localePathRedirect: false,
           },
         },
       },

tests/integration/i18n/app-csr/modern.config.ts

@@ -10,7 +10,6 @@
     "react-i18next": "15.7.4",
     "@modern-js/runtime": "workspace:*",
     "@modern-js/plugin-i18n": "workspace:*",
-    "i18next-browser-languagedetector": "8.2.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },

tests/integration/i18n/app-csr/package.json

@@ -9,7 +9,7 @@ export default defineConfig({
     appTools(),
     i18nPlugin({
       localeDetection: {
-        enable: true,
+        localePathRedirect: true,
         languages: ['zh', 'en'],
         fallbackLanguage: 'en',
       },

tests/integration/i18n/app-ssr/modern.config.ts

@@ -18,7 +18,7 @@ export default defineConfig({
     appTools(),
     i18nPlugin({
       localeDetection: {
-        enable: true,
+        localePathRedirect: true,
         languages: ['zh', 'en'],
         fallbackLanguage: 'en',
       },

tests/integration/i18n/app-ssr/modern.ssg.config.ts

@@ -11,7 +11,6 @@
     "react-i18next": "15.7.4",
     "@modern-js/runtime": "workspace:*",
     "@modern-js/plugin-i18n": "workspace:*",
-    "i18next-browser-languagedetector": "8.2.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },