@bleedingdev/modern-js-plugin-i18n 3.2.0-ultramodern.99 → 3.4.0-ultramodern.0

package/dist/types/runtime/i18n/backend/defaults.d.ts

@@ -2,12 +2,15 @@ export declare const DEFAULT_I18NEXT_BACKEND_OPTIONS: {
     loadPath: string;
     addPath: string;
 };
-declare global {
-    interface Window {
-        __assetPrefix__?: string;
-    }
-}
-export declare function convertBackendOptions<T extends {
+interface InternalBackendPathOptions {
     loadPath?: string;
     addPath?: string;
-}>(options: T): T;
+    serverLoadPath?: string;
+    serverAddPath?: string;
+    serverLoadPaths?: string[];
+    serverAddPaths?: string[];
+    _detectedLoadPath?: string;
+    _detectedAddPath?: string;
+}
+export declare function convertBackendOptions<T extends InternalBackendPathOptions>(options: T): T;
+export {};

package/dist/types/runtime/i18n/backend/defaults.node.d.ts

@@ -1,8 +1,17 @@
+export declare const resolveDefaultLocalesDir: (cwd?: string) => string;
 export declare const DEFAULT_I18NEXT_BACKEND_OPTIONS: {
-    loadPath: string;
-    addPath: string;
+    readonly loadPath: string;
+    readonly addPath: string;
 };
-export declare function convertBackendOptions<T extends {
+interface InternalBackendPathOptions {
     loadPath?: string;
     addPath?: string;
-}>(options: T): T;
+    serverLoadPath?: string;
+    serverAddPath?: string;
+    serverLoadPaths?: string[];
+    serverAddPaths?: string[];
+    _detectedLoadPath?: string;
+    _detectedAddPath?: string;
+}
+export declare function convertBackendOptions<T extends InternalBackendPathOptions>(options: T): T;
+export {};

package/dist/types/runtime/index.d.ts

@@ -16,6 +16,10 @@ export interface I18nPluginOptions {
     [key: string]: any;
 }
 export declare 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/dist/types/runtime/localizedPaths.d.ts

@@ -0,0 +1,39 @@
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+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 declare const localizePath: (pathname: string, language: string, config: LocalizedPathsConfig) => string;
+/**
+ * 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 declare const canonicalPath: (target: string, config: LocalizedPathsConfig) => string;
+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 declare const useLocalizedPaths: () => UseLocalizedPathsReturn;
+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 declare const useLocalizedLocation: () => UseLocalizedLocationReturn;

package/dist/types/runtime/types.d.ts

@@ -8,7 +8,7 @@ declare module '@modern-js/runtime' {
             initOptions?: I18nInitOptions;
         };
     }
-    interface TInternalRuntimeContext {
+    interface TRuntimeContext {
         i18nInstance?: I18nInstance;
         changeLanguage?: (lang: string) => Promise<void>;
     }

package/dist/types/runtime/utils.d.ts

@@ -1,5 +1,5 @@
 import { type TInternalRuntimeContext } from '@modern-js/runtime/context';
-import type { LocalisedUrlsMap } from '../shared/localisedUrls';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
 export declare const getPathname: (context: TInternalRuntimeContext) => string;
 export declare const getEntryPath: () => string;
 /**
@@ -10,14 +10,23 @@ export declare const getEntryPath: () => string;
  * @returns The detected language or fallback language
  */
 export declare const getLanguageFromPath: (pathname: string, languages: string[], fallbackLanguage: string) => string;
+/**
+ * Split a link target into its pathname, search and hash parts without
+ * relying on `new URL` (SSR-hot path; targets are relative).
+ */
+export declare const splitUrlTarget: (target: string) => {
+    pathname: string;
+    search: string;
+    hash: string;
+};
 /**
  * Helper function to build localized URL
- * @param pathname - The current pathname
+ * @param target - The language-agnostic target; may include `?search` and `#hash`
  * @param language - The target language
  * @param languages - Array of supported languages
- * @returns The localized URL path
+ * @returns The localized URL path with search and hash re-appended verbatim
  */
-export declare const buildLocalizedUrl: (pathname: string, language: string, languages: string[], localisedUrls?: boolean | LocalisedUrlsMap) => string;
+export declare const buildLocalizedUrl: (target: string, language: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;
 export declare const detectLanguageFromPath: (pathname: string, languages: string[], localePathRedirect: boolean) => {
     detected: boolean;
     language?: string;

package/dist/types/shared/localisedUrls.d.ts

@@ -7,7 +7,30 @@ export interface ResolvedLocalisedUrlsConfig {
     map: LocalisedUrlsMap;
 }
 export declare const normalisePathPattern: (path: string) => string;
+/**
+ * Normalise a concrete request pathname: slash cleanup only. Unlike
+ * {@link normalisePathPattern} it must not rewrite literal `[x]` segments to
+ * `:x` params — pathnames are values, not patterns.
+ */
+export declare const normalisePathname: (pathname: string) => string;
+/**
+ * Localised URLs are strictly opt-in: only an explicit, non-empty map enables
+ * route expansion and validation. `true`, `false`, an empty map and absence
+ * all resolve to disabled, so upstream-style configs (`localePathRedirect` +
+ * `languages` without a map) keep plain locale-prefix behavior instead of
+ * failing the build for every route missing from a map they never wrote.
+ */
 export declare const resolveLocalisedUrlsConfig: (option: LocalisedUrlsOption | undefined) => ResolvedLocalisedUrlsConfig;
 export declare const validateLocalisedUrls: (routes: (NestedRouteForCli | PageRoute)[], languages: string[], localisedUrls: LocalisedUrlsMap) => void;
 export declare const applyLocalisedUrlsToRoutes: (routes: (NestedRouteForCli | PageRoute)[], languages: string[], localisedUrls: LocalisedUrlsMap) => (NestedRouteForCli | PageRoute)[];
+export declare const matchPathPattern: (pathname: string, pattern: string) => Record<string, string> | null;
+export declare const buildPathFromPattern: (pattern: string, params: Record<string, string>) => string;
 export declare const resolveLocalisedPath: (pathname: string, targetLanguage: string, languages: string[], localisedUrls: LocalisedUrlsMap) => string;
+/**
+ * Reverse-map a language-specific pathname (without language prefix) back to
+ * the canonical, language-agnostic path: localized slug patterns are matched
+ * against every language variant and rebuilt from the canonical map key.
+ */
+export declare const resolveCanonicalLocalisedPath: (pathname: string, languages: string[], localisedUrls: LocalisedUrlsMap) => string;
+export declare const localiseTargetPathname: (pathname: string, language: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;
+export declare const canonicalTargetPathname: (pathname: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;

package/dist/types/shared/type.d.ts

@@ -10,12 +10,14 @@ export interface BaseLocaleDetectionOptions {
     /**
      * Enables localised pathnames in addition to the locale prefix.
      *
-     * - `false`: keep only locale-prefix behavior (`/en/about`).
-     * - object: map canonical route paths to every configured language.
+     * - non-empty object: map canonical route paths to every configured
+     *   language; route generation then validates that every localisable route
+     *   path has entries for all configured languages.
+     * - absent / `false` / `true` / empty object: keep only locale-prefix
+     *   behavior (`/en/about`).
      *
-     * Defaults to `true` when `localePathRedirect` is enabled, so route
-     * generation validates that every localisable route path has entries for all
-     * configured languages.
+     * Strictly opt-in: without a map, `localePathRedirect` + `languages` behave
+     * exactly like upstream Modern.js.
      */
     localisedUrls?: LocalisedUrlsOption;
 }
@@ -70,6 +72,26 @@ export interface BaseBackendOptions {
     enabled?: boolean;
     loadPath?: string;
     addPath?: string;
+    /**
+     * Internal file-system path used by the Node.js FS backend.
+     * Browser HTTP backend keeps using `loadPath`.
+     */
+    serverLoadPath?: string;
+    /**
+     * Internal file-system path candidates used by the Node.js FS backend.
+     * The first existing path under current cwd will be used.
+     */
+    serverLoadPaths?: string[];
+    /**
+     * Internal file-system path used by the Node.js FS backend.
+     * Browser HTTP backend keeps using `addPath`.
+     */
+    serverAddPath?: string;
+    /**
+     * Internal file-system path candidates used by the Node.js FS backend.
+     * The first existing path under current cwd will be used.
+     */
+    serverAddPaths?: string[];
     /**
      * Cache hit mode for chained backend (only effective when both `loadPath` and `sdk` are provided)
      *

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.99",
+  "version": "3.4.0-ultramodern.0",
   "engines": {
     "node": ">=20"
   },
@@ -83,41 +83,44 @@
   "dependencies": {
     "@swc/helpers": "^0.5.23",
     "i18next-browser-languagedetector": "^8.2.1",
-    "i18next-chained-backend": "^5.0.4",
+    "i18next-chained-backend": "^5.0.5",
     "i18next-fs-backend": "^2.6.6",
     "i18next-http-backend": "^4.0.0",
     "i18next-http-middleware": "^3.9.7",
-    "react-i18next": "17.0.8",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.99",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.2.0-ultramodern.99",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.99",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.2.0-ultramodern.99",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.99",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.2.0-ultramodern.99"
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.4.0-ultramodern.0",
+    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.4.0-ultramodern.0",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.4.0-ultramodern.0",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.4.0-ultramodern.0",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.4.0-ultramodern.0",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.4.0-ultramodern.0"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.2.0-ultramodern.99",
-    "i18next": ">=25.7.4",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6"
+    "@modern-js/runtime": "3.4.0-ultramodern.0",
+    "i18next": ">=26.3.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-i18next": "^17.0.8"
   },
   "peerDependenciesMeta": {
     "i18next": {
       "optional": true
+    },
+    "react-i18next": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@rslib/core": "0.21.5",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
-    "i18next": "26.2.0",
-    "jest": "^30.4.2",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "ts-jest": "^29.4.11",
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.2.0-ultramodern.99",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.99"
+    "@rslib/core": "0.23.0",
+    "@types/node": "^26.0.0",
+    "@typescript/native-preview": "7.0.0-dev.20260624.1",
+    "i18next": "26.3.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-i18next": "17.0.8",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3",
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.4.0-ultramodern.0",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.4.0-ultramodern.0"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -126,7 +129,7 @@
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build",
+    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\"",
     "test": "rstest --passWithNoTests"
   }
 }

package/rstest.config.mts

@@ -26,13 +26,18 @@ export default {
     withTestPreset({
       name: 'plugin-i18n-node',
       testEnvironment: 'node',
-      include: ['tests/localisedUrls.test.ts'],
+      include: [
+        'tests/i18nUtils.test.ts',
+        'tests/localisedUrls.test.ts',
+        'tests/linkTypes.test.ts',
+        'tests/backendDefaults.test.ts',
+      ],
       extends: commonConfig,
     }),
     withTestPreset({
       name: 'plugin-i18n-client',
       testEnvironment: 'happy-dom',
-      include: ['tests/routerAdapter.test.tsx'],
+      include: ['tests/routerAdapter.test.tsx', 'tests/link.test.tsx'],
       extends: commonConfig,
     }),
   ],

package/src/cli/index.ts

@@ -13,81 +13,14 @@ import {
 } from '../shared/localisedUrls';
 import type { BackendOptions, LocaleDetectionOptions } from '../shared/type';
 import { getBackendOptions, getLocaleDetectionOptions } from '../shared/utils';
+import { applyDetectedBackendPaths, detectLocalesDirectory } from './locales';
+import '../runtime/types';
 
 export type TransformRuntimeConfigFn = (
   extendedConfig: Record<string, any>,
   entrypoint: Entrypoint,
 ) => Record<string, any>;
 
-/**
- * Check if a directory exists and contains JSON files
- */
-function hasJsonFiles(dirPath: string): boolean {
-  try {
-    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
-      return false;
-    }
-    const entries = fs.readdirSync(dirPath);
-    // Check if there are any JSON files in the directory or subdirectories
-    for (const entry of entries) {
-      const entryPath = path.join(dirPath, entry);
-      const stat = fs.statSync(entryPath);
-      if (stat.isFile() && entry.endsWith('.json')) {
-        return true;
-      }
-      if (stat.isDirectory()) {
-        // Recursively check subdirectories (e.g., locales/en/, locales/zh/)
-        if (hasJsonFiles(entryPath)) {
-          return true;
-        }
-      }
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Auto-detect if locales directory exists with JSON files
- * Checks both project root and config/public directory
- */
-function detectLocalesDirectory(
-  appDirectory: string,
-  normalizedConfig?: any,
-): boolean {
-  // Check project root directory
-  const rootLocalesPath = path.join(appDirectory, 'locales');
-  if (hasJsonFiles(rootLocalesPath)) {
-    return true;
-  }
-
-  // Check config/public directory
-  const configPublicPath = path.join(
-    appDirectory,
-    'config',
-    'public',
-    'locales',
-  );
-  if (hasJsonFiles(configPublicPath)) {
-    return true;
-  }
-
-  // Check publicDir if configured
-  const publicDir = normalizedConfig?.server?.publicDir;
-  if (publicDir) {
-    const publicDirPath = Array.isArray(publicDir) ? publicDir[0] : publicDir;
-    const localesPath = path.isAbsolute(publicDirPath)
-      ? path.join(publicDirPath, 'locales')
-      : path.join(appDirectory, publicDirPath, 'locales');
-    if (hasJsonFiles(localesPath)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
 export interface I18nPluginOptions {
   localeDetection?: LocaleDetectionOptions;
   backend?: BackendOptions;
@@ -125,10 +58,14 @@ export const i18nPlugin = (
       // Auto-detect locales directory and enable backend if:
       // 1. User didn't explicitly set backend.enabled to false
       // 2. Locales directory exists with JSON files
-      // 3. If user configured loadPath or addPath, auto-enable backend without detection
+      // 3. If user configured loadPath or addPath, auto-enable backend
       let backendOptions: BackendOptions | undefined;
       const { appDirectory } = api.getAppContext();
       const normalizedConfig = api.getNormalizedConfig();
+      const detectedLocales = detectLocalesDirectory(
+        appDirectory,
+        normalizedConfig,
+      );
 
       if (backend) {
         const entryBackendOptions = getBackendOptions(
@@ -139,45 +76,35 @@ export const i18nPlugin = (
         if (entryBackendOptions?.enabled === false) {
           backendOptions = entryBackendOptions;
         } else {
-          // If user configured loadPath or addPath, auto-enable backend
-          // No need to detect locales directory since user has specified the path
-          if (entryBackendOptions?.loadPath || entryBackendOptions?.addPath) {
+          if (detectedLocales) {
+            backendOptions = applyDetectedBackendPaths(
+              entryBackendOptions,
+              detectedLocales,
+            );
+          } else if (
+            entryBackendOptions?.loadPath ||
+            entryBackendOptions?.addPath
+          ) {
+            // If user configured loadPath or addPath, auto-enable backend even
+            // when no local locales directory is detected.
             backendOptions = {
               ...entryBackendOptions,
               enabled: true,
             };
-          } else if (entryBackendOptions?.enabled !== true) {
-            // Auto-detect if enabled is not explicitly true and no loadPath/addPath configured
-            const hasLocales = detectLocalesDirectory(
-              appDirectory,
-              normalizedConfig,
-            );
-
-            if (hasLocales) {
-              // Auto-enable backend if locales directory is detected
-              backendOptions = {
-                ...entryBackendOptions,
-                enabled: true,
-              };
-            } else {
-              backendOptions = entryBackendOptions;
-            }
           } else {
             backendOptions = entryBackendOptions;
           }
         }
       } else {
         // No backend config provided, try auto-detection
-        const hasLocales = detectLocalesDirectory(
-          appDirectory,
-          normalizedConfig,
-        );
-
-        if (hasLocales) {
+        if (detectedLocales) {
           // Auto-enable backend if locales directory is detected
-          backendOptions = getBackendOptions(entrypoint.entryName, {
-            enabled: true,
-          });
+          backendOptions = applyDetectedBackendPaths(
+            getBackendOptions(entrypoint.entryName, {
+              enabled: true,
+            }),
+            detectedLocales,
+          );
         }
       }