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

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.119",
+  "version": "3.2.0-ultramodern.120",
   "engines": {
     "node": ">=20"
   },
@@ -88,15 +88,15 @@
     "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.119",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.2.0-ultramodern.119",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.2.0-ultramodern.119",
-    "@modern-js/server-runtime": "npm:@bleedingdev/modern-js-server-runtime@3.2.0-ultramodern.119",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.2.0-ultramodern.119",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.2.0-ultramodern.119"
+    "@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.119",
+    "@modern-js/runtime": "3.2.0-ultramodern.120",
     "i18next": ">=25.7.4",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
@@ -107,17 +107,17 @@
     }
   },
   "devDependencies": {
-    "@rslib/core": "0.21.5",
+    "@rslib/core": "0.22.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260606.1",
+    "@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.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.119",
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.2.0-ultramodern.119"
+    "@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": {

package/rstest.config.mts

@@ -26,13 +26,13 @@ export default {
     withTestPreset({
       name: 'plugin-i18n-node',
       testEnvironment: 'node',
-      include: ['tests/localisedUrls.test.ts'],
+      include: ['tests/localisedUrls.test.ts', 'tests/linkTypes.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/runtime/I18nLink.tsx

@@ -1,7 +1,5 @@
 import type React from 'react';
-import { useModernI18n } from './context';
-import { useI18nRouterAdapter } from './routerAdapter';
-import { buildLocalizedUrl } from './utils';
+import { Link } from './Link';
 
 export interface I18nLinkProps {
   to: string;
@@ -9,61 +7,30 @@ export interface I18nLinkProps {
   [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.
  */
 export const I18nLink: React.FC<I18nLinkProps> = ({
   to,
   children,
   ...props
 }) => {
-  const { Link, params, hasRouter } = useI18nRouterAdapter();
-  const { language, supportedLanguages, localisedUrls } = 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,
-    localisedUrls,
-  );
-
-  // 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 (!hasRouter || !Link) {
-    const { prefetch: _prefetch, preload: _preload, ...anchorProps } = props;
-
-    return (
-      <a href={localizedTo} {...anchorProps}>
-        {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>
   );

package/src/runtime/Link.tsx

@@ -0,0 +1,414 @@
+import type React from 'react';
+import { useMemo } from 'react';
+import type {
+  LinkParamsProp,
+  LinkTargetPathname,
+  ValidateLinkTo,
+} from './canonicalRoutes';
+import { useModernI18n } from './context';
+import { canonicalPath, type LocalizedPathsConfig } from './localizedPaths';
+import { useI18nRouterAdapter } from './routerAdapter';
+import { buildLocalizedUrl, splitUrlTarget } from './utils';
+
+const EXTERNAL_TARGET_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+
+const warnedTargets = new Set<string>();
+
+const warnOnce = (key: string, message: string) => {
+  if (process.env.NODE_ENV !== 'development' || warnedTargets.has(key)) {
+    return;
+  }
+  warnedTargets.add(key);
+  console.warn(message);
+};
+
+export type LinkParams = Record<string, string | number | undefined>;
+
+/**
+ * Interpolate `$param`, `:param`, optional (`{-$param}` / `:param?`) and splat
+ * (`$` / `*`) segments with concrete values before localization, so
+ * pattern-mapped slugs localize correctly.
+ */
+export const interpolateRouteParams = (
+  pathname: string,
+  params?: LinkParams,
+): string => {
+  if (!/[$:*{]/.test(pathname)) {
+    return pathname;
+  }
+
+  const resolveParam = (name: string): string | undefined => {
+    const value = params?.[name];
+    return value === undefined ? undefined : String(value);
+  };
+
+  const segments = pathname
+    .split('/')
+    .map(segment => {
+      if (!segment) {
+        return segment;
+      }
+
+      if (segment.startsWith('{-$') && segment.endsWith('}')) {
+        const value = resolveParam(segment.slice(3, -1));
+        return value === undefined ? null : encodeURIComponent(value);
+      }
+
+      if (segment === '$' || segment === '*') {
+        const value = resolveParam('_splat') ?? resolveParam('*');
+        return value === undefined
+          ? null
+          : value.split('/').map(encodeURIComponent).join('/');
+      }
+
+      if (segment.startsWith('$')) {
+        const value = resolveParam(segment.slice(1));
+        if (value === undefined) {
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${segment.slice(1)}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      if (segment.startsWith(':')) {
+        const optional = segment.endsWith('?');
+        const name = segment.slice(1, optional ? -1 : undefined);
+        const value = resolveParam(name);
+        if (value === undefined) {
+          if (optional) {
+            return null;
+          }
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${name}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      return segment;
+    })
+    .filter(segment => segment !== null);
+
+  return segments.join('/') || '/';
+};
+
+export interface LinkActiveOptions {
+  /**
+   * `true`: active only when the location matches the target exactly.
+   * `false`: also active when the location is nested under the target.
+   * Defaults to prefix matching, except for `/` which defaults to exact.
+   */
+  exact?: boolean;
+}
+
+type AnchorRest = Omit<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href' | 'children'
+>;
+
+export interface LinkBaseProps extends AnchorRest {
+  children?: React.ReactNode;
+  /** Hash fragment without the leading `#`. Overrides a `#hash` inside `to`. */
+  hash?: string;
+  /** Search params. Object form is passed natively to TanStack Link. */
+  search?: string | Record<string, unknown>;
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+  replace?: boolean;
+  prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  preload?: unknown;
+  activeOptions?: LinkActiveOptions;
+  /** Extra anchor props applied when the link is active. */
+  activeProps?: AnchorRest & Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export type LinkProps<TTo extends string = string> = LinkBaseProps & {
+  to: TTo;
+} & ValidateLinkTo<TTo> &
+  LinkParamsProp<LinkTargetPathname<TTo>>;
+
+const normalizeSearch = (
+  search: string | Record<string, unknown> | undefined,
+  searchFromTo: string,
+): {
+  searchString: string;
+  searchObject: Record<string, string> | undefined;
+} => {
+  if (search && typeof search === 'object') {
+    const entries = Object.entries(search).filter(
+      ([, value]) => value !== undefined && value !== null,
+    );
+    const searchObject = Object.fromEntries(
+      entries.map(([key, value]) => [key, String(value)]),
+    );
+    const params = new URLSearchParams(searchObject);
+    const serialized = params.toString();
+    return {
+      searchString: serialized ? `?${serialized}` : '',
+      searchObject,
+    };
+  }
+
+  const raw = typeof search === 'string' && search ? search : searchFromTo;
+  if (!raw) {
+    return { searchString: '', searchObject: undefined };
+  }
+
+  const searchString = raw.startsWith('?') ? raw : `?${raw}`;
+  const searchObject: Record<string, string> = {};
+  new URLSearchParams(searchString).forEach((value, key) => {
+    searchObject[key] = value;
+  });
+
+  return { searchString, searchObject };
+};
+
+const splitActiveProps = (
+  active: boolean,
+  activeProps?: LinkBaseProps['activeProps'],
+) => {
+  if (!active || !activeProps) {
+    return {};
+  }
+  return activeProps;
+};
+
+const mergeClassNames = (...values: Array<unknown>): string | undefined => {
+  const classNames = values.filter(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  );
+  return classNames.length > 0 ? classNames.join(' ') : undefined;
+};
+
+/**
+ * The standard UltraModern link: a vanilla link in every respect except that
+ * it localizes canonical, language-agnostic paths automatically.
+ *
+ * - `to` accepts canonical routes (`/talks/$slug`), optionally with `#hash`
+ *   and `?query` suffixes; both survive localization.
+ * - External URLs and bare `#hash` targets render a plain `<a>`.
+ * - Active state is language-invariant: a canonical `to` is active when the
+ *   current location matches any localized variant of that route.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/talks/$slug" params={{ slug: talk.slug }} hash="abstract" />
+ * <Link to="/platform" />            // -> /cs/platforma under cs
+ * <Link to="/#work-with-me" />       // cross-page hash, SPA navigation
+ * <Link to="https://ai.bleeding.dev" /> // external -> plain <a>
+ * ```
+ */
+export const Link = <TTo extends string = string>(
+  props: LinkProps<TTo>,
+): React.ReactElement => {
+  const {
+    to,
+    params,
+    children,
+    hash: hashProp,
+    search: searchProp,
+    hashScrollIntoView,
+    activeOptions,
+    activeProps,
+    ...rest
+  } = props as LinkBaseProps & { to: string; params?: LinkParams };
+
+  const adapter = useI18nRouterAdapter();
+  const { language, supportedLanguages, localisedUrls } = useModernI18n();
+
+  const config: LocalizedPathsConfig = {
+    languages: supportedLanguages,
+    localisedUrls,
+  };
+
+  const isExternal = EXTERNAL_TARGET_RE.test(to);
+  const isBareHash = to.startsWith('#');
+
+  const target = useMemo(() => {
+    if (isExternal || isBareHash) {
+      return null;
+    }
+
+    const {
+      pathname,
+      search: searchFromTo,
+      hash: hashFromTo,
+    } = splitUrlTarget(to);
+    const interpolated = interpolateRouteParams(pathname || '/', params);
+
+    const firstSegment = interpolated.split('/').filter(Boolean)[0];
+    if (firstSegment && supportedLanguages.includes(firstSegment)) {
+      warnOnce(
+        `lang-prefix:${to}`,
+        `[plugin-i18n] <Link to="${to}"> starts with a language prefix. ` +
+          'Write language-agnostic canonical paths; the Link localizes them automatically.',
+      );
+    }
+
+    const localizedPathname = buildLocalizedUrl(
+      interpolated,
+      language,
+      supportedLanguages,
+      localisedUrls,
+    );
+    const hash = hashProp ?? (hashFromTo ? hashFromTo.slice(1) : '');
+    const { searchString, searchObject } = normalizeSearch(
+      searchProp,
+      searchFromTo,
+    );
+
+    return {
+      canonicalPathname: interpolated,
+      localizedPathname,
+      hash,
+      searchString,
+      searchObject,
+      href: `${localizedPathname}${searchString}${hash ? `#${hash}` : ''}`,
+    };
+  }, [
+    to,
+    params,
+    hashProp,
+    searchProp,
+    isExternal,
+    isBareHash,
+    language,
+    supportedLanguages,
+    localisedUrls,
+  ]);
+
+  const isActive = useMemo(() => {
+    if (!target || !adapter.location) {
+      return false;
+    }
+
+    const current = canonicalPath(adapter.location.pathname, config);
+    const targetCanonical = canonicalPath(target.canonicalPathname, config);
+    const exact = activeOptions?.exact ?? targetCanonical === '/';
+
+    if (current === targetCanonical) {
+      return true;
+    }
+    if (exact) {
+      return false;
+    }
+    return current.startsWith(
+      targetCanonical === '/' ? '/' : `${targetCanonical}/`,
+    );
+  }, [
+    target,
+    adapter.location,
+    activeOptions?.exact,
+    supportedLanguages,
+    localisedUrls,
+  ]);
+
+  const resolvedActiveProps = splitActiveProps(isActive, activeProps);
+  const activeAttributes = isActive
+    ? {
+        'data-status': 'active',
+        'aria-current': (rest['aria-current'] ??
+          resolvedActiveProps['aria-current'] ??
+          'page') as React.AriaAttributes['aria-current'],
+      }
+    : {};
+
+  // External targets and same-page anchors are vanilla links.
+  if (!target) {
+    const {
+      prefetch: _prefetch,
+      preload: _preload,
+      replace: _replace,
+      ...anchorProps
+    } = rest;
+
+    return (
+      <a href={to} {...anchorProps}>
+        {children}
+      </a>
+    );
+  }
+
+  const { Link: RouterLink, hasRouter, framework } = adapter;
+
+  if (!hasRouter || !RouterLink) {
+    const {
+      prefetch: _prefetch,
+      preload: _preload,
+      replace: _replace,
+      ...anchorProps
+    } = rest;
+    const {
+      className: activeClassName,
+      style: activeStyle,
+      ...activeRest
+    } = resolvedActiveProps;
+
+    return (
+      <a
+        href={target.href}
+        {...anchorProps}
+        {...activeRest}
+        {...activeAttributes}
+        className={mergeClassNames(rest.className, activeClassName)}
+        style={{
+          ...(rest.style as React.CSSProperties | undefined),
+          ...(activeStyle as React.CSSProperties | undefined),
+        }}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  const {
+    className: activeClassName,
+    style: activeStyle,
+    ...activeRest
+  } = resolvedActiveProps;
+  const mergedClassName = mergeClassNames(rest.className, activeClassName);
+  const mergedStyle = {
+    ...(rest.style as React.CSSProperties | undefined),
+    ...(activeStyle as React.CSSProperties | undefined),
+  };
+
+  if (framework === 'tanstack') {
+    // Pass hash/search natively: string-concatenated targets silently break
+    // TanStack navigation.
+    return (
+      <RouterLink
+        to={target.localizedPathname}
+        {...(target.searchObject ? { search: target.searchObject } : {})}
+        {...(target.hash ? { hash: target.hash } : {})}
+        {...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView })}
+        {...rest}
+        {...activeRest}
+        {...activeAttributes}
+        className={mergedClassName}
+        style={mergedStyle}
+      >
+        {children}
+      </RouterLink>
+    );
+  }
+
+  return (
+    <RouterLink
+      to={target.href}
+      {...rest}
+      {...activeRest}
+      {...activeAttributes}
+      className={mergedClassName}
+      style={mergedStyle}
+    >
+      {children}
+    </RouterLink>
+  );
+};
+
+export default Link;

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/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;