@bleedingdev/modern-js-plugin-i18n 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

package/src/runtime/context.tsx

@@ -1,15 +1,22 @@
 import { isBrowser } from '@modern-js/runtime';
 import type { FC, ReactNode } from 'react';
-import { createContext, useCallback, useContext, useMemo } from 'react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+} from 'react';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
 import type { I18nInstance } from './i18n';
 import type { SdkBackend } from './i18n/backend/sdk-backend';
 import { cacheUserLanguage } from './i18n/detection';
+import { useI18nRouterAdapter } from './routerAdapter';
 import {
   buildLocalizedUrl,
   detectLanguageFromPath,
   getEntryPath,
   shouldIgnoreRedirect,
-  useRouterHooks,
 } from './utils';
 
 export interface ModernI18nContextValue {
@@ -20,6 +27,7 @@ export interface ModernI18nContextValue {
   languages?: string[];
   localePathRedirect?: boolean;
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+  localisedUrls?: LocalisedUrlsOption;
   // Callback to update language in context
   updateLanguage?: (newLang: string) => void;
 }
@@ -47,6 +55,7 @@ export interface UseModernI18nReturn {
   changeLanguage: (newLang: string) => Promise<void>;
   i18nInstance: I18nInstance;
   supportedLanguages: string[];
+  localisedUrls?: LocalisedUrlsOption;
   isLanguageSupported: (lang: string) => boolean;
   // Indicates if translation resources for current language are ready to use
   isResourcesReady: boolean;
@@ -77,15 +86,40 @@ export const useModernI18n = (): UseModernI18nReturn => {
     languages,
     localePathRedirect,
     ignoreRedirectRoutes,
+    localisedUrls,
     updateLanguage,
   } = context;
 
-  // Get router hooks safely
-  const { navigate, location, hasRouter } = useRouterHooks();
+  const { navigate, location, hasRouter } = useI18nRouterAdapter();
+
+  const pathLanguage = useMemo(() => {
+    if (!localePathRedirect || !location?.pathname) {
+      return undefined;
+    }
+    const detected = detectLanguageFromPath(
+      location.pathname,
+      languages || [],
+      localePathRedirect,
+    );
+    return detected.detected ? detected.language : undefined;
+  }, [languages, localePathRedirect, location?.pathname]);
+
+  const currentLanguage = pathLanguage || contextLanguage;
 
-  // 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;
+  useEffect(() => {
+    if (!pathLanguage || pathLanguage === contextLanguage) {
+      return;
+    }
+
+    updateLanguage?.(pathLanguage);
+    i18nInstance?.setLang?.(pathLanguage);
+    void i18nInstance?.changeLanguage?.(pathLanguage);
+
+    if (isBrowser()) {
+      const detectionOptions = i18nInstance.options?.detection;
+      cacheUserLanguage(i18nInstance, pathLanguage, detectionOptions);
+    }
+  }, [contextLanguage, i18nInstance, pathLanguage, updateLanguage]);
 
   /**
    * Changes the current language and updates the URL accordingly.
@@ -147,6 +181,7 @@ export const useModernI18n = (): UseModernI18nReturn => {
               relativePath,
               newLang,
               languages || [],
+              localisedUrls,
             );
             const newUrl =
               entryPath + newPath + location.search + location.hash;
@@ -181,6 +216,7 @@ export const useModernI18n = (): UseModernI18nReturn => {
               relativePath,
               newLang,
               languages || [],
+              localisedUrls,
             );
             const newUrl =
               entryPath +
@@ -206,6 +242,7 @@ export const useModernI18n = (): UseModernI18nReturn => {
       updateLanguage,
       localePathRedirect,
       ignoreRedirectRoutes,
+      localisedUrls,
       languages,
       hasRouter,
       navigate,
@@ -275,6 +312,7 @@ export const useModernI18n = (): UseModernI18nReturn => {
     changeLanguage,
     i18nInstance,
     supportedLanguages: languages || [],
+    localisedUrls,
     isLanguageSupported,
     isResourcesReady,
   };

package/src/runtime/hooks.ts

@@ -2,6 +2,7 @@ import type { TRuntimeContext } from '@modern-js/runtime';
 import { isBrowser } from '@modern-js/runtime';
 import type React from 'react';
 import { useEffect, useRef } from 'react';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
 import type { I18nInstance } from './i18n';
 import {
   getI18nSdkBackendId,
@@ -9,13 +10,13 @@ import {
   type I18nSdkResourcesLoadedEventDetail,
 } from './i18n/backend/sdk-event';
 import { cacheUserLanguage } from './i18n/detection';
+import { useI18nRouterAdapter } from './routerAdapter';
 import {
   buildLocalizedUrl,
   detectLanguageFromPath,
   getEntryPath,
   getPathname,
   shouldIgnoreRedirect,
-  useRouterHooks,
 } from './utils';
 
 interface RuntimeContextWithI18n extends TRuntimeContext {
@@ -41,6 +42,7 @@ export function createContextValue(
   languages: string[],
   localePathRedirect: boolean,
   ignoreRedirectRoutes: string[] | ((pathname: string) => boolean) | undefined,
+  localisedUrls: LocalisedUrlsOption | undefined,
   setLang: (lang: string) => void,
 ) {
   const instance = i18nInstance || createMinimalI18nInstance(lang);
@@ -51,6 +53,7 @@ export function createContextValue(
     languages,
     localePathRedirect,
     ignoreRedirectRoutes,
+    localisedUrls,
     updateLanguage: setLang,
   };
 }
@@ -162,10 +165,10 @@ export function useClientSideRedirect(
   languages: string[],
   fallbackLanguage: string,
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
+  localisedUrls?: LocalisedUrlsOption,
 ) {
   const hasRedirectedRef = useRef(false);
-  // Get router hooks safely
-  const { navigate, location, hasRouter } = useRouterHooks();
+  const { navigate, location, hasRouter } = useI18nRouterAdapter();
 
   useEffect(() => {
     if (process.env.MODERN_TARGET !== 'browser') {
@@ -220,7 +223,12 @@ export function useClientSideRedirect(
     const targetLanguage =
       i18nInstance.language || fallbackLanguage || languages[0] || 'en';
 
-    const newPath = buildLocalizedUrl(relativePath, targetLanguage, languages);
+    const newPath = buildLocalizedUrl(
+      relativePath,
+      targetLanguage,
+      languages,
+      localisedUrls,
+    );
     const newUrl = entryPath + newPath + currentSearch + currentHash;
 
     if (newUrl !== currentPathname + currentSearch + currentHash) {
@@ -244,6 +252,7 @@ export function useClientSideRedirect(
     languages,
     fallbackLanguage,
     ignoreRedirectRoutes,
+    localisedUrls,
   ]);
 }
 

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

@@ -1,6 +1,44 @@
+import fs from 'fs';
+import nodePath from 'path';
+
+/**
+ * Conventional locales roots, in the same priority order as the CLI plugin's
+ * `detectLocalesDirectory` auto-detection (project-root `./locales` first —
+ * the upstream convention — then the scaffold's `./config/public/locales`).
+ * The fs-backend default must read from the same directory whose existence
+ * enabled the backend in the first place.
+ */
+const CONVENTIONAL_LOCALES_DIRS = [
+  './locales',
+  './config/public/locales',
+] as const;
+
+const isDirectory = (dirPath: string): boolean => {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+export const resolveDefaultLocalesDir = (
+  cwd: string = process.cwd(),
+): string => {
+  for (const dir of CONVENTIONAL_LOCALES_DIRS) {
+    if (isDirectory(nodePath.resolve(cwd, dir))) {
+      return dir;
+    }
+  }
+  return CONVENTIONAL_LOCALES_DIRS[0];
+};
+
 export const DEFAULT_I18NEXT_BACKEND_OPTIONS = {
-  loadPath: './locales/{{lng}}/{{ns}}.json',
-  addPath: './locales/{{lng}}/{{ns}}.json',
+  get loadPath(): string {
+    return `${resolveDefaultLocalesDir()}/{{lng}}/{{ns}}.json`;
+  },
+  get addPath(): string {
+    return `${resolveDefaultLocalesDir()}/{{lng}}/{{ns}}.json`;
+  },
 };
 
 function convertPath(path: string | undefined): string | undefined {

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

@@ -15,7 +15,9 @@ function convertPath(path: string | undefined): string | undefined {
   }
   // If it's an absolute path (starts with /), convert to relative path
   if (path.startsWith('/')) {
-    return `${window.__assetPrefix__ || ''}${path}`;
+    return typeof window === 'undefined'
+      ? path
+      : `${window.__assetPrefix__ || ''}${path}`;
   }
   return path;
 }

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

@@ -1,4 +1,4 @@
-import Backend from 'i18next-fs-backend';
+import Backend from 'i18next-fs-backend/cjs';
 import type { ExtendedBackendOptions } from '../../../shared/type';
 import type { I18nInstance } from '../instance';
 import { useI18nextBackendCommon } from './middleware.common';

package/src/runtime/i18n/instance.ts

@@ -1,9 +1,5 @@
 import type { BaseBackendOptions } from '../../shared/type';
 
-type ReactI18nextModule = typeof import('react-i18next');
-type InitReactI18next = ReactI18nextModule['initReactI18next'];
-type I18nextProviderComponent = ReactI18nextModule['I18nextProvider'];
-
 export interface I18nResourceStore {
   data?: {
     [language: string]: {
@@ -110,9 +106,11 @@ export interface BackendOptions extends Omit<BaseBackendOptions, 'enabled'> {
   [key: string]: any;
 }
 
+export type ResourceValue = string | { [key: string]: ResourceValue };
+
 export interface Resources {
   [lng: string]: {
-    [source: string]: string | Record<string, string>;
+    [source: string]: ResourceValue;
   };
 }
 
@@ -171,15 +169,6 @@ async function createI18nextInstance(): Promise<I18nInstance | null> {
   }
 }
 
-async function tryImportReactI18next(): Promise<ReactI18nextModule | null> {
-  try {
-    const reactI18next = await import('react-i18next');
-    return reactI18next;
-  } catch (error) {
-    return null;
-  }
-}
-
 export function getI18nextInstanceForProvider(
   instance: I18nInstance | any,
 ): any {
@@ -213,19 +202,3 @@ export async function getI18nInstance(
 
   throw new Error('No i18n instance found');
 }
-
-export async function getInitReactI18next(): Promise<InitReactI18next | null> {
-  const reactI18nextModule = await tryImportReactI18next();
-  if (reactI18nextModule) {
-    return reactI18nextModule.initReactI18next;
-  }
-  return null;
-}
-
-export async function getI18nextProvider(): Promise<I18nextProviderComponent | null> {
-  const reactI18nextModule = await tryImportReactI18next();
-  if (reactI18nextModule) {
-    return reactI18nextModule.I18nextProvider;
-  }
-  return null;
-}

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

@@ -0,0 +1,25 @@
+import type React from 'react';
+
+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;
+  } catch (error) {
+    return null;
+  }
+}
+
+export async function getReactI18nextIntegration(): Promise<ReactI18nextIntegration> {
+  const reactI18nextModule = await tryImportReactI18next();
+
+  return {
+    I18nextProvider: reactI18nextModule?.I18nextProvider ?? null,
+    initReactI18next: reactI18nextModule?.initReactI18next ?? null,
+  };
+}

package/src/runtime/i18n/utils.ts

@@ -238,32 +238,10 @@ export const initializeI18nInstance = async (
       }
     }
 
-    if (mergedBackend && hasOptions(i18nInstance)) {
-      // For chained backend with cacheHitMode: 'refreshAndUpdateStore',
-      // i18next-chained-backend automatically:
-      // 1. Loads from the first backend (HTTP/FS) and displays immediately
-      // 2. Asynchronously loads from the second backend (SDK) and updates the store
-      // 3. Triggers 'loaded' event when SDK resources are loaded, which causes React to re-render
-      //
-      // Note: i18next.init() returns a Promise that resolves when the first backend loads.
-      // For chained backend, it does NOT wait for the second backend (SDK) to load.
-      // The SDK backend loads asynchronously and triggers 'loaded' event automatically.
-      const defaultNS =
-        initOptions.defaultNS || initOptions.ns || 'translation';
-      const ns = Array.isArray(defaultNS) ? defaultNS[0] : defaultNS;
-
-      let retries = 20;
-      while (retries > 0) {
-        // Get the actual i18next instance to access store property
-        const actualInstance = getActualI18nextInstance(i18nInstance);
-        const store = (actualInstance as any).store;
-        if (store?.data?.[finalLanguage]?.[ns]) {
-          break;
-        }
-        await new Promise(resolve => setTimeout(resolve, 100));
-        retries--;
-      }
-    }
+    // i18next.init() is the synchronization boundary for the primary backend.
+    // Chained SDK refreshes update the store through their own loaded events and
+    // must not block SSR HTML, otherwise missing/edge-only resources add fixed
+    // latency to every route render.
   }
 };
 

package/src/runtime/index.tsx

@@ -29,11 +29,7 @@ import {
   mergeDetectionOptions,
 } from './i18n/detection';
 import { useI18nextLanguageDetector } from './i18n/detection/middleware';
-import {
-  getI18nextInstanceForProvider,
-  getI18nextProvider,
-  getInitReactI18next,
-} from './i18n/instance';
+import { getI18nextInstanceForProvider } from './i18n/instance';
 import {
   changeI18nLanguage,
   ensureLanguageMatch,
@@ -54,6 +50,7 @@ export interface I18nPluginOptions {
   changeLanguage?: (lang: string) => void;
   initOptions?: I18nInitOptions;
   htmlLangAttr?: boolean;
+  reactI18next?: boolean;
   [key: string]: any;
 }
 
@@ -72,6 +69,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
       localeDetection,
       backend,
       htmlLangAttr = false,
+      reactI18next = true,
     } = options;
     const {
       localePathRedirect = false,
@@ -80,20 +78,31 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
       fallbackLanguage = 'en',
       detection,
       ignoreRedirectRoutes,
+      localisedUrls,
     } = localeDetection || {};
     const { enabled: backendEnabled = false } = backend || {};
     let latestI18nInstance: I18nInstance | undefined;
-    let I18nextProvider: React.FunctionComponent<any> | null;
+    let I18nextProvider: React.ComponentType<any> | null;
+
+    const loadReactI18nextIntegration = async () => {
+      if (!reactI18next) {
+        return null;
+      }
+      const { getReactI18nextIntegration } = await import(
+        './i18n/react-i18next'
+      );
+      return getReactI18nextIntegration();
+    };
 
     api.onBeforeRender(async context => {
       let i18nInstance = await getI18nInstance(userI18nInstance);
       const { i18n: otherConfig } = api.getRuntimeConfig();
       const { initOptions: otherInitOptions } = otherConfig || {};
       const userInitOptions = merge(otherInitOptions || {}, initOptions || {});
-      const initReactI18next = await getInitReactI18next();
-      I18nextProvider = await getI18nextProvider();
-      if (initReactI18next) {
-        i18nInstance.use(initReactI18next);
+      const reactI18nextIntegration = await loadReactI18nextIntegration();
+      I18nextProvider = reactI18nextIntegration?.I18nextProvider ?? null;
+      if (reactI18nextIntegration?.initReactI18next) {
+        i18nInstance.use(reactI18nextIntegration.initReactI18next);
       }
 
       const pathname = getPathname(context);
@@ -227,6 +236,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
           languages,
           fallbackLanguage,
           ignoreRedirectRoutes,
+          localisedUrls,
         );
 
         const contextValue = useMemo(
@@ -238,6 +248,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
               languages,
               localePathRedirect,
               ignoreRedirectRoutes,
+              localisedUrls,
               setLang,
             ),
           [
@@ -247,15 +258,17 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
             languages,
             localePathRedirect,
             ignoreRedirectRoutes,
+            localisedUrls,
             forceUpdate,
           ],
         );
 
+        const children = (props as React.PropsWithChildren).children;
         const appContent = (
           <>
             {Boolean(htmlLangAttr) && <Helmet htmlAttributes={{ lang }} />}
             <ModernI18nProvider value={contextValue}>
-              <App {...props} />
+              {App ? <App {...props}>{children}</App> : children}
             </ModernI18nProvider>
           </>
         );
@@ -280,6 +293,28 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
   },
 });
 
+export type {
+  AllowedLinkTarget,
+  CanonicalRoutePath,
+  UltramodernCanonicalRoutes,
+} from './canonicalRoutes';
 export { useModernI18n } from './context';
-export { I18nLink } from './I18nLink';
+export { I18nLink, type I18nLinkProps } from './I18nLink';
+export {
+  Link,
+  type LinkActiveOptions,
+  type LinkBaseProps,
+  type LinkParams,
+  type LinkProps,
+} from './Link';
+export {
+  canonicalPath,
+  type LocalizedPathsConfig,
+  localizePath,
+  type UseLocalizedLocationReturn,
+  type UseLocalizedPathsReturn,
+  useLocalizedLocation,
+  useLocalizedPaths,
+} from './localizedPaths';
+export { buildLocalizedUrl, splitUrlTarget } from './utils';
 export default i18nPlugin;

package/src/runtime/localizedPaths.ts

@@ -0,0 +1,107 @@
+import { useMemo } from 'react';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import { canonicalTargetPathname } from '../shared/localisedUrls';
+import { useModernI18n } from './context';
+import { useI18nRouterAdapter } from './routerAdapter';
+import { buildLocalizedUrl, splitUrlTarget } from './utils';
+
+export interface LocalizedPathsConfig {
+  languages: string[];
+  localisedUrls?: LocalisedUrlsOption;
+}
+
+/**
+ * Localize a canonical, language-agnostic target for the given language:
+ * adds the language prefix and applies `localisedUrls` pattern mapping.
+ * `?search`/`#hash` suffixes are preserved verbatim.
+ */
+export const localizePath = (
+  pathname: string,
+  language: string,
+  config: LocalizedPathsConfig,
+): string =>
+  buildLocalizedUrl(pathname, language, config.languages, config.localisedUrls);
+
+/**
+ * Reverse of {@link localizePath}: strip the language prefix and map localized
+ * slugs back to the canonical pattern's path. `?search`/`#hash` suffixes are
+ * preserved verbatim.
+ */
+export const canonicalPath = (
+  target: string,
+  config: LocalizedPathsConfig,
+): string => {
+  const { pathname, search, hash } = splitUrlTarget(target);
+  const resolvedPath = canonicalTargetPathname(
+    pathname,
+    config.languages,
+    config.localisedUrls,
+  );
+
+  return `${resolvedPath}${search}${hash}`;
+};
+
+export interface UseLocalizedPathsReturn {
+  localizePath: (pathname: string, language: string) => string;
+  canonicalPath: (pathname: string) => string;
+}
+
+/**
+ * Context-bound versions of {@link localizePath} and {@link canonicalPath} —
+ * the plugin configuration (languages, localisedUrls) is read from the i18n
+ * provider, so apps never copy pattern-matching helpers again.
+ */
+export const useLocalizedPaths = (): UseLocalizedPathsReturn => {
+  const { supportedLanguages, localisedUrls } = useModernI18n();
+
+  return useMemo(() => {
+    const config: LocalizedPathsConfig = {
+      languages: supportedLanguages,
+      localisedUrls,
+    };
+
+    return {
+      localizePath: (pathname: string, language: string) =>
+        localizePath(pathname, language, config),
+      canonicalPath: (pathname: string) => canonicalPath(pathname, config),
+    };
+  }, [supportedLanguages, localisedUrls]);
+};
+
+export interface UseLocalizedLocationReturn {
+  language: string;
+  /** Canonical (language-agnostic) path of the current location. */
+  canonical: string;
+  /** Per-language hrefs for the current location, search+hash preserved. */
+  alternates: Record<string, string>;
+}
+
+/**
+ * Per-language hrefs for the current location — for hreflang `<link>` tags and
+ * language switchers. SSR-safe: the location comes from the router adapter.
+ */
+export const useLocalizedLocation = (): UseLocalizedLocationReturn => {
+  const { language, supportedLanguages, localisedUrls } = useModernI18n();
+  const { location } = useI18nRouterAdapter();
+  const pathname = location?.pathname ?? '/';
+  const search = location?.search ?? '';
+  const hash = location?.hash ?? '';
+
+  return useMemo(() => {
+    const config: LocalizedPathsConfig = {
+      languages: supportedLanguages,
+      localisedUrls,
+    };
+    const alternates: Record<string, string> = {};
+    for (const supportedLanguage of supportedLanguages) {
+      alternates[supportedLanguage] =
+        `${localizePath(pathname, supportedLanguage, config)}${search}${hash}`;
+    }
+
+    return {
+      language,
+      canonical: canonicalPath(pathname, config),
+      alternates,
+    };
+  }, [language, supportedLanguages, localisedUrls, pathname, search, hash]);
+};