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

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,4 +1,5 @@
 import { type TInternalRuntimeContext } from '@modern-js/runtime/context';
+import type { LocalisedUrlsMap } from '../shared/localisedUrls';
 export declare const getPathname: (context: TInternalRuntimeContext) => string;
 export declare const getEntryPath: () => string;
 /**
@@ -9,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[]) => string;
+export declare const buildLocalizedUrl: (target: string, language: string, languages: string[], localisedUrls?: boolean | LocalisedUrlsMap) => string;
 export declare const detectLanguageFromPath: (pathname: string, languages: string[], localePathRedirect: boolean) => {
     detected: boolean;
     language?: string;
@@ -25,9 +35,3 @@ export declare const detectLanguageFromPath: (pathname: string, languages: strin
  * Check if the given pathname should ignore automatic locale redirect
  */
 export declare const shouldIgnoreRedirect: (pathname: string, languages: string[], ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean)) => boolean;
-export declare const useRouterHooks: () => {
-    navigate: any;
-    location: any;
-    params: any;
-    hasRouter: boolean;
-};

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

@@ -4,5 +4,11 @@ export interface I18nPluginOptions {
     localeDetection: LocaleDetectionOptions;
     staticRoutePrefixes: string[];
 }
+type ApiPrefixInput = string | string[] | undefined;
+export declare const collectApiPrefixes: (routes: Array<{
+    isApi?: boolean;
+    urlPath?: string;
+}>, bffPrefix?: ApiPrefixInput) => string[];
+export declare const matchesApiPrefix: (pathname: string, apiPrefixes: string[]) => boolean;
 export declare const i18nServerPlugin: (options: I18nPluginOptions) => ServerPlugin;
 export default i18nServerPlugin;

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

@@ -0,0 +1,21 @@
+import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
+export type LocalisedUrlPathMap = Record<string, string>;
+export type LocalisedUrlsMap = Record<string, LocalisedUrlPathMap>;
+export type LocalisedUrlsOption = boolean | LocalisedUrlsMap;
+export interface ResolvedLocalisedUrlsConfig {
+    enabled: boolean;
+    map: LocalisedUrlsMap;
+}
+export declare const normalisePathPattern: (path: string) => string;
+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;

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

@@ -1,4 +1,5 @@
 import type { LanguageDetectorOptions, Resources } from '../runtime/i18n/instance';
+import type { LocalisedUrlsOption } from './localisedUrls';
 export interface BaseLocaleDetectionOptions {
     localePathRedirect?: boolean;
     i18nextDetector?: boolean;
@@ -6,6 +7,17 @@ export interface BaseLocaleDetectionOptions {
     fallbackLanguage?: string;
     detection?: LanguageDetectorOptions;
     ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+    /**
+     * 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.
+     *
+     * Defaults to `true` when `localePathRedirect` is enabled, so route
+     * generation validates that every localisable route path has entries for all
+     * configured languages.
+     */
+    localisedUrls?: LocalisedUrlsOption;
 }
 export interface LocaleDetectionOptions extends BaseLocaleDetectionOptions {
     localeDetectionByEntry?: Record<string, BaseLocaleDetectionOptions>;

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.12",
+  "version": "3.2.0-ultramodern.120",
   "engines": {
     "node": ">=20"
   },
@@ -81,47 +81,43 @@
     }
   },
   "dependencies": {
-    "@swc/helpers": "^0.5.21",
+    "@swc/helpers": "^0.5.23",
     "i18next-browser-languagedetector": "^8.2.1",
     "i18next-chained-backend": "^5.0.4",
-    "i18next-fs-backend": "^2.6.5",
+    "i18next-fs-backend": "^2.6.6",
     "i18next-http-backend": "^4.0.0",
-    "i18next-http-middleware": "^3.9.6",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.2.0-ultramodern.12",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.2.0-ultramodern.12",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.12",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.2.0-ultramodern.12",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.12",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.12"
+    "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"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.2.0-ultramodern.12",
+    "@modern-js/runtime": "3.2.0-ultramodern.120",
     "i18next": ">=25.7.4",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-i18next": ">=15.7.4"
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
   },
   "peerDependenciesMeta": {
     "i18next": {
       "optional": true
-    },
-    "react-i18next": {
-      "optional": true
     }
   },
   "devDependencies": {
-    "@rslib/core": "0.21.5",
+    "@rslib/core": "0.22.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.8.0",
-    "@typescript/native-preview": "7.0.0-dev.20260516.1",
-    "i18next": "26.2.0",
+    "@types/node": "^25.9.3",
+    "@typescript/native-preview": "7.0.0-dev.20260610.1",
+    "i18next": "26.3.1",
     "jest": "^30.4.2",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-i18next": "17.0.8",
-    "ts-jest": "^29.4.9",
-    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.2.0-ultramodern.12",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.12"
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "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"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -130,7 +126,7 @@
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build",
+    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\"",
     "test": "rstest --passWithNoTests"
   }
 }

package/rstest.config.mts

@@ -0,0 +1,39 @@
+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/localisedUrls.test.ts', 'tests/linkTypes.test.ts'],
+      extends: commonConfig,
+    }),
+    withTestPreset({
+      name: 'plugin-i18n-client',
+      testEnvironment: 'happy-dom',
+      include: ['tests/routerAdapter.test.tsx', 'tests/link.test.tsx'],
+      extends: commonConfig,
+    }),
+  ],
+};

package/src/cli/index.ts

@@ -1,10 +1,19 @@
 import type { AppTools, CliPlugin } from '@modern-js/app-tools';
 import { getPublicDirRoutePrefixes } from '@modern-js/server-core';
-import type { Entrypoint } from '@modern-js/types';
+import type {
+  Entrypoint,
+  NestedRouteForCli,
+  PageRoute,
+} from '@modern-js/types';
 import fs from 'fs';
 import path from 'path';
+import {
+  applyLocalisedUrlsToRoutes,
+  resolveLocalisedUrlsConfig,
+} from '../shared/localisedUrls';
 import type { BackendOptions, LocaleDetectionOptions } from '../shared/type';
 import { getBackendOptions, getLocaleDetectionOptions } from '../shared/utils';
+import '../runtime/types';
 
 export type TransformRuntimeConfigFn = (
   extendedConfig: Record<string, any>,
@@ -203,6 +212,40 @@ export const i18nPlugin = (
       };
     });
 
+    api.modifyFileSystemRoutes(({ entrypoint, routes }) => {
+      if (!localeDetection) {
+        return { entrypoint, routes };
+      }
+
+      const localeDetectionOptions = getLocaleDetectionOptions(
+        entrypoint.entryName,
+        localeDetection,
+      );
+      const {
+        localePathRedirect,
+        languages = [],
+        localisedUrls,
+      } = localeDetectionOptions;
+
+      if (!localePathRedirect || languages.length === 0) {
+        return { entrypoint, routes };
+      }
+
+      const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
+      if (!localisedUrlsConfig.enabled) {
+        return { entrypoint, routes };
+      }
+
+      return {
+        entrypoint,
+        routes: applyLocalisedUrlsToRoutes(
+          routes as (NestedRouteForCli | PageRoute)[],
+          languages,
+          localisedUrlsConfig.map,
+        ),
+      };
+    });
+
     api._internalServerPlugins(({ plugins }) => {
       const { serverRoutes, metaName } = api.getAppContext();
       const normalizedConfig = api.getNormalizedConfig();

package/src/runtime/I18nLink.tsx

@@ -1,73 +1,36 @@
-import { Link, useInRouterContext, useParams } from '@modern-js/runtime/router';
 import type React from 'react';
-import { useModernI18n } from './context';
-import { buildLocalizedUrl } from './utils';
+import { Link } from './Link';
 
 export interface I18nLinkProps {
   to: string;
   children: React.ReactNode;
-  [key: string]: any; // Allow other props to be passed through
+  [key: string]: any;
 }
 
+let warnedDeprecation = false;
+
 /**
- * I18nLink component that automatically adds language prefix to navigation links.
- * This component should be used within a :lang dynamic route context.
- *
- * @example
- * ```tsx
- * // When current language is 'en' and to="/about"
- * // The actual link will be "/en/about"
- * <I18nLink to="/about">About</I18nLink>
- *
- * // When current language is 'zh' and to="/"
- * // The actual link will be "/zh"
- * <I18nLink to="/">Home</I18nLink>
- * ```
+ * @deprecated Use {@link Link} from `@modern-js/plugin-i18n/runtime` instead.
+ * `Link` accepts the same language-agnostic `to` values and additionally
+ * supports `#hash`/`?query` targets, typed canonical routes, `params`
+ * interpolation and language-invariant active state.
  */
-// Use static imports to avoid breaking router tree-shaking. Detect router context via useInRouterContext.
-const useRouterHooks = () => {
-  const inRouter = useInRouterContext();
-  return {
-    Link: inRouter ? Link : null,
-    params: inRouter ? useParams() : ({} as any),
-    hasRouter: inRouter,
-  };
-};
-
 export const I18nLink: React.FC<I18nLinkProps> = ({
   to,
   children,
   ...props
 }) => {
-  const { Link, params, hasRouter } = useRouterHooks();
-  const { language, supportedLanguages } = useModernI18n();
-
-  // Get the 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 currentLang = language;
-
-  // Build the localized URL by adding language prefix
-  const localizedTo = buildLocalizedUrl(to, currentLang, supportedLanguages);
-
-  // In development mode, warn if used outside of :lang route context
-  if (process.env.NODE_ENV === 'development' && hasRouter && !params.lang) {
+  if (process.env.NODE_ENV === 'development' && !warnedDeprecation) {
+    warnedDeprecation = true;
     console.warn(
-      'I18nLink is being used outside of a :lang dynamic route context. ' +
-        'This may cause unexpected behavior. Please ensure I18nLink is used within a route that has a :lang parameter.',
-    );
-  }
-
-  // If router is not available, render as a regular anchor tag
-  if (!hasRouter || !Link) {
-    return (
-      <a href={localizedTo} {...props}>
-        {children}
-      </a>
+      '[plugin-i18n] I18nLink is deprecated. Import { Link } from ' +
+        "'@modern-js/plugin-i18n/runtime' instead — it accepts the same " +
+        'language-agnostic `to` values.',
     );
   }
 
   return (
-    <Link to={localizedTo} {...props}>
+    <Link to={to} {...props}>
       {children}
     </Link>
   );