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

package/src/runtime/localizedPaths.ts

@@ -0,0 +1,118 @@
+import { useMemo } from 'react';
+import type { LocalisedUrlsOption } from '../shared/localisedUrls';
+import {
+  resolveCanonicalLocalisedPath,
+  resolveLocalisedUrlsConfig,
+} 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 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}`;
+};
+
+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/utils.ts

@@ -45,25 +45,44 @@ 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,
 ): 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;
+      : pathname || '/';
   const resolvedPath = localisedUrlsConfig.enabled
     ? resolveLocalisedPath(
         pathWithoutLanguage,
@@ -74,7 +93,7 @@ export const buildLocalizedUrl = (
     : pathWithoutLanguage;
   const resolvedSegments = resolvedPath.split('/').filter(Boolean);
 
-  return `/${[language, ...resolvedSegments].join('/')}`;
+  return `/${[language, ...resolvedSegments].join('/')}${search}${hash}`;
 };
 
 export const detectLanguageFromPath = (

package/src/shared/localisedUrls.ts

@@ -224,7 +224,7 @@ const transformLocalisedRoute = (
     languages,
     localisedUrlEntry,
   ).map((localisedPath, index) =>
-    cloneRouteWithLocalisedPath(baseRoute, localisedPath, index),
+    cloneRouteWithLocalisedPath(baseRoute, localisedPath, index, canonicalPath),
   );
 };
 
@@ -251,6 +251,7 @@ const cloneRouteWithLocalisedPath = (
   route: NestedRouteForCli | PageRoute,
   path: string,
   index: number,
+  canonicalPath: string,
 ): NestedRouteForCli | PageRoute => {
   const leadingLocaleParam = getLeadingLocaleParam(route.path);
   const localisedPath = leadingLocaleParam
@@ -260,6 +261,10 @@ const cloneRouteWithLocalisedPath = (
     ...route,
     path: localisedPath,
   } as NestedRouteForCli | PageRoute;
+  // Language-agnostic source pattern; lets downstream codegen collapse the
+  // localized physical variants back to one canonical route.
+  (routeWithPath as { modernCanonicalPath?: string }).modernCanonicalPath =
+    canonicalPath;
 
   return index === 0
     ? routeWithPath
@@ -324,7 +329,7 @@ const compilePathPattern = (pattern: string) => {
   };
 };
 
-const matchPathPattern = (
+export const matchPathPattern = (
   pathname: string,
   pattern: string,
 ): Record<string, string> | null => {
@@ -340,7 +345,7 @@ const matchPathPattern = (
   }, {});
 };
 
-const buildPathFromPattern = (
+export const buildPathFromPattern = (
   pattern: string,
   params: Record<string, string>,
 ): string => {
@@ -370,6 +375,22 @@ export const resolveLocalisedPath = (
 ): string => {
   const normalizedPathname = normalisePathPattern(pathname);
 
+  // Canonical keys take precedence: authors write language-agnostic paths,
+  // which are the map keys, even when no language pattern equals the key.
+  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) {
@@ -391,3 +412,42 @@ export const resolveLocalisedPath = (
 
   return normalizedPathname;
 };
+
+/**
+ * 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 const resolveCanonicalLocalisedPath = (
+  pathname: string,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+): string => {
+  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;
+};