@bleedingdev/modern-js-plugin-i18n 3.5.0-ultramodern.4 → 3.5.0-ultramodern.41

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

@@ -0,0 +1,64 @@
+/**
+ * Normalize language code (e.g., 'zh-CN' -> 'zh', 'en-US' -> 'en')
+ */
+const normalizeLanguageCode = (language: string): string => {
+  if (!language) {
+    return language;
+  }
+  // Extract base language code (before hyphen)
+  const baseLang = language.split('-')[0];
+  return baseLang;
+};
+
+/**
+ * Check if a language is supported
+ * Also checks the base language code (e.g., 'zh-CN' matches 'zh')
+ */
+export const isLanguageSupported = (
+  language: string | undefined,
+  supportedLanguages: string[],
+): boolean => {
+  if (!language) {
+    return false;
+  }
+  if (supportedLanguages.length === 0) {
+    return true;
+  }
+  // Check exact match first
+  if (supportedLanguages.includes(language)) {
+    return true;
+  }
+  // Check base language code match (e.g., 'zh-CN' matches 'zh')
+  const baseLang = normalizeLanguageCode(language);
+  if (baseLang !== language && supportedLanguages.includes(baseLang)) {
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Get the supported language that matches the given language
+ * Returns the exact match if available, otherwise returns the base language code match
+ * Returns undefined if no match is found
+ */
+export const getSupportedLanguage = (
+  language: string | undefined,
+  supportedLanguages: string[],
+): string | undefined => {
+  if (!language) {
+    return undefined;
+  }
+  if (supportedLanguages.length === 0) {
+    return language;
+  }
+  // Check exact match first
+  if (supportedLanguages.includes(language)) {
+    return language;
+  }
+  // Check base language code match (e.g., 'zh-CN' matches 'zh')
+  const baseLang = normalizeLanguageCode(language);
+  if (baseLang !== language && supportedLanguages.includes(baseLang)) {
+    return baseLang;
+  }
+  return undefined;
+};

package/src/runtime/i18n/detection/middleware.node.ts

@@ -1,10 +1,22 @@
 import { LanguageDetector } from 'i18next-http-middleware';
-import type { I18nInstance } from '../instance';
+import type { I18nInstance, LanguageDetectorOptions } from '../instance';
+
+type HttpDetectorInit = (
+  services: NonNullable<I18nInstance['services']>,
+  options?: unknown,
+  allOptions?: unknown,
+) => void;
+
+type HttpDetectorDetect = (
+  request: unknown,
+  response: unknown,
+  detectionOrder?: unknown,
+) => string | string[] | undefined;
 
 export const cacheUserLanguage = (
   _i18nInstance: I18nInstance,
   _language: string,
-  _detectionOptions?: any,
+  _detectionOptions?: unknown,
 ): void => {
   return;
 };
@@ -14,7 +26,7 @@ export const cacheUserLanguage = (
  * Not available in Node.js environment, returns undefined
  */
 export const readLanguageFromStorage = (
-  _detectionOptions?: any,
+  _detectionOptions?: LanguageDetectorOptions,
 ): string | undefined => {
   // In Node.js environment, storage-based detection is not available
   return undefined;
@@ -36,8 +48,8 @@ export const useI18nextLanguageDetector = (i18nInstance: I18nInstance) => {
  */
 export const detectLanguage = (
   i18nInstance: I18nInstance,
-  request?: any,
-  detectionOptions?: any,
+  request?: unknown,
+  detectionOptions?: LanguageDetectorOptions,
 ): string | undefined => {
   if (!request) {
     return undefined;
@@ -65,9 +77,16 @@ export const detectLanguage = (
       const optionsToUse = detectionOptions
         ? { ...i18nInstance.options, detection: detectionOptions }
         : i18nInstance.options;
-      manualDetector.init(i18nInstance.services, optionsToUse as any);
+      (manualDetector.init as unknown as HttpDetectorInit)(
+        i18nInstance.services,
+        optionsToUse,
+      );
 
-      const result = (manualDetector.detect as any)(request, {}, undefined);
+      const result = (manualDetector.detect as unknown as HttpDetectorDetect)(
+        request,
+        {},
+        undefined,
+      );
       if (typeof result === 'string') {
         return result;
       }

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

@@ -1,8 +1,10 @@
 import { isBrowser } from '@modern-js/runtime';
 import LanguageDetector from 'i18next-browser-languagedetector';
-import type { I18nInstance } from '../instance';
+import type { I18nInstance, LanguageDetectorOptions } from '../instance';
 import { getActualI18nextInstance, isI18nWrapperInstance } from '../instance';
 
+type BrowserDetectorInitOptions = Parameters<LanguageDetector['init']>[1];
+
 /**
  * Register LanguageDetector plugin to i18n instance
  * Must be called before init() to properly register the detector
@@ -27,7 +29,7 @@ export const useI18nextLanguageDetector = (i18nInstance: I18nInstance) => {
  * Fallback when detector is not available in services
  */
 export const readLanguageFromStorage = (
-  detectionOptions?: any,
+  detectionOptions?: LanguageDetectorOptions,
 ): string | undefined => {
   try {
     const options = detectionOptions || {};
@@ -112,8 +114,8 @@ export const readLanguageFromStorage = (
  */
 export const detectLanguage = (
   i18nInstance: I18nInstance,
-  _request?: any,
-  detectionOptions?: any,
+  _request?: unknown,
+  detectionOptions?: LanguageDetectorOptions,
 ): string | undefined => {
   try {
     // For wrapper instances, get the underlying i18next instance
@@ -160,7 +162,10 @@ export const detectLanguage = (
         const mergedOptions = detectionOptions
           ? { ...optionsToUse, detection: detectionOptions }
           : optionsToUse;
-        manualDetector.init(servicesToUse, mergedOptions as any);
+        manualDetector.init(
+          servicesToUse,
+          mergedOptions as unknown as BrowserDetectorInitOptions,
+        );
 
         const result = manualDetector.detect();
         if (typeof result === 'string') {
@@ -186,7 +191,7 @@ export const detectLanguage = (
 export const cacheUserLanguage = (
   i18nInstance: I18nInstance,
   language: string,
-  detectionOptions?: any,
+  detectionOptions?: unknown,
 ): void => {
   if (typeof window === 'undefined') {
     return;
@@ -231,7 +236,10 @@ export const cacheUserLanguage = (
           : optionsToUse;
 
         const manualDetector = new LanguageDetector();
-        manualDetector.init(servicesToUse, mergedOptions as any);
+        manualDetector.init(
+          servicesToUse,
+          mergedOptions as unknown as BrowserDetectorInitOptions,
+        );
 
         if (typeof manualDetector.cacheUserLanguage === 'function') {
           manualDetector.cacheUserLanguage(language);

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

@@ -0,0 +1,41 @@
+import { detectLanguageFromPath } from '../../utils';
+
+/**
+ * Priority 2: Detect language from URL path
+ * Only returns a language if the path explicitly contains a language prefix
+ */
+export const detectLanguageFromPathPriority = (
+  pathname: string,
+  languages: string[],
+  localePathRedirect: boolean,
+): string | undefined => {
+  if (!localePathRedirect) {
+    return undefined;
+  }
+
+  // If no languages are configured, cannot detect from path
+  if (!languages || languages.length === 0) {
+    return undefined;
+  }
+
+  // If pathname is empty or invalid, no language in path
+  if (!pathname || pathname.trim() === '') {
+    return undefined;
+  }
+
+  try {
+    const pathDetection = detectLanguageFromPath(
+      pathname,
+      languages,
+      localePathRedirect,
+    );
+    // Only return language if explicitly detected in path
+    if (pathDetection.detected === true && pathDetection.language) {
+      return pathDetection.language;
+    }
+  } catch (error) {
+    // Silently ignore errors, return undefined
+  }
+
+  return undefined;
+};

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

@@ -0,0 +1,82 @@
+import { type I18nInstance, isI18nWrapperInstance } from '../instance';
+
+import { detectLanguageFromI18nextDetector } from './detector';
+
+import { mergeDetectionOptions } from './initOptions';
+import { readLanguageFromStorage } from './middleware';
+import { detectLanguageFromPathPriority } from './path';
+import { detectLanguageFromSSR } from './ssr';
+
+import type {
+  LanguageDetectionOptions,
+  LanguageDetectionResult,
+} from './types';
+
+/**
+ * Detect language with priority:
+ * Priority 1: Path detection
+ * Priority 2: SSR data (try window._SSR_DATA first, works for both SSR and CSR)
+ * Priority 3: i18next detector (reads from cookie/localStorage)
+ * Priority 4: User config language or fallback
+ */
+export const detectLanguageWithPriority = async (
+  i18nInstance: I18nInstance,
+  options: LanguageDetectionOptions,
+): Promise<LanguageDetectionResult> => {
+  const {
+    languages,
+    fallbackLanguage,
+    localePathRedirect,
+    i18nextDetector,
+    detection,
+    userInitOptions,
+    pathname,
+    ssrContext,
+  } = options;
+
+  let detectedLanguage: string | undefined;
+
+  // Priority 1: Path detection. Explicit URL locale must win over stale
+  // hydration data after client-side navigation.
+  detectedLanguage = detectLanguageFromPathPriority(
+    pathname,
+    languages,
+    localePathRedirect,
+  );
+
+  // Priority 2: Try SSR data when the current path has no explicit locale.
+  if (!detectedLanguage) {
+    detectedLanguage = detectLanguageFromSSR(languages);
+  }
+
+  // Priority 3: i18next detector (reads from cookie/localStorage)
+  if (!detectedLanguage && i18nextDetector) {
+    if (isI18nWrapperInstance(i18nInstance)) {
+      detectedLanguage = readLanguageFromStorage(
+        mergeDetectionOptions(
+          i18nextDetector,
+          detection,
+          localePathRedirect,
+          userInitOptions,
+        ),
+      );
+    } else {
+      detectedLanguage = await detectLanguageFromI18nextDetector(i18nInstance, {
+        languages,
+        fallbackLanguage,
+        localePathRedirect,
+        i18nextDetector,
+        detection,
+        userInitOptions,
+        mergedBackend: options.mergedBackend,
+        ssrContext,
+      });
+    }
+  }
+
+  // Priority 4: Use user config language or fallback
+  const finalLanguage =
+    detectedLanguage || userInitOptions?.lng || fallbackLanguage;
+
+  return { detectedLanguage, finalLanguage };
+};

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

@@ -0,0 +1,47 @@
+import { isBrowser, type TRuntimeContext } from '@modern-js/runtime';
+import { getSupportedLanguage } from './language';
+
+export function exportServerLngToWindow(context: TRuntimeContext, lng: string) {
+  context.__i18nData__ = { lng };
+}
+
+export const getLanguageFromSSRData = (window: Window): string | undefined => {
+  try {
+    const ssrData = (window as any)._SSR_DATA;
+    // Check if SSR data exists and has valid structure
+    if (!ssrData || !ssrData.data || !ssrData.data.i18nData) {
+      return undefined;
+    }
+    const lng = ssrData.data.i18nData.lng;
+    // Return language only if it's a non-empty string
+    return typeof lng === 'string' && lng.trim() !== '' ? lng : undefined;
+  } catch (error) {
+    // If accessing window._SSR_DATA throws an error, return undefined
+    return undefined;
+  }
+};
+
+/**
+ * Priority 1: Detect language from SSR data
+ * Try to get language from window._SSR_DATA first (both SSR and CSR projects)
+ * Returns undefined if SSR data is not available or invalid
+ */
+export const detectLanguageFromSSR = (
+  languages: string[],
+): string | undefined => {
+  if (!isBrowser()) {
+    return undefined;
+  }
+
+  try {
+    const ssrLanguage = getLanguageFromSSRData(window);
+    const supportedLanguage = getSupportedLanguage(ssrLanguage, languages);
+    if (supportedLanguage) {
+      return supportedLanguage;
+    }
+  } catch (error) {
+    // Silently ignore errors
+  }
+
+  return undefined;
+};

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

@@ -0,0 +1,41 @@
+import type {
+  BackendOptions,
+  I18nInitOptions,
+  LanguageDetectorOptions,
+} from '../instance';
+
+export interface LanguageDetectionSsrContext {
+  request?: unknown;
+}
+
+export interface BaseLanguageDetectionOptions {
+  languages: string[];
+  fallbackLanguage: string;
+  localePathRedirect: boolean;
+  i18nextDetector: boolean;
+  detection?: LanguageDetectorOptions;
+  userInitOptions?: I18nInitOptions;
+  mergedBackend?: BackendOptions;
+}
+
+export interface LanguageDetectionOptions extends BaseLanguageDetectionOptions {
+  pathname: string;
+  ssrContext?: LanguageDetectionSsrContext;
+}
+
+export interface LanguageDetectionResult {
+  detectedLanguage?: string;
+  finalLanguage: string;
+}
+
+/**
+ * Options for building i18n init options
+ */
+export interface BuildInitOptionsParams {
+  finalLanguage: string;
+  fallbackLanguage: string;
+  languages: string[];
+  userInitOptions?: I18nInitOptions;
+  mergedDetection?: LanguageDetectorOptions;
+  mergeBackend?: BackendOptions;
+}

package/src/runtime/i18n/instance.ts

@@ -1,9 +1,9 @@
 import type { BaseBackendOptions } from '../../shared/type';
 
-export interface I18nResourceStore {
+interface I18nResourceStore {
   data?: {
     [language: string]: {
-      [namespace: string]: string | { [key: string]: any };
+      [namespace: string]: ResourceValue;
     };
   };
   addResourceBundle?: (
@@ -15,30 +15,49 @@ export interface I18nResourceStore {
   ) => void;
 }
 
-export function isI18nWrapperInstance(obj: any): boolean {
+type I18nWrapperInstance = I18nInstance & {
+  i18nInstance: {
+    instance: I18nInstance;
+  };
+};
+
+export function isI18nWrapperInstance(
+  obj: unknown,
+): obj is I18nWrapperInstance {
   if (!obj || typeof obj !== 'object') {
     return false;
   }
-  if (!obj.i18nInstance || typeof obj.i18nInstance !== 'object') {
+  const candidate = obj as {
+    i18nInstance?: unknown;
+    init?: unknown;
+    use?: unknown;
+  };
+  if (!candidate.i18nInstance || typeof candidate.i18nInstance !== 'object') {
     return false;
   }
-  if (!obj.i18nInstance.instance) {
+  const wrapper = candidate.i18nInstance as { instance?: unknown };
+  if (!wrapper.instance) {
     return false;
   }
-  if (typeof obj.init !== 'function' || typeof obj.use !== 'function') {
+  if (
+    typeof candidate.init !== 'function' ||
+    typeof candidate.use !== 'function'
+  ) {
     return false;
   }
   return true;
 }
 
-export function getI18nWrapperI18nextInstance(wrapperInstance: any): any {
+function getI18nWrapperI18nextInstance(
+  wrapperInstance: unknown,
+): I18nInstance | null {
   if (isI18nWrapperInstance(wrapperInstance)) {
     return wrapperInstance.i18nInstance?.instance;
   }
   return null;
 }
 
-export function getActualI18nextInstance(instance: I18nInstance | any): any {
+export function getActualI18nextInstance(instance: I18nInstance): I18nInstance {
   if (isI18nWrapperInstance(instance)) {
     const i18nextInstance = getI18nWrapperI18nextInstance(instance);
     return i18nextInstance || instance;
@@ -50,39 +69,42 @@ export interface I18nInstance {
   language: string;
   isInitialized?: boolean;
   init: {
-    (callback?: (error: any, t: any) => void): Promise<any>;
+    (callback?: (error: unknown, t: unknown) => void): Promise<unknown>;
     (
       options: I18nInitOptions,
-      callback?: (error: any, t: any) => void,
-    ): Promise<any>;
+      callback?: (error: unknown, t: unknown) => void,
+    ): Promise<unknown>;
   };
   changeLanguage?: (
     lng?: string,
-    callback?: (error: any, t: any) => void,
-  ) => Promise<any>;
+    callback?: (error: unknown, t: unknown) => void,
+  ) => Promise<unknown>;
   setLang?: (lang: string) => void | Promise<void>;
-  use: (plugin: any) => void;
+  use: (plugin: unknown) => void;
   createInstance?: (options?: I18nInitOptions) => I18nInstance;
   cloneInstance?: () => I18nInstance; // ssr need
   // i18next store (may not be in type definition but exists at runtime)
   store?: I18nResourceStore;
-  emit?: (event: string, ...args: any[]) => void;
+  emit?: (event: string, ...args: unknown[]) => void;
   reloadResources?: (language?: string, namespace?: string) => Promise<void>;
   services?: {
     languageDetector?: {
-      detect: (request?: any, options?: any) => string | string[] | undefined;
-      [key: string]: any;
+      detect: (
+        request?: unknown,
+        options?: unknown,
+      ) => string | string[] | undefined;
+      [key: string]: unknown;
     };
     resourceStore?: I18nResourceStore;
-    backend?: any; // Backend instance (e.g., SdkBackend)
-    [key: string]: any;
+    backend?: unknown; // Backend instance (e.g., SdkBackend)
+    [key: string]: unknown;
   };
   // i18next instance options (available after initialization)
   options?: {
     backend?: BackendOptions;
-    [key: string]: any;
+    [key: string]: unknown;
   };
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 type LanguageDetectorOrder = string[];
@@ -101,12 +123,12 @@ export interface LanguageDetectorOptions {
 }
 
 export interface BackendOptions extends Omit<BaseBackendOptions, 'enabled'> {
-  parse?: (data: string) => any;
-  stringify?: (data: any) => string;
+  parse?: (data: string) => unknown;
+  stringify?: (data: unknown) => string;
   [key: string]: any;
 }
 
-export type ResourceValue = string | { [key: string]: ResourceValue };
+type ResourceValue = string | { [key: string]: ResourceValue };
 
 export interface Resources {
   [lng: string]: {
@@ -126,15 +148,15 @@ export type I18nInitOptions = {
   defaultNS?: string | string[];
   interpolation?: {
     escapeValue?: boolean;
-    [key: string]: any;
+    [key: string]: unknown;
   };
   react?: {
     useSuspense?: boolean;
-    [key: string]: any;
+    [key: string]: unknown;
   };
 };
 
-export function isI18nInstance(obj: any): obj is I18nInstance {
+export function isI18nInstance(obj: unknown): obj is I18nInstance {
   if (!obj || typeof obj !== 'object') {
     return false;
   }
@@ -143,7 +165,10 @@ export function isI18nInstance(obj: any): obj is I18nInstance {
     return true;
   }
 
-  return typeof obj.init === 'function' && typeof obj.use === 'function';
+  const candidate = obj as { init?: unknown; use?: unknown };
+  return (
+    typeof candidate.init === 'function' && typeof candidate.use === 'function'
+  );
 }
 
 async function tryImportI18next(): Promise<I18nInstance | null> {
@@ -170,8 +195,8 @@ async function createI18nextInstance(): Promise<I18nInstance | null> {
 }
 
 export function getI18nextInstanceForProvider(
-  instance: I18nInstance | any,
-): any {
+  instance: I18nInstance,
+): I18nInstance {
   if (isI18nWrapperInstance(instance)) {
     const i18nextInstance = getI18nWrapperI18nextInstance(instance);
     if (i18nextInstance) {
@@ -183,7 +208,7 @@ export function getI18nextInstanceForProvider(
 }
 
 export async function getI18nInstance(
-  userInstance?: I18nInstance | any,
+  userInstance?: unknown,
 ): Promise<I18nInstance> {
   if (userInstance) {
     if (isI18nWrapperInstance(userInstance)) {

package/src/runtime/i18n/react-i18next.ts

@@ -1,12 +1,7 @@
-import type React from 'react';
+import type { ReactI18nextIntegration } from '../reactI18next';
 
 type ReactI18nextModule = typeof import('react-i18next');
 
-interface ReactI18nextIntegration {
-  I18nextProvider: React.ComponentType<any> | null;
-  initReactI18next: any | null;
-}
-
 async function tryImportReactI18next(): Promise<ReactI18nextModule | null> {
   try {
     return (await import('react-i18next')) as ReactI18nextModule;

package/src/runtime/i18n/utils.ts

@@ -11,7 +11,16 @@ import {
   isI18nWrapperInstance,
 } from './instance';
 
-export function assertI18nInstance(obj: any): asserts obj is I18nInstance {
+type MergedBackendOptions = NonNullable<I18nInitOptions['backend']> & {
+  _useChainedBackend?: boolean;
+  _chainedBackendConfig?: {
+    backendOptions: Array<Record<string, unknown>>;
+  };
+  backends?: unknown[];
+  backendOptions?: unknown;
+};
+
+export function assertI18nInstance(obj: unknown): asserts obj is I18nInstance {
   if (!isI18nInstance(obj)) {
     throw new Error('Object does not implement I18nInstance interface');
   }
@@ -24,8 +33,8 @@ export const buildInitOptions = async (
   finalLanguage: string,
   fallbackLanguage: string,
   languages: string[],
-  mergedDetection: any,
-  mergedBackend: any,
+  mergedDetection: I18nInitOptions['detection'],
+  mergedBackend: MergedBackendOptions | undefined,
   userInitOptions?: I18nInitOptions,
   useSuspense?: boolean,
   i18nInstance?: I18nInstance,
@@ -84,8 +93,8 @@ export const buildInitOptions = async (
     if (isChainedBackend && mergedBackend._chainedBackendConfig) {
       // Try to get backend classes from i18nInstance.options.backend.backends first
       // This avoids importing fs-backend in browser environment
-      let HttpBackend: any;
-      let SdkBackendClass: any;
+      let HttpBackend: unknown;
+      let SdkBackendClass: unknown;
 
       if (
         i18nInstance?.options?.backend?.backends &&
@@ -148,7 +157,7 @@ export const changeI18nLanguage = async (
   i18nInstance: I18nInstance,
   newLang: string,
   options?: {
-    detectionOptions?: any;
+    detectionOptions?: I18nInitOptions['detection'];
   },
 ): Promise<void> => {
   if (!newLang || typeof newLang !== 'string') {
@@ -179,8 +188,8 @@ export const initializeI18nInstance = async (
   finalLanguage: string,
   fallbackLanguage: string,
   languages: string[],
-  mergedDetection: any,
-  mergedBackend: any,
+  mergedDetection: I18nInitOptions['detection'],
+  mergedBackend: MergedBackendOptions | undefined,
   userInitOptions?: I18nInitOptions,
   useSuspense?: boolean,
 ): Promise<void> => {
@@ -265,7 +274,7 @@ export const setupClonedInstance = async (
   backendEnabled: boolean,
   backend: BaseBackendOptions | undefined,
   i18nextDetector: boolean,
-  detection: any,
+  detection: I18nInitOptions['detection'],
   localePathRedirect: boolean,
   userInitOptions: I18nInitOptions | undefined,
 ): Promise<void> => {