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

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>;
+}
+
+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;
+}

package/src/runtime/providerComposition.tsx

@@ -0,0 +1,144 @@
+import { RuntimeContext } from '@modern-js/runtime';
+import { Helmet } from '@modern-js/runtime/head';
+import type React from 'react';
+import { useContext, useEffect, useMemo, useRef, useState } from 'react';
+import type { BaseLocaleDetectionOptions } from '../shared/type';
+import { ModernI18nProvider } from './context';
+import {
+  createContextValue,
+  useClientSideRedirect,
+  useLanguageSync,
+  useSdkResourcesLoader,
+} from './hooks';
+import type { I18nInstance } from './i18n';
+import { getI18nextInstanceForProvider } from './i18n/instance';
+import type { RuntimeContextWithI18n } from './pluginSetup';
+
+interface I18nRootWrapperOptions {
+  entryName?: string;
+  htmlLangAttr: boolean;
+  localePathRedirect: boolean;
+  languages: string[];
+  fallbackLanguage: string;
+  ignoreRedirectRoutes?: BaseLocaleDetectionOptions['ignoreRedirectRoutes'];
+  localisedUrls?: BaseLocaleDetectionOptions['localisedUrls'];
+  getLatestI18nInstance: () => I18nInstance | undefined;
+  getI18nextProvider: () => React.ComponentType<any> | null | undefined;
+}
+
+export const createI18nRootWrapper =
+  (options: I18nRootWrapperOptions) => (App: React.ComponentType<any>) => {
+    return (props: Record<string, unknown>) => {
+      const {
+        entryName,
+        htmlLangAttr,
+        localePathRedirect,
+        languages,
+        fallbackLanguage,
+        ignoreRedirectRoutes,
+        localisedUrls,
+        getLatestI18nInstance,
+        getI18nextProvider,
+      } = options;
+      const runtimeContext = useContext(
+        RuntimeContext,
+      ) as RuntimeContextWithI18n;
+      const i18nInstance =
+        runtimeContext.i18nInstance || getLatestI18nInstance();
+      const initialLang = useMemo(
+        () => i18nInstance?.language || fallbackLanguage,
+        [i18nInstance?.language, fallbackLanguage],
+      );
+      const [lang, setLang] = useState(initialLang);
+      const [forceUpdate, setForceUpdate] = useState(0);
+      const prevLangRef = useRef(lang);
+      const runtimeContextRef = useRef(runtimeContext);
+      runtimeContextRef.current = runtimeContext;
+
+      useEffect(() => {
+        if (i18nInstance?.language) {
+          const translator = (i18nInstance as any).translator;
+          if (translator) {
+            translator.language = i18nInstance.language;
+          }
+        }
+      }, [i18nInstance?.language]);
+
+      useEffect(() => {
+        prevLangRef.current = lang;
+      }, [lang]);
+
+      useSdkResourcesLoader(i18nInstance, setForceUpdate);
+      useLanguageSync(
+        i18nInstance,
+        localePathRedirect,
+        languages,
+        runtimeContextRef,
+        prevLangRef,
+        setLang,
+      );
+
+      // Handle client-side redirect for static deployments.
+      useClientSideRedirect(
+        i18nInstance,
+        localePathRedirect,
+        languages,
+        fallbackLanguage,
+        ignoreRedirectRoutes,
+        localisedUrls,
+      );
+
+      const contextValue = useMemo(
+        () =>
+          createContextValue(
+            lang,
+            i18nInstance,
+            entryName,
+            languages,
+            localePathRedirect,
+            ignoreRedirectRoutes,
+            localisedUrls,
+            setLang,
+          ),
+        [
+          lang,
+          i18nInstance,
+          entryName,
+          languages,
+          localePathRedirect,
+          ignoreRedirectRoutes,
+          localisedUrls,
+          forceUpdate,
+        ],
+      );
+
+      const children = (props as React.PropsWithChildren).children;
+      let appContent: React.ReactNode = App ? (
+        <App {...props}>{children}</App>
+      ) : (
+        children
+      );
+
+      if (i18nInstance) {
+        const I18nextProvider = getI18nextProvider();
+        if (I18nextProvider) {
+          const i18nextInstanceForProvider =
+            getI18nextInstanceForProvider(i18nInstance);
+          appContent = (
+            <I18nextProvider i18n={i18nextInstanceForProvider}>
+              {appContent}
+            </I18nextProvider>
+          );
+        }
+      }
+
+      return (
+        <>
+          {Boolean(htmlLangAttr) && <Helmet htmlAttributes={{ lang }} />}
+          <ModernI18nProvider value={contextValue}>
+            {appContent}
+          </ModernI18nProvider>
+        </>
+      );
+    };
+  };

package/src/runtime/reactI18next.ts

@@ -0,0 +1,20 @@
+import type React from 'react';
+
+export interface ReactI18nextIntegration {
+  I18nextProvider: React.ComponentType<any> | null;
+  initReactI18next: any | null;
+}
+
+export type LoadReactI18nextIntegration =
+  () => Promise<ReactI18nextIntegration | null>;
+
+export const resolveReactI18nextIntegration = async (
+  reactI18next: boolean,
+  loadReactI18nextIntegration?: LoadReactI18nextIntegration,
+): Promise<ReactI18nextIntegration | null> => {
+  if (!reactI18next) {
+    return null;
+  }
+
+  return loadReactI18nextIntegration?.() ?? null;
+};

package/src/runtime/routerAdapter.tsx

@@ -15,31 +15,31 @@ import {
 import type React from 'react';
 import { useCallback, useContext, useEffect, useState } from 'react';
 
-export type I18nRouterFramework = 'react-router' | 'tanstack' | string;
+type I18nRouterFramework = 'react-router' | 'tanstack' | string;
 
-export interface I18nRouterLocation {
+interface I18nRouterLocation {
   pathname: string;
   search: string;
   hash: string;
 }
 
-export interface I18nRouterNavigateOptions {
+interface I18nRouterNavigateOptions {
   replace?: boolean;
   state?: unknown;
 }
 
-export type I18nRouterNavigate = (
+type I18nRouterNavigate = (
   href: string,
   options?: I18nRouterNavigateOptions,
 ) => void | Promise<void>;
 
-export type I18nRouterLink = React.ComponentType<{
+type I18nRouterLink = React.ComponentType<{
   to: string;
   children?: React.ReactNode;
   [key: string]: unknown;
 }>;
 
-export interface I18nRouterAdapter {
+interface I18nRouterAdapter {
   framework?: I18nRouterFramework;
   hasRouter: boolean;
   location: I18nRouterLocation | null;

package/src/runtime/utils.ts

@@ -1,12 +1,17 @@
 import { isBrowser } from '@modern-js/runtime';
-import {
-  getGlobalBasename,
-  type TInternalRuntimeContext,
-} from '@modern-js/runtime/context';
+import { getGlobalBasename } from '@modern-js/runtime/context';
 import type { LocalisedUrlsOption } from '../shared/localisedUrls';
-import { localiseTargetPathname } from '../shared/localisedUrls';
-
-export const getPathname = (context: TInternalRuntimeContext): string => {
+import {
+  localiseTargetPathname,
+  shouldSkipLocaleRedirect,
+} from '../shared/localisedUrls';
+
+// Structural parameter: hooks.ts passes a public-TRuntimeContext-based
+// context while core.tsx passes the internal one; both carry the request
+// pathname shape this helper needs.
+export const getPathname = (context: {
+  ssrContext?: { request?: { pathname?: string } };
+}): string => {
   if (isBrowser()) {
     return window.location.pathname;
   }
@@ -127,32 +132,5 @@ export const shouldIgnoreRedirect = (
   languages: string[],
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
 ): boolean => {
-  if (!ignoreRedirectRoutes) {
-    return false;
-  }
-
-  // Remove language prefix if present (e.g., /en/api -> /api)
-  const segments = pathname.split('/').filter(Boolean);
-  let pathWithoutLang = pathname;
-  if (segments.length > 0 && languages.includes(segments[0])) {
-    // Remove language prefix
-    pathWithoutLang = `/${segments.slice(1).join('/')}`;
-  }
-
-  // Normalize path (ensure it starts with /)
-  const normalizedPath = pathWithoutLang.startsWith('/')
-    ? pathWithoutLang
-    : `/${pathWithoutLang}`;
-
-  if (typeof ignoreRedirectRoutes === 'function') {
-    return ignoreRedirectRoutes(normalizedPath);
-  }
-
-  // Check if pathname matches any of the ignore patterns
-  return ignoreRedirectRoutes.some(pattern => {
-    // Support both exact match and prefix match
-    return (
-      normalizedPath === pattern || normalizedPath.startsWith(`${pattern}/`)
-    );
-  });
+  return shouldSkipLocaleRedirect(pathname, languages, ignoreRedirectRoutes);
 };

package/src/server/apiPrefix.ts

@@ -0,0 +1,67 @@
+type ApiPrefixInput = string | string[] | undefined;
+
+const normalizeApiPrefix = (prefix: string): string | null => {
+  const trimmedPrefix = prefix.trim();
+  if (!trimmedPrefix) {
+    return null;
+  }
+
+  const prefixedPath = trimmedPrefix.startsWith('/')
+    ? trimmedPrefix
+    : `/${trimmedPrefix}`;
+  const withoutWildcard = prefixedPath.replace(/\/\*$/, '');
+  const normalizedPrefix =
+    withoutWildcard.length > 1
+      ? withoutWildcard.replace(/\/+$/, '')
+      : withoutWildcard;
+
+  return normalizedPrefix === '/' ? null : normalizedPrefix;
+};
+
+export const collectApiPrefixes = (
+  routes: Array<{ isApi?: boolean; urlPath?: string }>,
+  bffPrefix?: ApiPrefixInput,
+): string[] => {
+  const prefixes = new Set<string>();
+
+  for (const route of routes) {
+    if (!route.isApi || !route.urlPath) {
+      continue;
+    }
+
+    const normalizedPrefix = normalizeApiPrefix(route.urlPath);
+    if (normalizedPrefix) {
+      prefixes.add(normalizedPrefix);
+    }
+  }
+
+  const bffPrefixes = Array.isArray(bffPrefix)
+    ? bffPrefix
+    : bffPrefix
+      ? [bffPrefix]
+      : [];
+
+  for (const prefix of bffPrefixes) {
+    const normalizedPrefix = normalizeApiPrefix(prefix);
+    if (normalizedPrefix) {
+      prefixes.add(normalizedPrefix);
+    }
+  }
+
+  return [...prefixes];
+};
+
+export const matchesApiPrefix = (
+  pathname: string,
+  apiPrefixes: string[],
+): boolean => {
+  const normalizedPathname = pathname.startsWith('/')
+    ? pathname
+    : `/${pathname}`;
+
+  return apiPrefixes.some(
+    prefix =>
+      normalizedPathname === prefix ||
+      normalizedPathname.startsWith(`${prefix}/`),
+  );
+};