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

package/src/shared/localisedUrls.ts

@@ -11,19 +11,28 @@ export interface ResolvedLocalisedUrlsConfig {
 
 const LOCALE_PARAM_NAMES = new Set(['lang', 'locale', 'language']);
 
-export const normalisePathPattern = (path: string): string => {
+const normaliseSlashes = (path: string): string => {
   const withoutDuplicateSlashes = path.replace(/\/+/g, '/');
   const withLeadingSlash = withoutDuplicateSlashes.startsWith('/')
     ? withoutDuplicateSlashes
     : `/${withoutDuplicateSlashes}`;
-  const withoutTrailingSlash =
-    withLeadingSlash.length > 1
-      ? withLeadingSlash.replace(/\/+$/, '')
-      : withLeadingSlash;
 
-  return withoutTrailingSlash.replace(/\[(.+?)\]/g, ':$1');
+  return withLeadingSlash.length > 1
+    ? withLeadingSlash.replace(/\/+$/, '')
+    : withLeadingSlash;
 };
 
+export const normalisePathPattern = (path: string): string =>
+  normaliseSlashes(path).replace(/\[(.+?)\]/g, ':$1');
+
+/**
+ * Normalise a concrete request pathname: slash cleanup only. Unlike
+ * {@link normalisePathPattern} it must not rewrite literal `[x]` segments to
+ * `:x` params — pathnames are values, not patterns.
+ */
+export const normalisePathname = (pathname: string): string =>
+  normaliseSlashes(pathname);
+
 const normaliseRoutePath = (path: string): string => {
   const normalized = normalisePathPattern(path);
   return normalized === '/' ? '' : normalized.slice(1);
@@ -63,18 +72,21 @@ const getLeadingLocaleParam = (path?: string): string | null => {
   return getLocaleParamSegment(segments[0] || '');
 };
 
+/**
+ * Localised URLs are strictly opt-in: only an explicit, non-empty map enables
+ * route expansion and validation. `true`, `false`, an empty map and absence
+ * all resolve to disabled, so upstream-style configs (`localePathRedirect` +
+ * `languages` without a map) keep plain locale-prefix behavior instead of
+ * failing the build for every route missing from a map they never wrote.
+ */
 export const resolveLocalisedUrlsConfig = (
   option: LocalisedUrlsOption | undefined,
 ): ResolvedLocalisedUrlsConfig => {
-  if (option === false) {
-    return { enabled: false, map: {} };
-  }
-
-  if (option && typeof option === 'object') {
+  if (option && typeof option === 'object' && Object.keys(option).length > 0) {
     return { enabled: true, map: option };
   }
 
-  return { enabled: true, map: {} };
+  return { enabled: false, map: {} };
 };
 
 const isLocaleParamPath = (path?: string): boolean => {
@@ -303,9 +315,22 @@ const escapeRegExp = (value: string): string =>
 const getParamName = (segment: string): string =>
   segment.slice(1).replace(/\?$/, '');
 
-const compilePathPattern = (pattern: string) => {
+interface CompiledPathPattern {
+  names: string[];
+  regexp: RegExp;
+}
+
+const compiledPathPatternCache = new Map<string, CompiledPathPattern>();
+
+const compilePathPattern = (pattern: string): CompiledPathPattern => {
+  const normalizedPattern = normalisePathPattern(pattern);
+  const cached = compiledPathPatternCache.get(normalizedPattern);
+  if (cached) {
+    return cached;
+  }
+
   const names: string[] = [];
-  const segments = normalisePathPattern(pattern).split('/').filter(Boolean);
+  const segments = normalizedPattern.split('/').filter(Boolean);
   const source = segments
     .map(segment => {
       if (segment.startsWith(':')) {
@@ -323,10 +348,76 @@ const compilePathPattern = (pattern: string) => {
     })
     .join('');
 
-  return {
+  const compiled = {
     names,
     regexp: new RegExp(`^${source || '/'}$`),
   };
+  compiledPathPatternCache.set(normalizedPattern, compiled);
+
+  return compiled;
+};
+
+const getPatternSpecificity = (pattern: string) => {
+  const segments = normalisePathPattern(pattern).split('/').filter(Boolean);
+  let staticSegments = 0;
+  let dynamicSegments = 0;
+  let splatSegments = 0;
+
+  for (const segment of segments) {
+    if (segment === '*') {
+      splatSegments++;
+    } else if (segment.startsWith(':')) {
+      dynamicSegments++;
+    } else {
+      staticSegments++;
+    }
+  }
+
+  return {
+    staticSegments,
+    dynamicSegments,
+    splatSegments,
+    totalSegments: segments.length,
+  };
+};
+
+const comparePatternSpecificity = (left: string, right: string): number => {
+  const a = getPatternSpecificity(left);
+  const b = getPatternSpecificity(right);
+
+  return (
+    b.staticSegments - a.staticSegments ||
+    b.totalSegments - a.totalSegments ||
+    a.splatSegments - b.splatSegments ||
+    a.dynamicSegments - b.dynamicSegments
+  );
+};
+
+const sortPatternsBySpecificity = <T extends { pattern: string }>(
+  patterns: T[],
+): T[] =>
+  patterns
+    .map((pattern, index) => ({ pattern, index }))
+    .sort(
+      (left, right) =>
+        comparePatternSpecificity(
+          left.pattern.pattern,
+          right.pattern.pattern,
+        ) || left.index - right.index,
+    )
+    .map(({ pattern }) => pattern);
+
+/**
+ * `decodeURIComponent` throws `URIError` on malformed percent-encoding
+ * (e.g. `%E0%A4%A`), which attacker-controlled request URLs can carry.
+ * Treat such segments as undecodable instead of throwing.
+ */
+const decodePathParam = (value: string): string | null => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
 };
 
 export const matchPathPattern = (
@@ -334,15 +425,22 @@ export const matchPathPattern = (
   pattern: string,
 ): Record<string, string> | null => {
   const { names, regexp } = compilePathPattern(pattern);
-  const match = regexp.exec(normalisePathPattern(pathname));
+  const match = regexp.exec(normalisePathname(pathname));
   if (!match) {
     return null;
   }
 
-  return names.reduce<Record<string, string>>((params, name, index) => {
-    params[name] = decodeURIComponent(match[index + 1] || '');
-    return params;
-  }, {});
+  const params: Record<string, string> = {};
+  for (let index = 0; index < names.length; index++) {
+    const decoded = decodePathParam(match[index + 1] || '');
+    if (decoded === null) {
+      // Malformed encoding cannot identify a localised route: no match.
+      return null;
+    }
+    params[names[index]] = decoded;
+  }
+
+  return params;
 };
 
 export const buildPathFromPattern = (
@@ -373,13 +471,21 @@ export const resolveLocalisedPath = (
   languages: string[],
   localisedUrls: LocalisedUrlsMap,
 ): string => {
-  const normalizedPathname = normalisePathPattern(pathname);
+  const normalizedPathname = normalisePathname(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 canonicalCandidates = sortPatternsBySpecificity(
+    Object.entries(localisedUrls).map(
+      ([canonicalPattern, localisedUrlEntry]) => ({
+        pattern: canonicalPattern,
+        canonicalPattern,
+        localisedUrlEntry,
+      }),
+    ),
+  );
+
+  for (const { canonicalPattern, localisedUrlEntry } of canonicalCandidates) {
     const targetPattern = localisedUrlEntry[targetLanguage];
     if (!targetPattern) {
       continue;
@@ -391,22 +497,30 @@ export const resolveLocalisedPath = (
     }
   }
 
-  for (const localisedUrlEntry of Object.values(localisedUrls)) {
-    const targetPattern = localisedUrlEntry[targetLanguage];
-    if (!targetPattern) {
-      continue;
-    }
-
-    for (const language of languages) {
-      const sourcePattern = localisedUrlEntry[language];
-      if (!sourcePattern) {
-        continue;
+  const localisedCandidates = sortPatternsBySpecificity(
+    Object.values(localisedUrls).flatMap(localisedUrlEntry => {
+      const targetPattern = localisedUrlEntry[targetLanguage];
+      if (!targetPattern) {
+        return [];
       }
 
-      const params = matchPathPattern(normalizedPathname, sourcePattern);
-      if (params) {
-        return buildPathFromPattern(targetPattern, params);
-      }
+      return languages
+        .map(language => localisedUrlEntry[language])
+        .filter((sourcePattern): sourcePattern is string =>
+          Boolean(sourcePattern),
+        )
+        .map(sourcePattern => ({
+          pattern: sourcePattern,
+          sourcePattern,
+          targetPattern,
+        }));
+    }),
+  );
+
+  for (const { sourcePattern, targetPattern } of localisedCandidates) {
+    const params = matchPathPattern(normalizedPathname, sourcePattern);
+    if (params) {
+      return buildPathFromPattern(targetPattern, params);
     }
   }
 
@@ -423,11 +537,19 @@ export const resolveCanonicalLocalisedPath = (
   languages: string[],
   localisedUrls: LocalisedUrlsMap,
 ): string => {
-  const normalizedPathname = normalisePathPattern(pathname);
+  const normalizedPathname = normalisePathname(pathname);
+
+  const canonicalCandidates = sortPatternsBySpecificity(
+    Object.entries(localisedUrls).map(
+      ([canonicalPattern, localisedUrlEntry]) => ({
+        pattern: canonicalPattern,
+        canonicalPattern,
+        localisedUrlEntry,
+      }),
+    ),
+  );
 
-  for (const [canonicalPattern, localisedUrlEntry] of Object.entries(
-    localisedUrls,
-  )) {
+  for (const { canonicalPattern, localisedUrlEntry } of canonicalCandidates) {
     const canonicalParams = matchPathPattern(
       normalizedPathname,
       canonicalPattern,
@@ -451,3 +573,51 @@ export const resolveCanonicalLocalisedPath = (
 
   return normalizedPathname;
 };
+
+const stripLanguagePrefix = (pathname: string, languages: string[]): string => {
+  const segments = pathname.split('/').filter(Boolean);
+
+  if (segments.length > 0 && languages.includes(segments[0])) {
+    return `/${segments.slice(1).join('/')}`;
+  }
+
+  return pathname || '/';
+};
+
+export const localiseTargetPathname = (
+  pathname: string,
+  language: string,
+  languages: string[],
+  localisedUrls?: LocalisedUrlsOption,
+): string => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname, languages);
+  const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
+  const resolvedPath = localisedUrlsConfig.enabled
+    ? resolveLocalisedPath(
+        pathWithoutLanguage,
+        language,
+        languages,
+        localisedUrlsConfig.map,
+      )
+    : pathWithoutLanguage;
+  const resolvedSegments = resolvedPath.split('/').filter(Boolean);
+
+  return `/${[language, ...resolvedSegments].join('/')}`;
+};
+
+export const canonicalTargetPathname = (
+  pathname: string,
+  languages: string[],
+  localisedUrls?: LocalisedUrlsOption,
+): string => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname, languages);
+  const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
+
+  return localisedUrlsConfig.enabled
+    ? resolveCanonicalLocalisedPath(
+        pathWithoutLanguage,
+        languages,
+        localisedUrlsConfig.map,
+      )
+    : pathWithoutLanguage;
+};

package/src/shared/type.ts

@@ -14,12 +14,14 @@ export interface BaseLocaleDetectionOptions {
   /**
    * 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.
+   * - non-empty object: map canonical route paths to every configured
+   *   language; route generation then validates that every localisable route
+   *   path has entries for all configured languages.
+   * - absent / `false` / `true` / empty object: keep only locale-prefix
+   *   behavior (`/en/about`).
    *
-   * Defaults to `true` when `localePathRedirect` is enabled, so route
-   * generation validates that every localisable route path has entries for all
-   * configured languages.
+   * Strictly opt-in: without a map, `localePathRedirect` + `languages` behave
+   * exactly like upstream Modern.js.
    */
   localisedUrls?: LocalisedUrlsOption;
 }

package/tests/backendDefaults.test.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, test } from '@rstest/core';
+import {
+  DEFAULT_I18NEXT_BACKEND_OPTIONS,
+  resolveDefaultLocalesDir,
+} from '../src/runtime/i18n/backend/defaults.node';
+
+const makeTempDir = (...dirs: string[]): string => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'i18n-defaults-'));
+  for (const dir of dirs) {
+    fs.mkdirSync(path.join(root, dir), { recursive: true });
+  }
+  return root;
+};
+
+describe('node backend default loadPath', () => {
+  const originalCwd = process.cwd();
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+  });
+
+  test('prefers the project-root ./locales convention (the detection root)', () => {
+    const root = makeTempDir('locales', 'config/public/locales');
+    expect(resolveDefaultLocalesDir(root)).toBe('./locales');
+  });
+
+  test('falls back to ./config/public/locales when only it exists', () => {
+    const root = makeTempDir('config/public/locales');
+    expect(resolveDefaultLocalesDir(root)).toBe('./config/public/locales');
+  });
+
+  test('defaults to ./locales when neither conventional directory exists', () => {
+    const root = makeTempDir();
+    expect(resolveDefaultLocalesDir(root)).toBe('./locales');
+  });
+
+  test('DEFAULT_I18NEXT_BACKEND_OPTIONS resolves against the working directory', () => {
+    const root = makeTempDir('locales');
+    process.chdir(root);
+
+    expect(DEFAULT_I18NEXT_BACKEND_OPTIONS.loadPath).toBe(
+      './locales/{{lng}}/{{ns}}.json',
+    );
+    expect(DEFAULT_I18NEXT_BACKEND_OPTIONS.addPath).toBe(
+      './locales/{{lng}}/{{ns}}.json',
+    );
+  });
+});

package/tests/i18nUtils.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, test } from '@rstest/core';
 import type { I18nInstance } from '../src/runtime/i18n';
-import { DEFAULT_I18NEXT_BACKEND_OPTIONS as NODE_DEFAULT_I18NEXT_BACKEND_OPTIONS } from '../src/runtime/i18n/backend/defaults.node';
+import {
+  DEFAULT_I18NEXT_BACKEND_OPTIONS as NODE_DEFAULT_I18NEXT_BACKEND_OPTIONS,
+  resolveDefaultLocalesDir,
+} from '../src/runtime/i18n/backend/defaults.node';
 import { initializeI18nInstance } from '../src/runtime/i18n/utils';
 
 function createBackendI18nInstance(): I18nInstance {
@@ -17,9 +20,13 @@ function createBackendI18nInstance(): I18nInstance {
 }
 
 describe('i18n runtime utils', () => {
-  test('uses the generated public locale directory for node fs backend defaults', () => {
+  test('node fs backend defaults follow the detected locales directory', () => {
+    // The default must match whichever conventional root exists at runtime
+    // (./locales first, then ./config/public/locales), mirroring the CLI
+    // plugin's detectLocalesDirectory. Detailed precedence cases live in
+    // tests/backendDefaults.test.ts.
     expect(NODE_DEFAULT_I18NEXT_BACKEND_OPTIONS.loadPath).toBe(
-      './config/public/locales/{{lng}}/{{ns}}.json',
+      `${resolveDefaultLocalesDir()}/{{lng}}/{{ns}}.json`,
     );
   });
 

package/tests/link.test.tsx

@@ -46,10 +46,13 @@ const requestContext = {
 
 const capturedLinkProps: any[] = [];
 
+// Mirrors the real TanStack Link contract: it consumes its own props
+// (`preload`, `search`, `hash`, ...) and spreads everything else onto the
+// anchor. Deliberately does NOT strip `prefetch` — TanStack has no such prop,
+// so a forwarded `prefetch` would leak into the DOM and fail assertions.
 const TanstackLink = ({ to, children, ...props }: any) => {
   capturedLinkProps.push({ to, ...props });
   const {
-    prefetch: _prefetch,
     preload: _preload,
     search: _search,
     hash: _hash,
@@ -378,6 +381,53 @@ describe('framework Link', () => {
     expect(link?.hasAttribute('prefetch')).toBe(false);
   });
 
+  test('maps prefetch to the TanStack preload prop', async () => {
+    const router = createTanstackRouter('/en/products', 'en');
+    rendered = await renderWithRuntime(
+      <ModernI18nProvider value={providerValue('en')}>
+        <Link to="/products" data-testid="pf" prefetch="intent">
+          Products
+        </Link>
+      </ModernI18nProvider>,
+      createTanstackRuntimeContext(router),
+    );
+
+    const props = capturedLinkProps.at(-1);
+    expect(props.preload).toBe('intent');
+    expect(props.prefetch).toBeUndefined();
+
+    const link = rendered.container.querySelector('[data-testid="pf"]');
+    expect(link?.hasAttribute('prefetch')).toBe(false);
+  });
+
+  test('maps prefetch="none" to preload={false}; explicit preload wins', async () => {
+    const router = createTanstackRouter('/en/products', 'en');
+    rendered = await renderWithRuntime(
+      <ModernI18nProvider value={providerValue('en')}>
+        <Link to="/products" data-testid="none" prefetch="none">
+          Products
+        </Link>
+        <Link
+          to="/products"
+          data-testid="explicit"
+          prefetch="intent"
+          preload="viewport"
+        >
+          Products
+        </Link>
+      </ModernI18nProvider>,
+      createTanstackRuntimeContext(router),
+    );
+
+    const noneProps = capturedLinkProps[capturedLinkProps.length - 2];
+    expect(noneProps.preload).toBe(false);
+    expect(noneProps.prefetch).toBeUndefined();
+
+    const explicitProps = capturedLinkProps.at(-1);
+    expect(explicitProps.preload).toBe('viewport');
+    expect(explicitProps.prefetch).toBeUndefined();
+  });
+
   test('marks the canonical target active on any localized variant', async () => {
     const router = createTanstackRouter('/cs/podminky-pouzivani', 'cs');
     rendered = await renderWithRuntime(