@bleedingdev/modern-js-plugin-i18n 3.5.0-ultramodern.30 → 3.5.0-ultramodern.31

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/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,33 @@
+import type { I18nInitOptions, LanguageDetectorOptions } from '../instance';
+
+export interface BaseLanguageDetectionOptions {
+  languages: string[];
+  fallbackLanguage: string;
+  localePathRedirect: boolean;
+  i18nextDetector: boolean;
+  detection?: LanguageDetectorOptions;
+  userInitOptions?: I18nInitOptions;
+  mergedBackend?: any;
+}
+
+export interface LanguageDetectionOptions extends BaseLanguageDetectionOptions {
+  pathname: string;
+  ssrContext?: any;
+}
+
+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?: any;
+  mergeBackend?: any;
+}

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/linkHelpers.ts

@@ -0,0 +1,174 @@
+const warnedTargets = new Set<string>();
+
+export const warnOnce = (key: string, message: string) => {
+  if (process.env.NODE_ENV !== 'development' || warnedTargets.has(key)) {
+    return;
+  }
+  warnedTargets.add(key);
+  console.warn(message);
+};
+
+export type LinkParams = Record<string, string | number | undefined>;
+type NormalizedSearchValue = string | string[];
+
+/**
+ * Interpolate `$param`, `:param`, optional (`{-$param}` / `:param?`) and splat
+ * (`$` / `*`) segments with concrete values before localization, so
+ * pattern-mapped slugs localize correctly.
+ */
+export const interpolateRouteParams = (
+  pathname: string,
+  params?: LinkParams,
+): string => {
+  if (!/[$:*{]/.test(pathname)) {
+    return pathname;
+  }
+
+  const resolveParam = (name: string): string | undefined => {
+    const value = params?.[name];
+    return value === undefined ? undefined : String(value);
+  };
+
+  const segments = pathname
+    .split('/')
+    .map(segment => {
+      if (!segment) {
+        return segment;
+      }
+
+      if (segment.startsWith('{-$') && segment.endsWith('}')) {
+        const value = resolveParam(segment.slice(3, -1));
+        return value === undefined ? null : encodeURIComponent(value);
+      }
+
+      if (segment === '$' || segment === '*') {
+        const value = resolveParam('_splat') ?? resolveParam('*');
+        return value === undefined
+          ? null
+          : value.split('/').map(encodeURIComponent).join('/');
+      }
+
+      if (segment.startsWith('$')) {
+        const value = resolveParam(segment.slice(1));
+        if (value === undefined) {
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${segment.slice(1)}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      if (segment.startsWith(':')) {
+        const optional = segment.endsWith('?');
+        const name = segment.slice(1, optional ? -1 : undefined);
+        const value = resolveParam(name);
+        if (value === undefined) {
+          if (optional) {
+            return null;
+          }
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${name}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      return segment;
+    })
+    .filter(segment => segment !== null);
+
+  return segments.join('/') || '/';
+};
+
+export const normalizeSearch = (
+  search: string | Record<string, unknown> | undefined,
+  searchFromTo: string,
+): {
+  searchString: string;
+  searchObject: Record<string, NormalizedSearchValue> | undefined;
+} => {
+  if (search && typeof search === 'object') {
+    const searchObject: Record<string, NormalizedSearchValue> = {};
+    const params = new URLSearchParams();
+
+    for (const [key, value] of Object.entries(search)) {
+      if (value === undefined || value === null) {
+        continue;
+      }
+
+      if (Array.isArray(value)) {
+        const values = value
+          .filter(item => item !== undefined && item !== null)
+          .map(String);
+        if (values.length === 0) {
+          continue;
+        }
+        searchObject[key] = values;
+        for (const item of values) {
+          params.append(key, item);
+        }
+        continue;
+      }
+
+      const stringValue = String(value);
+      searchObject[key] = stringValue;
+      params.append(key, stringValue);
+    }
+
+    const serialized = params.toString();
+    return {
+      searchString: serialized ? `?${serialized}` : '',
+      searchObject:
+        Object.keys(searchObject).length > 0 ? searchObject : undefined,
+    };
+  }
+
+  const raw = typeof search === 'string' ? search : searchFromTo;
+  if (!raw) {
+    return { searchString: '', searchObject: undefined };
+  }
+
+  const searchString = raw.startsWith('?') ? raw : `?${raw}`;
+  const searchObject: Record<string, NormalizedSearchValue> = {};
+  new URLSearchParams(searchString).forEach((value, key) => {
+    const existing = searchObject[key];
+    if (existing === undefined) {
+      searchObject[key] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      searchObject[key] = [existing, value];
+    }
+  });
+
+  return { searchString, searchObject };
+};
+
+type ActivePropsResult<TActiveProps extends Record<string, unknown>> = Record<
+  string,
+  unknown
+> &
+  Partial<TActiveProps>;
+
+export const splitActiveProps = <TActiveProps extends Record<string, unknown>>(
+  active: boolean,
+  activeProps?: TActiveProps,
+): ActivePropsResult<TActiveProps> => {
+  if (!active || !activeProps) {
+    return {};
+  }
+  return activeProps;
+};
+
+export const mergeClassNames = (
+  ...values: Array<unknown>
+): string | undefined => {
+  const classNames = values.filter(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  );
+  return classNames.length > 0 ? classNames.join(' ') : undefined;
+};

package/src/runtime/pluginSetup.ts

@@ -0,0 +1,189 @@
+import { isBrowser } from '@modern-js/runtime';
+import type { TInternalRuntimeContext } from '@modern-js/runtime/internal';
+import { merge } from '@modern-js/runtime-utils/merge';
+import type {
+  BaseBackendOptions,
+  BaseLocaleDetectionOptions,
+} from '../shared/type';
+import type { I18nInitOptions, I18nInstance } from './i18n';
+import { getI18nInstance } from './i18n';
+import { mergeBackendOptions } from './i18n/backend';
+import {
+  detectLanguageWithPriority,
+  exportServerLngToWindow,
+  mergeDetectionOptions,
+} from './i18n/detection';
+import { useI18nextLanguageDetector } from './i18n/detection/middleware';
+import type { ReactI18nextIntegration } from './reactI18next';
+import { getPathname } from './utils';
+
+type I18nLifecycleHelpers = {
+  useI18nextBackend: typeof import('./i18n/backend/middleware')['useI18nextBackend'];
+  changeI18nLanguage: typeof import('./i18n/utils')['changeI18nLanguage'];
+  ensureLanguageMatch: typeof import('./i18n/utils')['ensureLanguageMatch'];
+  initializeI18nInstance: typeof import('./i18n/utils')['initializeI18nInstance'];
+  setupClonedInstance: typeof import('./i18n/utils')['setupClonedInstance'];
+};
+
+let i18nLifecycleHelpersPromise: Promise<I18nLifecycleHelpers> | undefined;
+
+function loadI18nLifecycleHelpers(): Promise<I18nLifecycleHelpers> {
+  i18nLifecycleHelpersPromise ??= Promise.all([
+    import('./i18n/backend/middleware'),
+    import('./i18n/utils'),
+  ]).then(([backendMiddleware, utils]) => ({
+    useI18nextBackend: backendMiddleware.useI18nextBackend,
+    changeI18nLanguage: utils.changeI18nLanguage,
+    ensureLanguageMatch: utils.ensureLanguageMatch,
+    initializeI18nInstance: utils.initializeI18nInstance,
+    setupClonedInstance: utils.setupClonedInstance,
+  }));
+
+  return i18nLifecycleHelpersPromise;
+}
+
+interface RuntimeConfigWithI18n {
+  i18n?: {
+    initOptions?: I18nInitOptions;
+  };
+}
+
+interface I18nRuntimeApi {
+  getRuntimeConfig: () => RuntimeConfigWithI18n;
+}
+
+export interface RuntimeContextWithI18n extends TInternalRuntimeContext {
+  i18nInstance?: I18nInstance;
+  changeLanguage?: (lang: string) => Promise<void>;
+}
+
+export interface SetupI18nBeforeRenderOptions {
+  api: I18nRuntimeApi;
+  userI18nInstance?: I18nInstance;
+  initOptions?: I18nInitOptions;
+  backend?: BaseBackendOptions;
+  backendEnabled: boolean;
+  i18nextDetector: boolean;
+  detection?: BaseLocaleDetectionOptions['detection'];
+  localePathRedirect: boolean;
+  languages: string[];
+  fallbackLanguage: string;
+  resolveReactI18nextIntegration: () => Promise<ReactI18nextIntegration | null>;
+  setI18nextProvider: (
+    provider: ReactI18nextIntegration['I18nextProvider'],
+  ) => void;
+}
+
+export async function setupI18nBeforeRender(
+  context: RuntimeContextWithI18n,
+  options: SetupI18nBeforeRenderOptions,
+): Promise<I18nInstance> {
+  const {
+    api,
+    userI18nInstance,
+    initOptions,
+    backend,
+    backendEnabled,
+    i18nextDetector,
+    detection,
+    localePathRedirect,
+    languages,
+    fallbackLanguage,
+    resolveReactI18nextIntegration,
+    setI18nextProvider,
+  } = options;
+  const {
+    useI18nextBackend,
+    changeI18nLanguage,
+    ensureLanguageMatch,
+    initializeI18nInstance,
+    setupClonedInstance,
+  } = await loadI18nLifecycleHelpers();
+  let i18nInstance = await getI18nInstance(userI18nInstance);
+  const { i18n: otherConfig } = api.getRuntimeConfig();
+  const { initOptions: otherInitOptions } = otherConfig || {};
+  const userInitOptions = merge(otherInitOptions || {}, initOptions || {});
+
+  const reactI18nextIntegration = await resolveReactI18nextIntegration();
+  setI18nextProvider(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 because detection may init.
+  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;
+
+  // Add changeLanguage method to context for other runtime plugins to use.
+  context.changeLanguage = async (newLang: string) => {
+    await changeI18nLanguage(i18nInstance, newLang, {
+      detectionOptions: mergedDetection,
+    });
+  };
+
+  return i18nInstance;
+}