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

package/dist/esm-node/runtime/I18nLink.mjs

@@ -1,24 +1,14 @@
 import "node:module";
 import { jsx } from "react/jsx-runtime";
-import { useModernI18n } from "./context.mjs";
-import { useI18nRouterAdapter } from "./routerAdapter.mjs";
-import { buildLocalizedUrl } from "./utils.mjs";
+import { Link } from "./Link.mjs";
+let warnedDeprecation = false;
 const I18nLink = ({ to, children, ...props })=>{
-    const { Link, params, hasRouter } = useI18nRouterAdapter();
-    const { language, supportedLanguages, localisedUrls } = useModernI18n();
-    const currentLang = language;
-    const localizedTo = buildLocalizedUrl(to, currentLang, supportedLanguages, localisedUrls);
-    if ('development' === process.env.NODE_ENV && hasRouter && !params.lang) 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 /*#__PURE__*/ jsx("a", {
-            href: localizedTo,
-            ...anchorProps,
-            children: children
-        });
+    if ('development' === process.env.NODE_ENV && !warnedDeprecation) {
+        warnedDeprecation = true;
+        console.warn("[plugin-i18n] I18nLink is deprecated. Import { Link } from '@modern-js/plugin-i18n/runtime' instead — it accepts the same language-agnostic `to` values.");
     }
     return /*#__PURE__*/ jsx(Link, {
-        to: localizedTo,
+        to: to,
         ...props,
         children: children
     });

package/dist/esm-node/runtime/Link.mjs

@@ -0,0 +1,210 @@
+import "node:module";
+import { jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useModernI18n } from "./context.mjs";
+import { canonicalPath } from "./localizedPaths.mjs";
+import { useI18nRouterAdapter } from "./routerAdapter.mjs";
+import { buildLocalizedUrl, splitUrlTarget } from "./utils.mjs";
+const EXTERNAL_TARGET_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const warnedTargets = new Set();
+const warnOnce = (key, message)=>{
+    if ('development' !== process.env.NODE_ENV || warnedTargets.has(key)) return;
+    warnedTargets.add(key);
+    console.warn(message);
+};
+const interpolateRouteParams = (pathname, params)=>{
+    if (!/[$:*{]/.test(pathname)) return pathname;
+    const resolveParam = (name)=>{
+        const value = params?.[name];
+        return void 0 === value ? void 0 : 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 void 0 === value ? null : encodeURIComponent(value);
+        }
+        if ('$' === segment || '*' === segment) {
+            const value = resolveParam('_splat') ?? resolveParam('*');
+            return void 0 === value ? null : value.split('/').map(encodeURIComponent).join('/');
+        }
+        if (segment.startsWith('$')) {
+            const value = resolveParam(segment.slice(1));
+            if (void 0 === value) {
+                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 : void 0);
+            const value = resolveParam(name);
+            if (void 0 === value) {
+                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)=>null !== segment);
+    return segments.join('/') || '/';
+};
+const normalizeSearch = (search, searchFromTo)=>{
+    if (search && 'object' == typeof search) {
+        const entries = Object.entries(search).filter(([, value])=>null != value);
+        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 = 'string' == typeof search && search ? search : searchFromTo;
+    if (!raw) return {
+        searchString: '',
+        searchObject: void 0
+    };
+    const searchString = raw.startsWith('?') ? raw : `?${raw}`;
+    const searchObject = {};
+    new URLSearchParams(searchString).forEach((value, key)=>{
+        searchObject[key] = value;
+    });
+    return {
+        searchString,
+        searchObject
+    };
+};
+const splitActiveProps = (active, activeProps)=>{
+    if (!active || !activeProps) return {};
+    return activeProps;
+};
+const mergeClassNames = (...values)=>{
+    const classNames = values.filter((value)=>'string' == typeof value && value.length > 0);
+    return classNames.length > 0 ? classNames.join(' ') : void 0;
+};
+const Link = (props)=>{
+    const { to, params, children, hash: hashProp, search: searchProp, hashScrollIntoView, activeOptions, activeProps, ...rest } = props;
+    const adapter = useI18nRouterAdapter();
+    const { language, supportedLanguages, localisedUrls } = useModernI18n();
+    const config = {
+        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'
+    } : {};
+    if (!target) {
+        const { prefetch: _prefetch, preload: _preload, replace: _replace, ...anchorProps } = rest;
+        return /*#__PURE__*/ jsx("a", {
+            href: to,
+            ...anchorProps,
+            children: children
+        });
+    }
+    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 /*#__PURE__*/ jsx("a", {
+            href: target.href,
+            ...anchorProps,
+            ...activeRest,
+            ...activeAttributes,
+            className: mergeClassNames(rest.className, activeClassName),
+            style: {
+                ...rest.style,
+                ...activeStyle
+            },
+            children: children
+        });
+    }
+    const { className: activeClassName, style: activeStyle, ...activeRest } = resolvedActiveProps;
+    const mergedClassName = mergeClassNames(rest.className, activeClassName);
+    const mergedStyle = {
+        ...rest.style,
+        ...activeStyle
+    };
+    if ('tanstack' === framework) return /*#__PURE__*/ jsx(RouterLink, {
+        to: target.localizedPathname,
+        ...target.searchObject ? {
+            search: target.searchObject
+        } : {},
+        ...target.hash ? {
+            hash: target.hash
+        } : {},
+        ...void 0 === hashScrollIntoView ? {} : {
+            hashScrollIntoView
+        },
+        ...rest,
+        ...activeRest,
+        ...activeAttributes,
+        className: mergedClassName,
+        style: mergedStyle,
+        children: children
+    });
+    return /*#__PURE__*/ jsx(RouterLink, {
+        to: target.href,
+        ...rest,
+        ...activeRest,
+        ...activeAttributes,
+        className: mergedClassName,
+        style: mergedStyle,
+        children: children
+    });
+};
+const runtime_Link = Link;
+export default runtime_Link;
+export { Link, interpolateRouteParams };

package/dist/esm-node/runtime/canonicalRoutes.mjs

@@ -0,0 +1 @@
+import "node:module";

package/dist/esm-node/runtime/index.mjs

@@ -13,7 +13,7 @@ import { detectLanguageWithPriority, exportServerLngToWindow, mergeDetectionOpti
 import { useI18nextLanguageDetector } from "./i18n/detection/middleware.mjs";
 import { getI18nextInstanceForProvider } from "./i18n/instance.mjs";
 import { changeI18nLanguage, ensureLanguageMatch, initializeI18nInstance, setupClonedInstance } from "./i18n/utils.mjs";
-import { getPathname } from "./utils.mjs";
+import { buildLocalizedUrl, getPathname, splitUrlTarget } from "./utils.mjs";
 import "./types.mjs";
 const i18nPlugin = (options)=>({
         name: '@modern-js/plugin-i18n',
@@ -137,5 +137,7 @@ const i18nPlugin = (options)=>({
     });
 const runtime = i18nPlugin;
 export { I18nLink } from "./I18nLink.mjs";
+export { Link } from "./Link.mjs";
+export { canonicalPath, localizePath, useLocalizedLocation, useLocalizedPaths } from "./localizedPaths.mjs";
 export default runtime;
-export { i18nPlugin, useModernI18n };
+export { buildLocalizedUrl, i18nPlugin, splitUrlTarget, useModernI18n };

package/dist/esm-node/runtime/localizedPaths.mjs

@@ -0,0 +1,59 @@
+import "node:module";
+import { useMemo } from "react";
+import { resolveCanonicalLocalisedPath, resolveLocalisedUrlsConfig } from "../shared/localisedUrls.mjs";
+import { useModernI18n } from "./context.mjs";
+import { useI18nRouterAdapter } from "./routerAdapter.mjs";
+import { buildLocalizedUrl, splitUrlTarget } from "./utils.mjs";
+const localizePath = (pathname, language, config)=>buildLocalizedUrl(pathname, language, config.languages, config.localisedUrls);
+const canonicalPath = (target, config)=>{
+    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;
+    return `${resolvedPath}${search}${hash}`;
+};
+const useLocalizedPaths = ()=>{
+    const { supportedLanguages, localisedUrls } = useModernI18n();
+    return useMemo(()=>{
+        const config = {
+            languages: supportedLanguages,
+            localisedUrls
+        };
+        return {
+            localizePath: (pathname, language)=>localizePath(pathname, language, config),
+            canonicalPath: (pathname)=>canonicalPath(pathname, config)
+        };
+    }, [
+        supportedLanguages,
+        localisedUrls
+    ]);
+};
+const useLocalizedLocation = ()=>{
+    const { language, supportedLanguages, localisedUrls } = useModernI18n();
+    const { location } = useI18nRouterAdapter();
+    const pathname = location?.pathname ?? '/';
+    const search = location?.search ?? '';
+    const hash = location?.hash ?? '';
+    return useMemo(()=>{
+        const config = {
+            languages: supportedLanguages,
+            localisedUrls
+        };
+        const alternates = {};
+        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
+    ]);
+};
+export { canonicalPath, localizePath, useLocalizedLocation, useLocalizedPaths };

package/dist/esm-node/runtime/utils.mjs

@@ -17,16 +17,30 @@ const getLanguageFromPath = (pathname, languages, fallbackLanguage)=>{
     if (languages.includes(firstSegment)) return firstSegment;
     return fallbackLanguage;
 };
-const buildLocalizedUrl = (pathname, language, languages, localisedUrls)=>{
+const splitUrlTarget = (target)=>{
+    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
+    };
+};
+const buildLocalizedUrl = (target, language, languages, localisedUrls)=>{
+    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 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('/')}`;
+    ].join('/')}${search}${hash}`;
 };
 const detectLanguageFromPath = (pathname, languages, localePathRedirect)=>{
     if (!localePathRedirect) return {
@@ -54,4 +68,4 @@ const shouldIgnoreRedirect = (pathname, languages, ignoreRedirectRoutes)=>{
     if ('function' == typeof ignoreRedirectRoutes) return ignoreRedirectRoutes(normalizedPath);
     return ignoreRedirectRoutes.some((pattern)=>normalizedPath === pattern || normalizedPath.startsWith(`${pattern}/`));
 };
-export { buildLocalizedUrl, detectLanguageFromPath, getEntryPath, getLanguageFromPath, getPathname, shouldIgnoreRedirect };
+export { buildLocalizedUrl, detectLanguageFromPath, getEntryPath, getLanguageFromPath, getPathname, shouldIgnoreRedirect, splitUrlTarget };

package/dist/esm-node/shared/localisedUrls.mjs

@@ -101,7 +101,7 @@ const transformLocalisedRoute = (route, parentCanonicalPath, parentLocalisedPath
     if (!localisedUrlEntry) return [
         baseRoute
     ];
-    return getLocalisedRoutePaths(canonicalPath, parentLocalisedPaths, languages, localisedUrlEntry).map((localisedPath, index)=>cloneRouteWithLocalisedPath(baseRoute, localisedPath, index));
+    return getLocalisedRoutePaths(canonicalPath, parentLocalisedPaths, languages, localisedUrlEntry).map((localisedPath, index)=>cloneRouteWithLocalisedPath(baseRoute, localisedPath, index, canonicalPath));
 };
 const legalRouteIdPart = (value)=>value.replace(/[^a-zA-Z0-9_$-]+/g, '_').replace(/^_+|_+$/g, '') || 'index';
 const suffixRouteIds = (route, suffix)=>{
@@ -116,13 +116,14 @@ const suffixRouteIds = (route, suffix)=>{
         } : {}
     };
 };
-const cloneRouteWithLocalisedPath = (route, path, index)=>{
+const cloneRouteWithLocalisedPath = (route, path, index, canonicalPath)=>{
     const leadingLocaleParam = getLeadingLocaleParam(route.path);
     const localisedPath = leadingLocaleParam ? normaliseRoutePath(`${leadingLocaleParam}/${path}`) : path;
     const routeWithPath = {
         ...route,
         path: localisedPath
     };
+    routeWithPath.modernCanonicalPath = canonicalPath;
     return 0 === index ? routeWithPath : suffixRouteIds(routeWithPath, legalRouteIdPart(localisedPath));
 };
 const applyLocalisedUrlsToRoutes = (routes, languages, localisedUrls)=>{
@@ -178,6 +179,12 @@ const buildPathFromPattern = (pattern, params)=>{
 };
 const resolveLocalisedPath = (pathname, targetLanguage, languages, localisedUrls)=>{
     const normalizedPathname = normalisePathPattern(pathname);
+    for (const [canonicalPattern, localisedUrlEntry] of Object.entries(localisedUrls)){
+        const targetPattern = localisedUrlEntry[targetLanguage];
+        if (!targetPattern) continue;
+        const params = matchPathPattern(normalizedPathname, canonicalPattern);
+        if (params) return buildPathFromPattern(targetPattern, params);
+    }
     for (const localisedUrlEntry of Object.values(localisedUrls)){
         const targetPattern = localisedUrlEntry[targetLanguage];
         if (targetPattern) for (const language of languages){
@@ -189,4 +196,18 @@ const resolveLocalisedPath = (pathname, targetLanguage, languages, localisedUrls
     }
     return normalizedPathname;
 };
-export { applyLocalisedUrlsToRoutes, normalisePathPattern, resolveLocalisedPath, resolveLocalisedUrlsConfig, validateLocalisedUrls };
+const resolveCanonicalLocalisedPath = (pathname, languages, localisedUrls)=>{
+    const normalizedPathname = normalisePathPattern(pathname);
+    for (const [canonicalPattern, localisedUrlEntry] of Object.entries(localisedUrls)){
+        const canonicalParams = matchPathPattern(normalizedPathname, canonicalPattern);
+        if (canonicalParams) return buildPathFromPattern(canonicalPattern, canonicalParams);
+        for (const language of languages){
+            const sourcePattern = localisedUrlEntry[language];
+            if (!sourcePattern) continue;
+            const params = matchPathPattern(normalizedPathname, sourcePattern);
+            if (params) return buildPathFromPattern(canonicalPattern, params);
+        }
+    }
+    return normalizedPathname;
+};
+export { applyLocalisedUrlsToRoutes, buildPathFromPattern, matchPathPattern, normalisePathPattern, resolveCanonicalLocalisedPath, resolveLocalisedPath, resolveLocalisedUrlsConfig, validateLocalisedUrls };

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

@@ -5,19 +5,10 @@ export interface I18nLinkProps {
     [key: string]: any;
 }
 /**
- * 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 declare const I18nLink: React.FC<I18nLinkProps>;
 export default I18nLink;

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

@@ -0,0 +1,56 @@
+import type React from 'react';
+import type { LinkParamsProp, LinkTargetPathname, ValidateLinkTo } from './canonicalRoutes';
+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 declare const interpolateRouteParams: (pathname: string, params?: LinkParams) => string;
+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>>;
+/**
+ * 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 declare const Link: <TTo extends string = string>(props: LinkProps<TTo>) => React.ReactElement;
+export default Link;

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

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+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>;
+};
+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/utils.d.ts

@@ -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?: boolean | LocalisedUrlsMap) => string;
 export declare const detectLanguageFromPath: (pathname: string, languages: string[], localePathRedirect: boolean) => {
     detected: boolean;
     language?: string;

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

@@ -10,4 +10,12 @@ 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;