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

package/src/runtime/canonicalRoutes.ts

@@ -0,0 +1,93 @@
+/**
+ * Canonical (language-agnostic) route map.
+ *
+ * Empty by default; populated via declaration merging by the generated
+ * `register.gen.d.ts` that `@modern-js/plugin-tanstack` emits:
+ *
+ * ```ts
+ * declare module '@modern-js/plugin-i18n/runtime' {
+ *   interface UltramodernCanonicalRoutes {
+ *     '/': Record<string, never>;
+ *     '/talks': Record<string, never>;
+ *     '/talks/$slug': { slug: string };
+ *   }
+ * }
+ * ```
+ *
+ * Keys are canonical route patterns in TanStack notation (`$param`,
+ * `{-$param}`); values describe the route's path params.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by generated code
+export interface UltramodernCanonicalRoutes {}
+
+export type CanonicalRoutePath = keyof UltramodernCanonicalRoutes & string;
+
+type HasCanonicalRoutes = [keyof UltramodernCanonicalRoutes] extends [never]
+  ? false
+  : true;
+
+/**
+ * Targets that bypass canonical-route validation: external URLs, same-page
+ * hash anchors, and canonical paths with a `?search` and/or `#hash` suffix
+ * (the pathname part of suffixed targets is still validated).
+ */
+type ExternalLinkTarget =
+  | `http://${string}`
+  | `https://${string}`
+  | `mailto:${string}`
+  | `tel:${string}`
+  | `//${string}`;
+
+type SuffixedCanonicalTarget =
+  | `${CanonicalRoutePath}?${string}`
+  | `${CanonicalRoutePath}#${string}`;
+
+export type AllowedLinkTarget =
+  | CanonicalRoutePath
+  | SuffixedCanonicalTarget
+  | ExternalLinkTarget
+  | `#${string}`;
+
+/**
+ * Validates a literal `to` against the canonical route map. Computed strings
+ * (type `string`) always pass — the escape hatch for dynamic values. When no
+ * canonical map has been generated, everything passes.
+ */
+export type ValidateLinkTo<TTo extends string> =
+  HasCanonicalRoutes extends false
+    ? unknown
+    : string extends TTo
+      ? unknown
+      : TTo extends AllowedLinkTarget
+        ? unknown
+        : {
+            to: {
+              error: 'Not a canonical route. Authors must write language-agnostic paths; see UltramodernCanonicalRoutes.';
+              received: TTo;
+            };
+          };
+
+/** Strip `?search`/`#hash` suffixes from a link target type. */
+export type LinkTargetPathname<TTo extends string> =
+  TTo extends `${infer TPath}#${string}`
+    ? TPath extends `${infer TPure}?${string}`
+      ? TPure
+      : TPath
+    : TTo extends `${infer TPath}?${string}`
+      ? TPath
+      : TTo;
+
+/**
+ * `params` prop contract for a canonical target: required when the route has
+ * required params, optional when all params are optional, forbidden when the
+ * route has none. Non-canonical (computed/external) targets accept a loose
+ * record.
+ */
+export type LinkParamsProp<TPath extends string> =
+  TPath extends CanonicalRoutePath
+    ? UltramodernCanonicalRoutes[TPath] extends Record<string, never>
+      ? { params?: undefined }
+      : Record<string, never> extends UltramodernCanonicalRoutes[TPath]
+        ? { params?: UltramodernCanonicalRoutes[TPath] }
+        : { params: UltramodernCanonicalRoutes[TPath] }
+    : { params?: Record<string, string | number | undefined> };

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 {
@@ -14,18 +52,85 @@ function convertPath(path: string | undefined): string | undefined {
   return path;
 }
 
-export function convertBackendOptions<
-  T extends { loadPath?: string; addPath?: string },
->(options: T): T {
+interface InternalBackendPathOptions {
+  loadPath?: string;
+  addPath?: string;
+  serverLoadPath?: string;
+  serverAddPath?: string;
+  serverLoadPaths?: string[];
+  serverAddPaths?: string[];
+  _detectedLoadPath?: string;
+  _detectedAddPath?: string;
+}
+
+function shouldUseServerPath(
+  currentPath: string | undefined,
+  detectedPath: string | undefined,
+): boolean {
+  return !detectedPath || currentPath === detectedPath;
+}
+
+function getResourceBasePath(resourcePath: string): string {
+  const markerIndex = resourcePath.indexOf('{{lng}}');
+  if (markerIndex < 0) {
+    return resourcePath;
+  }
+  return resourcePath.slice(0, markerIndex).replace(/[\\/]+$/, '');
+}
+
+function pathExists(resourcePath: string): boolean {
+  try {
+    return fs.existsSync(getResourceBasePath(resourcePath));
+  } catch {
+    return false;
+  }
+}
+
+function getServerPath(
+  pathCandidates: string[] | undefined,
+  fallbackPath: string | undefined,
+): string | undefined {
+  const candidates = Array.from(
+    new Set([...(pathCandidates || []), fallbackPath].filter(Boolean)),
+  ) as string[];
+
+  return candidates.find(pathExists) || candidates[0];
+}
+
+export function convertBackendOptions<T extends InternalBackendPathOptions>(
+  options: T,
+): T {
   if (!options) {
     return options;
   }
   const converted = { ...options };
-  if (converted.loadPath) {
+  if (
+    (converted.serverLoadPath || converted.serverLoadPaths) &&
+    shouldUseServerPath(converted.loadPath, converted._detectedLoadPath)
+  ) {
+    converted.loadPath = getServerPath(
+      converted.serverLoadPaths,
+      converted.serverLoadPath,
+    );
+  } else if (converted.loadPath) {
     converted.loadPath = convertPath(converted.loadPath);
   }
-  if (converted.addPath) {
+  if (
+    (converted.serverAddPath || converted.serverAddPaths) &&
+    shouldUseServerPath(converted.addPath, converted._detectedAddPath)
+  ) {
+    converted.addPath = getServerPath(
+      converted.serverAddPaths,
+      converted.serverAddPath,
+    );
+  } else if (converted.addPath) {
     converted.addPath = convertPath(converted.addPath);
   }
+  delete converted.serverLoadPath;
+  delete converted.serverAddPath;
+  delete converted.serverLoadPaths;
+  delete converted.serverAddPaths;
+  delete converted._detectedLoadPath;
+  delete converted._detectedAddPath;
   return converted;
 }

package/src/runtime/i18n/backend/defaults.ts

@@ -3,32 +3,34 @@ export const DEFAULT_I18NEXT_BACKEND_OPTIONS = {
   addPath: '/locales/{{lng}}/{{ns}}.json',
 };
 
-declare global {
-  interface Window {
-    __assetPrefix__?: string;
-  }
-}
-
 function convertPath(path: string | undefined): string | undefined {
-  if (!path) {
-    return path;
-  }
-  // If it's an absolute path (starts with /), convert to relative path
-  if (path.startsWith('/')) {
-    return typeof window === 'undefined'
-      ? path
-      : `${window.__assetPrefix__ || ''}${path}`;
-  }
   return path;
 }
 
-export function convertBackendOptions<
-  T extends { loadPath?: string; addPath?: string },
->(options: T): T {
+interface InternalBackendPathOptions {
+  loadPath?: string;
+  addPath?: string;
+  serverLoadPath?: string;
+  serverAddPath?: string;
+  serverLoadPaths?: string[];
+  serverAddPaths?: string[];
+  _detectedLoadPath?: string;
+  _detectedAddPath?: string;
+}
+
+export function convertBackendOptions<T extends InternalBackendPathOptions>(
+  options: T,
+): T {
   if (!options) {
     return options;
   }
   const converted = { ...options };
+  delete converted.serverLoadPath;
+  delete converted.serverAddPath;
+  delete converted.serverLoadPaths;
+  delete converted.serverAddPaths;
+  delete converted._detectedLoadPath;
+  delete converted._detectedAddPath;
   if (converted.loadPath) {
     converted.loadPath = convertPath(converted.loadPath);
   }

package/src/runtime/index.tsx

@@ -82,7 +82,7 @@ export const i18nPlugin = (options: I18nPluginOptions): RuntimePlugin => ({
     } = 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) {
@@ -293,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,107 @@
+import { useMemo } from 'react';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import { canonicalTargetPathname } 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 resolvedPath = canonicalTargetPathname(
+    pathname,
+    config.languages,
+    config.localisedUrls,
+  );
+
+  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]);
+};

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/types.ts

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

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()) {
@@ -45,36 +42,46 @@ export const getLanguageFromPath = (
   return fallbackLanguage;
 };
 
+/**
+ * Split a link target into its pathname, search and hash parts without
+ * relying on `new URL` (SSR-hot path; targets are relative).
+ */
+export const splitUrlTarget = (
+  target: string,
+): { pathname: string; search: string; hash: string } => {
+  const hashIndex = target.indexOf('#');
+  const hash = hashIndex >= 0 ? target.slice(hashIndex) : '';
+  const beforeHash = hashIndex >= 0 ? target.slice(0, hashIndex) : target;
+  const searchIndex = beforeHash.indexOf('?');
+  const search = searchIndex >= 0 ? beforeHash.slice(searchIndex) : '';
+  const pathname =
+    searchIndex >= 0 ? beforeHash.slice(0, searchIndex) : beforeHash;
+
+  return { pathname, search, hash };
+};
+
 /**
  * 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 const buildLocalizedUrl = (
-  pathname: string,
+  target: string,
   language: string,
   languages: string[],
-  localisedUrls?: boolean | LocalisedUrlsMap,
+  localisedUrls?: LocalisedUrlsOption,
 ): string => {
-  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('/')}`;
+  const { pathname, search, hash } = splitUrlTarget(target);
+  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 =