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

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,118 @@
+import { useMemo } from 'react';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import {
+  resolveCanonicalLocalisedPath,
+  resolveLocalisedUrlsConfig,
+} 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 segments = pathname.split('/').filter(Boolean);
+  const pathWithoutLanguage =
+    segments.length > 0 && config.languages.includes(segments[0])
+      ? `/${segments.slice(1).join('/')}`
+      : pathname || '/';
+  const localisedUrlsConfig = resolveLocalisedUrlsConfig(config.localisedUrls);
+  const resolvedPath = localisedUrlsConfig.enabled
+    ? resolveCanonicalLocalisedPath(
+        pathWithoutLanguage,
+        config.languages,
+        localisedUrlsConfig.map,
+      )
+    : pathWithoutLanguage;
+
+  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]);
+};