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

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

@@ -1,6 +1,7 @@
+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 {
     loadPath?: string;

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;
 /**
@@ -26,7 +26,7 @@ export declare const splitUrlTarget: (target: string) => {
  * @param languages - Array of supported languages
  * @returns The localized URL path with search and hash re-appended verbatim
  */
-export declare const buildLocalizedUrl: (target: 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,6 +7,19 @@ 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)[];
@@ -19,3 +32,5 @@ export declare const resolveLocalisedPath: (pathname: string, targetLanguage: st
  * 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;
 }

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.120",
+  "version": "3.2.0-ultramodern.122",
   "engines": {
     "node": ">=20"
   },
@@ -87,23 +87,26 @@
     "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/plugin": "npm:@bleedingdev/modern-js-plugin@3.2.0-ultramodern.120",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.2.0-ultramodern.120",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.120",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.2.0-ultramodern.120",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.120",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.120"
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.2.0-ultramodern.122",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.2.0-ultramodern.122",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.122",
+    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.2.0-ultramodern.122",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.122",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.122"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.2.0-ultramodern.120",
+    "@modern-js/runtime": "3.2.0-ultramodern.122",
     "i18next": ">=25.7.4",
     "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react-dom": "^19.2.7",
+    "react-i18next": "^17.0.0"
   },
   "peerDependenciesMeta": {
     "i18next": {
       "optional": true
+    },
+    "react-i18next": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -115,9 +118,10 @@
     "jest": "^30.4.2",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
+    "react-i18next": "17.0.8",
     "ts-jest": "^29.4.11",
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.2.0-ultramodern.120",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.120"
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.2.0-ultramodern.122",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.122"
   },
   "sideEffects": false,
   "publishConfig": {

package/rstest.config.mts

@@ -26,7 +26,12 @@ export default {
     withTestPreset({
       name: 'plugin-i18n-node',
       testEnvironment: 'node',
-      include: ['tests/localisedUrls.test.ts', 'tests/linkTypes.test.ts'],
+      include: [
+        'tests/i18nUtils.test.ts',
+        'tests/localisedUrls.test.ts',
+        'tests/linkTypes.test.ts',
+        'tests/backendDefaults.test.ts',
+      ],
       extends: commonConfig,
     }),
     withTestPreset({

package/src/runtime/Link.tsx

@@ -119,7 +119,17 @@ export interface LinkBaseProps extends AnchorRest {
   search?: string | Record<string, unknown>;
   hashScrollIntoView?: boolean | ScrollIntoViewOptions;
   replace?: boolean;
+  /**
+   * Prefetching behavior, forwarded to the underlying router link:
+   * react-router gets it verbatim (Modern.js `PrefetchLink` supports it),
+   * TanStack receives it as its native `preload` prop (`'none'` -> `false`).
+   * Stripped from plain `<a>` fallbacks (external / no-router targets).
+   */
   prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  /**
+   * Native preload value of the underlying router link. When set, it wins
+   * over `prefetch` on the TanStack branch.
+   */
   preload?: unknown;
   activeOptions?: LinkActiveOptions;
   /** Extra anchor props applied when the link is active. */
@@ -215,6 +225,8 @@ export const Link = <TTo extends string = string>(
     hashScrollIntoView,
     activeOptions,
     activeProps,
+    prefetch,
+    preload,
     ...rest
   } = props as LinkBaseProps & { to: string; params?: LinkParams };
 
@@ -320,12 +332,7 @@ export const Link = <TTo extends string = string>(
 
   // External targets and same-page anchors are vanilla links.
   if (!target) {
-    const {
-      prefetch: _prefetch,
-      preload: _preload,
-      replace: _replace,
-      ...anchorProps
-    } = rest;
+    const { replace: _replace, ...anchorProps } = rest;
 
     return (
       <a href={to} {...anchorProps}>
@@ -337,12 +344,7 @@ export const Link = <TTo extends string = string>(
   const { Link: RouterLink, hasRouter, framework } = adapter;
 
   if (!hasRouter || !RouterLink) {
-    const {
-      prefetch: _prefetch,
-      preload: _preload,
-      replace: _replace,
-      ...anchorProps
-    } = rest;
+    const { replace: _replace, ...anchorProps } = rest;
     const {
       className: activeClassName,
       style: activeStyle,
@@ -378,6 +380,17 @@ export const Link = <TTo extends string = string>(
   };
 
   if (framework === 'tanstack') {
+    // TanStack's prop is `preload`; map our react-router-flavored `prefetch`
+    // onto it (`'none'` -> `false`). An explicit native `preload` wins.
+    const tanstackPreload =
+      preload !== undefined
+        ? preload
+        : prefetch === undefined
+          ? undefined
+          : prefetch === 'none'
+            ? false
+            : prefetch;
+
     // Pass hash/search natively: string-concatenated targets silently break
     // TanStack navigation.
     return (
@@ -386,6 +399,7 @@ export const Link = <TTo extends string = string>(
         {...(target.searchObject ? { search: target.searchObject } : {})}
         {...(target.hash ? { hash: target.hash } : {})}
         {...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView })}
+        {...(tanstackPreload === undefined ? {} : { preload: tanstackPreload })}
         {...rest}
         {...activeRest}
         {...activeAttributes}
@@ -400,6 +414,8 @@ export const Link = <TTo extends string = string>(
   return (
     <RouterLink
       to={target.href}
+      {...(prefetch === undefined ? {} : { prefetch })}
+      {...(preload === undefined ? {} : { preload })}
       {...rest}
       {...activeRest}
       {...activeAttributes}

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: './config/public/locales/{{lng}}/{{ns}}.json',
-  addPath: './config/public/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/localizedPaths.ts

@@ -1,9 +1,6 @@
 import { useMemo } from 'react';
 import type { LocalisedUrlsOption } from '../shared/localisedUrls';
-import {
-  resolveCanonicalLocalisedPath,
-  resolveLocalisedUrlsConfig,
-} from '../shared/localisedUrls';
+import { canonicalTargetPathname } from '../shared/localisedUrls';
 import { useModernI18n } from './context';
 import { useI18nRouterAdapter } from './routerAdapter';
 import { buildLocalizedUrl, splitUrlTarget } from './utils';
@@ -35,19 +32,11 @@ export const canonicalPath = (
   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;
+  const resolvedPath = canonicalTargetPathname(
+    pathname,
+    config.languages,
+    config.localisedUrls,
+  );
 
   return `${resolvedPath}${search}${hash}`;
 };

package/src/runtime/routerAdapter.tsx

@@ -1,5 +1,6 @@
 import { isBrowser, RuntimeContext } from '@modern-js/runtime';
 import {
+  getRouterRuntimeState,
   InternalRuntimeContext,
   type TInternalRuntimeContext,
   type TRuntimeContext,
@@ -131,9 +132,8 @@ const getRouterFramework = (
   inReactRouter: boolean,
 ): I18nRouterFramework | undefined => {
   const framework =
-    internalContext.routerFramework ||
-    internalContext.routerRuntime?.framework ||
-    runtimeContext.routerFramework;
+    getRouterRuntimeState(internalContext)?.framework ||
+    getRouterRuntimeState(runtimeContext)?.framework;
 
   if (framework) {
     return framework;
@@ -167,8 +167,7 @@ const getRouterInstance = (
     return contextRouter;
   }
 
-  const router =
-    internalContext.routerInstance || internalContext.routerRuntime?.instance;
+  const router = getRouterRuntimeState(internalContext)?.instance;
   if (!router || typeof router !== 'object') {
     return null;
   }

package/src/runtime/utils.ts

@@ -3,11 +3,8 @@ import {
   getGlobalBasename,
   type TInternalRuntimeContext,
 } from '@modern-js/runtime/context';
-import type { LocalisedUrlsMap } from '../shared/localisedUrls';
-import {
-  resolveLocalisedPath,
-  resolveLocalisedUrlsConfig,
-} from '../shared/localisedUrls';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import { localiseTargetPathname } from '../shared/localisedUrls';
 
 export const getPathname = (context: TInternalRuntimeContext): string => {
   if (isBrowser()) {
@@ -74,26 +71,17 @@ export const buildLocalizedUrl = (
   target: string,
   language: string,
   languages: string[],
-  localisedUrls?: boolean | LocalisedUrlsMap,
+  localisedUrls?: LocalisedUrlsOption,
 ): string => {
   const { pathname, search, hash } = splitUrlTarget(target);
-  const segments = pathname.split('/').filter(Boolean);
-  const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
-  const pathWithoutLanguage =
-    segments.length > 0 && languages.includes(segments[0])
-      ? `/${segments.slice(1).join('/')}`
-      : pathname || '/';
-  const resolvedPath = localisedUrlsConfig.enabled
-    ? resolveLocalisedPath(
-        pathWithoutLanguage,
-        language,
-        languages,
-        localisedUrlsConfig.map,
-      )
-    : pathWithoutLanguage;
-  const resolvedSegments = resolvedPath.split('/').filter(Boolean);
-
-  return `/${[language, ...resolvedSegments].join('/')}${search}${hash}`;
+  const localizedPathname = localiseTargetPathname(
+    pathname,
+    language,
+    languages,
+    localisedUrls,
+  );
+
+  return `${localizedPathname}${search}${hash}`;
 };
 
 export const detectLanguageFromPath = (

package/src/server/index.ts

@@ -9,7 +9,7 @@ import {
 } from '../runtime/i18n/detection/config.js';
 import type { LanguageDetectorOptions } from '../runtime/i18n/instance';
 import {
-  resolveLocalisedPath,
+  localiseTargetPathname,
   resolveLocalisedUrlsConfig,
 } from '../shared/localisedUrls.js';
 import type { LocaleDetectionOptions } from '../shared/type';
@@ -314,22 +314,12 @@ const buildLocalizedUrl = (
     ? pathname.slice(basePath.length)
     : pathname;
 
-  const segments = remainingPath.split('/').filter(Boolean);
-  const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
-  const pathWithoutLanguage =
-    segments.length > 0 && languages.includes(segments[0])
-      ? `/${segments.slice(1).join('/')}`
-      : remainingPath;
-  const resolvedPath = localisedUrlsConfig.enabled
-    ? resolveLocalisedPath(
-        pathWithoutLanguage,
-        language,
-        languages,
-        localisedUrlsConfig.map,
-      )
-    : pathWithoutLanguage;
-  const resolvedSegments = resolvedPath.split('/').filter(Boolean);
-  const newPathname = `/${[language, ...resolvedSegments].join('/')}`;
+  const newPathname = localiseTargetPathname(
+    remainingPath,
+    language,
+    languages,
+    localisedUrls,
+  );
   // Handle root path case to avoid double slashes like //en
   const suffix = `${url.search}${url.hash}`;
   const localizedUrl =