@bleedingdev/modern-js-plugin-i18n 3.9.0-ultramodern.9 → 3.9.3-ultramodern.2

package/src/runtime/context.tsx

@@ -1,12 +1,6 @@
 import { RuntimeComponentResolverContext } from '@modern-js/runtime/context';
 import type { ComponentType, FC, ReactNode } from 'react';
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-} from 'react';
+import { useCallback, useContext, useEffect, useMemo } from 'react';
 import type { I18nUrlStrategy } from '../shared/urlStrategy';
 import {
   changeModernI18nLanguage,
@@ -19,6 +13,10 @@ import type { I18nInstance } from './i18n';
 import type { Resources } from './i18n/instance';
 
 import { useI18nRouterAdapter } from './routerAdapter';
+import {
+  ModernI18nContext,
+  ReactI18nextProviderContext,
+} from './sharedContexts';
 
 export { getActualI18nextInstance } from './i18n/instance';
 
@@ -36,30 +34,7 @@ export interface ModernI18nContextValue {
   synchronizeLanguage?: (newLang: string) => void;
 }
 
-const modernI18nContextKey = Symbol.for(
-  '@modern-js/plugin-i18n/runtime/ModernI18nContext',
-);
-const reactI18nextProviderContextKey = Symbol.for(
-  '@modern-js/plugin-i18n/runtime/ReactI18nextProviderContext',
-);
-
-type GlobalContextStore<T> = typeof globalThis & {
-  [key: symbol]: ReturnType<typeof createContext<T>> | undefined;
-};
-
-const getGlobalContext = <T,>(key: symbol, defaultValue: T) => {
-  const globalStore = globalThis as GlobalContextStore<T>;
-  globalStore[key] ??= createContext<T>(defaultValue);
-  return globalStore[key];
-};
-
-export const ModernI18nContext =
-  getGlobalContext<ModernI18nContextValue | null>(modernI18nContextKey, null);
-export const ReactI18nextProviderContext =
-  getGlobalContext<ComponentType<any> | null>(
-    reactI18nextProviderContextKey,
-    null,
-  );
+export { ModernI18nContext, ReactI18nextProviderContext };
 
 export interface ModernI18nProviderProps {
   children: ReactNode;

package/src/runtime/contexts.ts

@@ -0,0 +1,16 @@
+import type { ComponentType } from 'react';
+import { createContext } from 'react';
+import type { ModernI18nContextValue } from './context';
+import type { I18nRouterAdapter } from './routerAdapter';
+
+// Every other i18n runtime module imports these through
+// `@modern-js/plugin-i18n/runtime/contexts` so Module Federation shares one
+// copy of them. Their values stay provider-owned.
+export const ModernI18nContext = createContext<ModernI18nContextValue | null>(
+  null,
+);
+export const ReactI18nextProviderContext =
+  createContext<ComponentType<any> | null>(null);
+export const I18nNavigationContext = createContext<I18nRouterAdapter | null>(
+  null,
+);

package/src/runtime/core.tsx

@@ -7,6 +7,7 @@ import type {
 } from '../shared/type';
 import { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
 import type { I18nInitOptions, I18nInstance } from './i18n';
+import { I18nRouterNavigationProvider } from './navigation';
 import {
   type RuntimeContextWithI18n,
   setupI18nBeforeRender,
@@ -32,6 +33,10 @@ export type {
   Resources,
   TranslateFn,
 } from './i18n/instance';
+export {
+  I18nRouterNavigationProvider,
+  useIntegratedRouterAdapter,
+} from './navigation';
 export type {
   LoadReactI18nextIntegration,
   ReactI18nextIntegration,
@@ -137,7 +142,13 @@ export const createI18nPlugin =
           fallbackLanguage,
           ignoreRedirectRoutes,
           urlStrategy: resolvedUrlStrategy,
-          NavigationProvider,
+          // The selected router, not react-router, is what a localized `<Link>`
+          // has to navigate through, and the i18n language has to follow a
+          // client-side navigation to a mapped URL. Both need the actual router
+          // instance, so a bare `appTools()` consumer gets the integrated
+          // adapter by default; a composing runtime plugin can still replace it.
+          NavigationProvider:
+            NavigationProvider ?? I18nRouterNavigationProvider,
           LanguageSynchronization,
           getLatestI18nInstance: () => latestI18nInstance,
           getI18nextProvider: () => I18nextProvider,

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

@@ -1,4 +1,5 @@
 import { LanguageDetector } from 'i18next-http-middleware';
+import { detectLanguageFromRequest } from '../../../shared/detection.js';
 import type { I18nInstance, LanguageDetectorOptions } from '../instance';
 
 type HttpDetectorInit = (
@@ -13,6 +14,20 @@ type HttpDetectorDetect = (
   detectionOrder?: unknown,
 ) => string | string[] | undefined;
 
+type DetectionRequest = Parameters<typeof detectLanguageFromRequest>[0];
+
+const isDetectionRequest = (request: unknown): request is DetectionRequest => {
+  if (!request || typeof request !== 'object') {
+    return false;
+  }
+
+  const { url, headers } = request as {
+    url?: unknown;
+    headers?: unknown;
+  };
+  return typeof url === 'string' && !!headers && typeof headers === 'object';
+};
+
 export const cacheUserLanguage = (
   _i18nInstance: I18nInstance,
   _language: string,
@@ -21,15 +36,18 @@ export const cacheUserLanguage = (
   return;
 };
 
-/**
- * Read language directly from storage (localStorage/cookie)
- * Not available in Node.js environment, returns undefined
- */
 export const readLanguageFromStorage = (
-  _detectionOptions?: LanguageDetectorOptions,
+  detectionOptions?: LanguageDetectorOptions,
+  request?: unknown,
+  languages: string[] = [],
 ): string | undefined => {
-  // In Node.js environment, storage-based detection is not available
-  return undefined;
+  if (!isDetectionRequest(request)) {
+    return undefined;
+  }
+
+  return (
+    detectLanguageFromRequest(request, languages, detectionOptions) ?? undefined
+  );
 };
 /**
  * Register LanguageDetector plugin to i18n instance

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

@@ -30,6 +30,8 @@ export const useI18nextLanguageDetector = (i18nInstance: I18nInstance) => {
  */
 export const readLanguageFromStorage = (
   detectionOptions?: LanguageDetectorOptions,
+  _request?: unknown,
+  _languages?: string[],
 ): string | undefined => {
   try {
     const options = detectionOptions || {};

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

@@ -59,6 +59,8 @@ export const detectLanguageWithPriority = async (
           localePathRedirect,
           userInitOptions,
         ),
+        ssrContext?.request,
+        languages,
       );
     } else {
       detectedLanguage = await detectLanguageFromI18nextDetector(i18nInstance, {

package/src/runtime/navigation.tsx

@@ -0,0 +1,20 @@
+import { createI18nRouterNavigation } from '@modern-js/i18n-runtime-extensions/router-navigation';
+import {
+  I18nNavigationProvider,
+  type I18nRouterAdapter,
+  useNativeI18nRouterAdapter,
+} from './routerAdapter';
+
+/**
+ * The seam, and only the seam. The selected-router navigation adapter is a
+ * fork subsystem, so it lives in the fork-owned
+ * `@modern-js/i18n-runtime-extensions` and is attached here through the
+ * `NavigationProvider` extension point this package already exposes. The
+ * factory takes this package's own primitives as arguments, so the fork
+ * package never imports back into it and the dependency stays one-way.
+ */
+export const { I18nRouterNavigationProvider, useIntegratedRouterAdapter } =
+  createI18nRouterNavigation<I18nRouterAdapter>({
+    I18nNavigationProvider,
+    useNativeI18nRouterAdapter,
+  });

package/src/runtime/routerAdapter.tsx

@@ -1,7 +1,8 @@
+import { I18nNavigationContext } from '@modern-js/plugin-i18n/runtime/contexts';
 import { isBrowser, RuntimeContext } from '@modern-js/runtime';
 import { InternalRuntimeContext } from '@modern-js/runtime/context';
 import type React from 'react';
-import { createContext, useContext } from 'react';
+import { useContext } from 'react';
 
 interface I18nRouterLocation {
   pathname: string;
@@ -44,16 +45,6 @@ export interface I18nRouterAdapter {
   };
 }
 
-const navigationContextKey = Symbol.for(
-  '@modern-js/plugin-i18n/runtime/I18nNavigationContext',
-);
-// Only the React context identity is shared. Its values remain provider-owned.
-const contextStore = globalThis as typeof globalThis & {
-  [navigationContextKey]?: React.Context<I18nRouterAdapter | null>;
-};
-const I18nNavigationContext = (contextStore[navigationContextKey] ??=
-  createContext<I18nRouterAdapter | null>(null));
-
 export const I18nNavigationProvider = ({
   children,
   value,

package/src/runtime/sharedContexts.ts

@@ -0,0 +1,8 @@
+// Upstream-owned runtime modules take the i18n contexts from this fork-owned
+// module, which reaches them through the shared
+// `@modern-js/plugin-i18n/runtime/contexts` request. That keeps the fork
+// import edge out of the upstream-owned files.
+export {
+  ModernI18nContext,
+  ReactI18nextProviderContext,
+} from '@modern-js/plugin-i18n/runtime/contexts';

package/src/shared/detection.ts

@@ -8,14 +8,13 @@ import type { LanguageDetectorOptions } from '../runtime/i18n/instance';
  * Detect language from request using the same detection logic as i18next
  * This ensures consistency between server-side and client-side detection
  */
-function detectLanguageFromRequest(
+export function detectLanguageFromRequest(
   req: {
     url: string;
     headers:
-      | {
-          get: (name: string) => string | null;
-        }
-      | Headers;
+      | Headers
+      | { get: (name: string) => string | null }
+      | Record<string, string | string[] | undefined>;
   },
   languages: string[],
   detectionOptions?: LanguageDetectorOptions,
@@ -39,11 +38,21 @@ function detectLanguageFromRequest(
       order.length > 0 ? order : ['querystring', 'cookie', 'header'];
 
     // Helper to get header value
+    // req.headers is a Fetch API Headers instance when the caller passes the raw
+    // Request (e.g. ssrContext.request.raw), but modern.js's own SSR request object
+    // (ssrContext.request) carries headers as a plain, lower-cased key/value object.
     const getHeader = (name: string): string | null => {
-      if (req.headers instanceof Headers) {
-        return req.headers.get(name);
+      const headers = req.headers;
+      if (typeof (headers as Headers)?.get === 'function') {
+        return (headers as Headers).get(name);
+      }
+      const value = (headers as Record<string, string | string[] | undefined>)[
+        name.toLowerCase()
+      ];
+      if (Array.isArray(value)) {
+        return value[0] ?? null;
       }
-      return req.headers.get(name);
+      return value ?? null;
     };
 
     // Try each detection method in order
@@ -94,7 +103,8 @@ function detectLanguageFromRequest(
               .map((lang: string) => {
                 const [code, q] = lang.trim().split(';');
                 return {
-                  code: code.split('-')[0], // Extract base language code
+                  code,
+                  baseCode: code.split('-')[0],
                   quality: q ? parseFloat(q.split('=')[1]) : 1.0,
                 };
               })
@@ -103,12 +113,17 @@ function detectLanguageFromRequest(
                   b.quality - a.quality,
               );
 
-            // Find first matching language
+            // Find first matching language, preferring an exact tag match
+            // (e.g. 'zh-Hant-TW') over the base language code (e.g. 'zh')
             for (const lang of languagesList) {
               if (languages.length === 0 || languages.includes(lang.code)) {
                 detectedLang = lang.code;
                 break;
               }
+              if (languages.includes(lang.baseCode)) {
+                detectedLang = lang.baseCode;
+                break;
+              }
             }
           }
           break;
@@ -122,6 +137,15 @@ function detectLanguageFromRequest(
       ) {
         return detectedLang;
       }
+
+      // Match query and cookie values like header values: exact tag first,
+      // then the supported base language (e.g. 'zh-CN' -> 'zh').
+      if (detectedLang) {
+        const baseLang = detectedLang.split('-')[0];
+        if (languages.includes(baseLang)) {
+          return baseLang;
+        }
+      }
     }
   } catch (error) {
     // Silently ignore errors

package/rslib.config.mts

@@ -1,4 +0,0 @@
-import { rslibConfig } from '@modern-js/rslib';
-import { defineConfig } from '@rslib/core';
-
-export default defineConfig(rslibConfig);

package/rstest.config.mts

@@ -1,50 +0,0 @@
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { ProjectConfig } from '@rstest/core';
-import { withTestPreset } from '@scripts/rstest-config';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const commonConfig: ProjectConfig = {
-  setupFiles: [resolve(__dirname, '../../../scripts/rstest-config/setup.ts')],
-  globals: true,
-  tools: {
-    swc: {
-      jsc: {
-        transform: {
-          react: {
-            runtime: 'automatic',
-          },
-        },
-      },
-    },
-  },
-};
-
-export default {
-  projects: [
-    withTestPreset({
-      name: 'plugin-i18n-node',
-      testEnvironment: 'node',
-      include: [
-        'tests/i18nUtils.test.ts',
-        'tests/localisedUrls.test.ts',
-        'tests/localisedRouteGeneration.test.ts',
-        'tests/mappedUrlStrategyDerivation.test.ts',
-        'tests/defaultUrlStrategy.test.ts',
-        'tests/urlStrategySerialization.test.ts',
-        'tests/backendDefaults.test.ts',
-        'tests/redirectPolicy.test.ts',
-        'tests/reactI18nextRuntimeBoundary.test.ts',
-        'tests/federatedI18nBoundaryResolver.test.tsx',
-      ],
-      extends: commonConfig,
-    }),
-    withTestPreset({
-      name: 'plugin-i18n-client',
-      testEnvironment: 'happy-dom',
-      include: ['tests/routerAdapter.test.tsx', 'tests/link.test.tsx'],
-      extends: commonConfig,
-    }),
-  ],
-};

package/tests/backendDefaults.test.ts

@@ -1,30 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { describe, expect, test } from '@rstest/core';
-import { resolveDefaultLocalesDir } from '../src/runtime/i18n/backend/defaults.node';
-
-const makeTempDir = (...dirs: string[]): string => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'i18n-defaults-'));
-  for (const dir of dirs) {
-    fs.mkdirSync(path.join(root, dir), { recursive: true });
-  }
-  return root;
-};
-
-describe('node backend default loadPath', () => {
-  test('prefers the project-root ./locales convention (the detection root)', () => {
-    const root = makeTempDir('locales', 'config/public/locales');
-    expect(resolveDefaultLocalesDir(root)).toBe('./locales');
-  });
-
-  test('falls back to ./config/public/locales when only it exists', () => {
-    const root = makeTempDir('config/public/locales');
-    expect(resolveDefaultLocalesDir(root)).toBe('./config/public/locales');
-  });
-
-  test('defaults to ./locales when neither conventional directory exists', () => {
-    const root = makeTempDir();
-    expect(resolveDefaultLocalesDir(root)).toBe('./locales');
-  });
-});

package/tests/defaultUrlStrategy.test.ts

@@ -1,107 +0,0 @@
-import { describe, expect, test } from '@rstest/core';
-import { i18nServerPlugin } from '../src/server';
-import { resolveDefaultUrlStrategy } from '../src/server/defaultUrlStrategy';
-
-const localisedUrls = {
-  '/about': { en: '/about', cs: '/o-nas' },
-};
-
-const createRequestContext = (pathname: string) =>
-  ({
-    req: { url: `http://localhost${pathname}` },
-  }) as any;
-
-const bootServerPlugin = (options: Parameters<typeof i18nServerPlugin>[0]) => {
-  const middlewares: any[] = [];
-  const routes = [{ entryName: 'main', entryPath: '', urlPath: '/' }];
-  let prepare: (() => void) | undefined;
-
-  i18nServerPlugin(options).setup({
-    getServerConfig: () => ({}),
-    getServerContext: () => ({ middlewares, routes }),
-    onPrepare: (fn: () => void) => {
-      prepare = fn;
-    },
-  } as any);
-
-  prepare?.();
-  return middlewares;
-};
-
-describe('default URL strategy', () => {
-  test('a mapped locale URL config alone produces a strategy', () => {
-    const strategy = resolveDefaultUrlStrategy(localisedUrls);
-
-    expect(strategy).toBeDefined();
-    expect(strategy?.localizePathname('/about', 'cs', ['en', 'cs'])).toBe(
-      '/cs/o-nas',
-    );
-    expect(strategy?.canonicalPathname('/cs/o-nas', ['en', 'cs'])).toBe(
-      '/about',
-    );
-  });
-
-  test('no map means no derived strategy', () => {
-    expect(resolveDefaultUrlStrategy(undefined)).toBeUndefined();
-    expect(resolveDefaultUrlStrategy({})).toBeUndefined();
-    expect(resolveDefaultUrlStrategy('nope')).toBeUndefined();
-  });
-
-  test('`localisedUrls` boots the server without any extra plugin', () => {
-    // Previously this threw "Mapped locale URLs require a URL strategy",
-    // which stopped every existing consumer's server from starting.
-    const middlewares = bootServerPlugin({
-      localeDetection: {
-        fallbackLanguage: 'en',
-        languages: ['en', 'cs'],
-        localePathRedirect: true,
-        localisedUrls,
-      } as any,
-      staticRoutePrefixes: [],
-    });
-
-    expect(middlewares.map(middleware => middleware.name)).toContain(
-      'i18n-server-middleware',
-    );
-  });
-
-  test('redirects a canonical path to its mapped locale URL', async () => {
-    const middlewares = bootServerPlugin({
-      localeDetection: {
-        fallbackLanguage: 'en',
-        languages: ['en', 'cs'],
-        localePathRedirect: true,
-        localisedUrls,
-      } as any,
-      staticRoutePrefixes: [],
-    });
-
-    const redirect = middlewares.find(
-      middleware => middleware.name === 'i18n-server-middleware',
-    );
-    const context = createRequestContext('/about');
-    context.get = () => 'cs';
-    const response = await redirect.handler(context, async () => undefined);
-
-    expect(response?.headers?.get('location')).toBe('/cs/o-nas');
-  });
-
-  test('an explicit strategy still wins over the derived one', () => {
-    const explicit = {
-      localizePathname: () => '/explicit',
-      canonicalPathname: () => '/explicit',
-    };
-    const middlewares = bootServerPlugin({
-      localeDetection: {
-        fallbackLanguage: 'en',
-        languages: ['en', 'cs'],
-        localePathRedirect: true,
-        localisedUrls,
-      } as any,
-      staticRoutePrefixes: [],
-      resolveUrlStrategy: () => explicit,
-    });
-
-    expect(middlewares.length).toBeGreaterThan(0);
-  });
-});

package/tests/federatedI18nBoundaryResolver.test.tsx

@@ -1,65 +0,0 @@
-import { RuntimeComponentResolverContext } from '@modern-js/runtime/context';
-import { describe, expect, test } from '@rstest/core';
-import { useState } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
-import {
-  FederatedI18nBoundary,
-  type FederatedI18nBoundaryProps,
-} from '../src/runtime/context';
-
-const props: FederatedI18nBoundaryProps = {
-  defaultNamespace: 'inventory',
-  resources: {},
-  children: <span>child content</span>,
-};
-
-describe('native federation resolver wrapper', () => {
-  test('retains the actionable fallback when a resolver does not handle i18n', () => {
-    expect(() =>
-      renderToStaticMarkup(
-        <RuntimeComponentResolverContext.Provider
-          value={component => component}
-        >
-          <FederatedI18nBoundary {...props} />
-        </RuntimeComponentResolverContext.Provider>,
-      ),
-    ).toThrow(/requires the @modern-js\/i18n-integration runtime plugin/);
-  });
-
-  test('rejects resolution back to the native wrapper', () => {
-    expect(() =>
-      renderToStaticMarkup(
-        <RuntimeComponentResolverContext.Provider
-          value={() => FederatedI18nBoundary}
-        >
-          <FederatedI18nBoundary {...props} />
-        </RuntimeComponentResolverContext.Provider>,
-      ),
-    ).toThrow(/resolver returned its own wrapper/);
-  });
-
-  test('renders the resolved hook-bearing component with unchanged props', () => {
-    let receivedProps: FederatedI18nBoundaryProps | undefined;
-    function ResolvedBoundary(value: FederatedI18nBoundaryProps) {
-      receivedProps = value;
-      const [label] = useState('resolved');
-      return (
-        <section>
-          {label}:{value.children}
-        </section>
-      );
-    }
-    const html = renderToStaticMarkup(
-      <RuntimeComponentResolverContext.Provider
-        value={(component, { name }) =>
-          name === 'i18n.FederatedI18nBoundary' ? ResolvedBoundary : component
-        }
-      >
-        <FederatedI18nBoundary {...props} />
-      </RuntimeComponentResolverContext.Provider>,
-    );
-    expect(html).toBe('<section>resolved:<span>child content</span></section>');
-    expect(receivedProps?.resources).toBe(props.resources);
-    expect(receivedProps?.defaultNamespace).toBe('inventory');
-  });
-});

package/tests/i18nUtils.test.ts

@@ -1,60 +0,0 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { describe, expect, test } from '@rstest/core';
-import {
-  FsBackendWithSave,
-  resolveFsBackendConstructor,
-} from '../src/runtime/i18n/backend/middleware.node';
-
-describe('i18n runtime utils', () => {
-  test('normalizes node fs backend CJS and ESM namespace shapes', () => {
-    class FakeBackend {}
-
-    expect(resolveFsBackendConstructor(FakeBackend)).toBe(FakeBackend);
-    expect(resolveFsBackendConstructor({ default: FakeBackend })).toBe(
-      FakeBackend,
-    );
-    expect(resolveFsBackendConstructor({ 'module.exports': FakeBackend })).toBe(
-      FakeBackend,
-    );
-    expect(
-      resolveFsBackendConstructor({ default: { default: FakeBackend } }),
-    ).toBe(FakeBackend);
-    expect(
-      resolveFsBackendConstructor({
-        default: { 'module.exports': FakeBackend },
-      }),
-    ).toBe(FakeBackend);
-  });
-
-  test('loads translation resources through the node fs backend', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'i18n-backend-'));
-
-    try {
-      await mkdir(join(root, 'cs'), { recursive: true });
-      await writeFile(
-        join(root, 'cs', 'common.json'),
-        JSON.stringify({ title: 'Ahoj' }),
-      );
-      const backend = new FsBackendWithSave(
-        {},
-        { loadPath: join(root, '{{lng}}', '{{ns}}.json') },
-        {},
-      );
-      const resources = await new Promise<unknown>((resolve, reject) => {
-        backend.read('cs', 'common', (error: Error | null, data: unknown) => {
-          if (error) {
-            reject(error);
-          } else {
-            resolve(data);
-          }
-        });
-      });
-
-      expect(resources).toEqual({ title: 'Ahoj' });
-    } finally {
-      await rm(root, { force: true, recursive: true });
-    }
-  });
-});