@bleedingdev/modern-js-plugin-i18n 3.9.0-ultramodern.7 → 3.9.0-ultramodern.9

package/src/server/redirectPolicy.ts

@@ -1,4 +1,5 @@
-import type { I18nUrlStrategy } from '../shared/urlStrategy';
+import { isDefaultLocaleRedirectSkipPath } from '../shared/mappedUrlStrategy';
+import { asI18nUrlStrategy, type I18nUrlStrategy } from '../shared/urlStrategy';
 
 interface LocaleRedirectRequest {
   url: string;
@@ -23,7 +24,20 @@ export const shouldIgnoreRedirect = (
   languages: string[] = [],
 ): boolean => {
   const remainingPath = stripUrlPathPrefix(pathname, urlPath);
-  if (urlStrategy?.shouldSkipRedirect?.(remainingPath, languages)) {
+  // Federation artifacts (`backend-mf-manifest.json`, `backendRemoteEntry.cjs`,
+  // `mf-manifest.json`, …) are never pages: redirecting them to a locale
+  // prefix hands a remote consumer an HTML document. This is native policy and
+  // does not depend on a URL strategy being configured; a strategy can only
+  // add exclusions.
+  if (isDefaultLocaleRedirectSkipPath(remainingPath, languages)) {
+    return true;
+  }
+  if (
+    asI18nUrlStrategy(urlStrategy)?.shouldSkipRedirect?.(
+      remainingPath,
+      languages,
+    )
+  ) {
     return true;
   }
   if (!ignoreRedirectRoutes) {
@@ -110,8 +124,9 @@ export const buildLocalizedUrl = (
   } else {
     segments.unshift(language);
   }
-  const pathname = urlStrategy
-    ? urlStrategy.localizePathname(remainingPath, language, languages)
+  const strategy = asI18nUrlStrategy(urlStrategy);
+  const pathname = strategy
+    ? strategy.localizePathname(remainingPath, language, languages)
     : `/${segments.join('/')}`;
   return `${basePath === '/' ? '' : basePath}${pathname}${url.search}${url.hash}`;
 };

package/src/shared/mappedUrlStrategy.ts

@@ -0,0 +1,59 @@
+import {
+  canonicalTargetPathname,
+  isDefaultLocaleRedirectSkipPath,
+  type LocalisedUrlsOption,
+  localiseTargetPathname,
+} from '@modern-js/i18n-runtime-extensions';
+import type { I18nUrlStrategy } from './urlStrategy';
+
+/**
+ * The fork's native locale-redirect exclusions (federation artifacts, static
+ * and upload prefixes). Re-exported from this fork-owned seam so the native
+ * runtime and server redirect paths apply them without importing the
+ * extensions package themselves.
+ */
+export { isDefaultLocaleRedirectSkipPath } from '@modern-js/i18n-runtime-extensions';
+
+/**
+ * Build the URL policy from a mapped-locale-URL configuration.
+ *
+ * `localeDetection.localisedUrls` is plain data, so unlike a `urlStrategy`
+ * object it survives the JSON boundary between `modern.config.ts` and the
+ * generated runtime registration. It is therefore the one configuration both
+ * sides can rely on for mapped URLs.
+ *
+ * This is shared rather than server-only on purpose. The server and the client
+ * have to agree on the mapping or a hydrated `<Link>` navigates to a path the
+ * server will not serve: SSR renders `/cs/obchodni-podminky` while a
+ * client-side navigation asks for `/cs/terms-of-service`. The helpers below are
+ * pure pathname functions from `@modern-js/i18n-runtime-extensions`, so the
+ * client cost is a few hundred bytes of string work and no i18n engine.
+ */
+export const createMappedUrlStrategy = (
+  localisedUrls?: LocalisedUrlsOption,
+): I18nUrlStrategy => ({
+  localizePathname: (pathname, language, languages) =>
+    localiseTargetPathname(pathname, language, [...languages], localisedUrls),
+  canonicalPathname: (pathname, languages) =>
+    canonicalTargetPathname(pathname, [...languages], localisedUrls),
+  shouldSkipRedirect: (pathname, languages) =>
+    isDefaultLocaleRedirectSkipPath(pathname, [...languages]),
+});
+
+/** Only a non-empty map needs a derived policy. */
+export const resolveMappedUrlStrategy = (
+  localeDetection: unknown,
+): I18nUrlStrategy | undefined => {
+  if (!localeDetection || typeof localeDetection !== 'object') {
+    return undefined;
+  }
+  const localisedUrls = Reflect.get(localeDetection, 'localisedUrls');
+  if (
+    !localisedUrls ||
+    typeof localisedUrls !== 'object' ||
+    Object.keys(localisedUrls).length === 0
+  ) {
+    return undefined;
+  }
+  return createMappedUrlStrategy(localisedUrls as LocalisedUrlsOption);
+};

package/src/shared/type.ts

@@ -10,6 +10,16 @@ export interface BaseLocaleDetectionOptions {
   fallbackLanguage?: string;
   detection?: LanguageDetectorOptions;
   ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
+  /**
+   * Canonical-path -> per-language path map, e.g.
+   * `{ '/products': { en: '/products', cs: '/produkty' } }`.
+   *
+   * Plain data on purpose: the generated runtime registration carries plugin
+   * options as JSON, so a map survives the trip where a `urlStrategy` object
+   * would lose its methods. The CLI expands file-system routes from it, and
+   * the server derives its URL strategy from it, with no extra plugin.
+   */
+  localisedUrls?: boolean | Record<string, Record<string, string>>;
 }
 
 export interface LocaleDetectionOptions extends BaseLocaleDetectionOptions {

package/src/shared/urlStrategy.ts

@@ -9,3 +9,30 @@ export interface I18nUrlStrategy {
   /** Adds exclusions; it cannot enable redirects excluded by native rules. */
   shouldSkipRedirect?(pathname: string, languages: readonly string[]): boolean;
 }
+
+/**
+ * A URL strategy reaches the runtime through the generated runtime
+ * registration, which carries plugin options as JSON. Functions do not survive
+ * that, so a configured strategy can arrive as an empty object — which is
+ * truthy and would make every call site throw. Anything that is not a complete
+ * strategy is treated as absent, and the caller falls back to the built-in
+ * language-prefix behaviour.
+ */
+export const asI18nUrlStrategy = (
+  candidate: unknown,
+): I18nUrlStrategy | undefined => {
+  if (!candidate || typeof candidate !== 'object') {
+    return undefined;
+  }
+  const strategy = candidate as Partial<I18nUrlStrategy>;
+  return typeof strategy.localizePathname === 'function' &&
+    typeof strategy.canonicalPathname === 'function'
+    ? (strategy as I18nUrlStrategy)
+    : undefined;
+};
+
+/** `true` when a value was configured as a strategy but cannot be used as one. */
+export const isUnusableI18nUrlStrategy = (candidate: unknown): boolean =>
+  Boolean(candidate) &&
+  typeof candidate === 'object' &&
+  asI18nUrlStrategy(candidate) === undefined;

package/tests/defaultUrlStrategy.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from '@rstest/core';
+import { i18nServerPlugin } from '../src/server';
+import { resolveDefaultUrlStrategy } from '../src/server/defaultUrlStrategy';
+
+const localisedUrls = {
+  '/about': { en: '/about', cs: '/o-nas' },
+};
+
+const createRequestContext = (pathname: string) =>
+  ({
+    req: { url: `http://localhost${pathname}` },
+  }) as any;
+
+const bootServerPlugin = (options: Parameters<typeof i18nServerPlugin>[0]) => {
+  const middlewares: any[] = [];
+  const routes = [{ entryName: 'main', entryPath: '', urlPath: '/' }];
+  let prepare: (() => void) | undefined;
+
+  i18nServerPlugin(options).setup({
+    getServerConfig: () => ({}),
+    getServerContext: () => ({ middlewares, routes }),
+    onPrepare: (fn: () => void) => {
+      prepare = fn;
+    },
+  } as any);
+
+  prepare?.();
+  return middlewares;
+};
+
+describe('default URL strategy', () => {
+  test('a mapped locale URL config alone produces a strategy', () => {
+    const strategy = resolveDefaultUrlStrategy(localisedUrls);
+
+    expect(strategy).toBeDefined();
+    expect(strategy?.localizePathname('/about', 'cs', ['en', 'cs'])).toBe(
+      '/cs/o-nas',
+    );
+    expect(strategy?.canonicalPathname('/cs/o-nas', ['en', 'cs'])).toBe(
+      '/about',
+    );
+  });
+
+  test('no map means no derived strategy', () => {
+    expect(resolveDefaultUrlStrategy(undefined)).toBeUndefined();
+    expect(resolveDefaultUrlStrategy({})).toBeUndefined();
+    expect(resolveDefaultUrlStrategy('nope')).toBeUndefined();
+  });
+
+  test('`localisedUrls` boots the server without any extra plugin', () => {
+    // Previously this threw "Mapped locale URLs require a URL strategy",
+    // which stopped every existing consumer's server from starting.
+    const middlewares = bootServerPlugin({
+      localeDetection: {
+        fallbackLanguage: 'en',
+        languages: ['en', 'cs'],
+        localePathRedirect: true,
+        localisedUrls,
+      } as any,
+      staticRoutePrefixes: [],
+    });
+
+    expect(middlewares.map(middleware => middleware.name)).toContain(
+      'i18n-server-middleware',
+    );
+  });
+
+  test('redirects a canonical path to its mapped locale URL', async () => {
+    const middlewares = bootServerPlugin({
+      localeDetection: {
+        fallbackLanguage: 'en',
+        languages: ['en', 'cs'],
+        localePathRedirect: true,
+        localisedUrls,
+      } as any,
+      staticRoutePrefixes: [],
+    });
+
+    const redirect = middlewares.find(
+      middleware => middleware.name === 'i18n-server-middleware',
+    );
+    const context = createRequestContext('/about');
+    context.get = () => 'cs';
+    const response = await redirect.handler(context, async () => undefined);
+
+    expect(response?.headers?.get('location')).toBe('/cs/o-nas');
+  });
+
+  test('an explicit strategy still wins over the derived one', () => {
+    const explicit = {
+      localizePathname: () => '/explicit',
+      canonicalPathname: () => '/explicit',
+    };
+    const middlewares = bootServerPlugin({
+      localeDetection: {
+        fallbackLanguage: 'en',
+        languages: ['en', 'cs'],
+        localePathRedirect: true,
+        localisedUrls,
+      } as any,
+      staticRoutePrefixes: [],
+      resolveUrlStrategy: () => explicit,
+    });
+
+    expect(middlewares.length).toBeGreaterThan(0);
+  });
+});

package/tests/localisedRouteGeneration.test.ts

@@ -0,0 +1,159 @@
+import type { AppTools, CliPlugin } from '@modern-js/app-tools';
+import { createAsyncHook, createPluginManager } from '@modern-js/plugin';
+import {
+  createContext,
+  initAppContext,
+  initPluginAPI,
+} from '@modern-js/plugin/cli';
+import type { NestedRouteForCli } from '@modern-js/types';
+import { describe, expect, test } from '@rstest/core';
+import { type I18nPluginOptions, i18nPlugin } from '../src/cli';
+
+/**
+ * Localised route generation must reach a bare `appTools()` consumer.
+ *
+ * The fork used to register it only from `@modern-js/i18n-integration`, which
+ * `ultramodernAppTools()` composes but plain `appTools()` does not — so an app
+ * declaring `localeDetection.localisedUrls` got a 404 on every mapped path
+ * under SSR. These cases deliberately register *only* the native plugin, with
+ * no integration plugin in the manager, so a regression back to the opt-in
+ * wiring fails here.
+ */
+
+const createRoute = (
+  path: string,
+  children?: NestedRouteForCli[],
+): NestedRouteForCli => ({
+  id: path,
+  path,
+  type: 'nested',
+  origin: 'file-system',
+  routeType: children ? 'layout' : 'page',
+  _component: `${path}.tsx`,
+  children,
+});
+
+async function createNativeOnlyHarness(options: I18nPluginOptions = {}) {
+  const manager = createPluginManager();
+  const routeHost: CliPlugin<AppTools> = {
+    name: 'test-route-host',
+    registryHooks: { modifyFileSystemRoutes: createAsyncHook<any>() },
+    setup() {
+      // Only supplies the hook registry the app-tools router owns.
+    },
+  };
+
+  manager.addPlugins([i18nPlugin(options), routeHost]);
+  const plugins = manager.getPlugins() as CliPlugin<AppTools>[];
+  const context = await createContext<AppTools>({
+    appContext: initAppContext({
+      packageName: 'plugin-i18n-native-only-test',
+      configFile: false,
+      command: 'build',
+      appDirectory: process.cwd(),
+      metaName: 'modern-js',
+      plugins,
+    }),
+    config: {},
+    normalizedConfig: {} as any,
+  });
+  const api = initPluginAPI<AppTools>({ context, pluginManager: manager });
+  for (const plugin of plugins) {
+    await plugin.setup?.(api);
+  }
+  return api.getHooks().modifyFileSystemRoutes.call;
+}
+
+const entrypoint = { entryName: 'main' } as any;
+
+const localisedUrls = {
+  '/about': { en: '/about', cs: '/o-nas' },
+  '/products/:slug': { en: '/products/:slug', cs: '/produkty/:slug' },
+};
+
+describe('native localised route generation', () => {
+  test('expands mapped locale paths without the integration plugin', async () => {
+    const modifyRoutes = await createNativeOnlyHarness({
+      localeDetection: {
+        localePathRedirect: true,
+        languages: ['en', 'cs'],
+        localisedUrls,
+      },
+    });
+
+    const result = await modifyRoutes({
+      entrypoint,
+      routes: [
+        createRoute(':lang', [
+          createRoute('about'),
+          createRoute('products/:slug'),
+        ]),
+      ],
+    });
+
+    const paths = result.routes[0].children?.map(
+      (route: NestedRouteForCli) => route.path,
+    );
+    expect(paths).toContain('about');
+    expect(paths).toContain('o-nas');
+    expect(paths).toContain('products/:slug');
+    expect(paths).toContain('produkty/:slug');
+  });
+
+  test('leaves routes untouched when no map is declared', async () => {
+    const modifyRoutes = await createNativeOnlyHarness({
+      localeDetection: {
+        localePathRedirect: true,
+        languages: ['en', 'cs'],
+      },
+    });
+
+    const input = [createRoute(':lang', [createRoute('about')])];
+    const result = await modifyRoutes({ entrypoint, routes: input });
+
+    expect(
+      result.routes[0].children?.map((r: NestedRouteForCli) => r.path),
+    ).toEqual(['about']);
+  });
+
+  test('leaves routes untouched without localePathRedirect', async () => {
+    const modifyRoutes = await createNativeOnlyHarness({
+      localeDetection: {
+        languages: ['en', 'cs'],
+        localisedUrls,
+      },
+    });
+
+    const input = [createRoute(':lang', [createRoute('about')])];
+    const result = await modifyRoutes({ entrypoint, routes: input });
+
+    expect(
+      result.routes[0].children?.map((r: NestedRouteForCli) => r.path),
+    ).toEqual(['about']);
+  });
+
+  test('resolves the map from a per-entry locale detection override', async () => {
+    const modifyRoutes = await createNativeOnlyHarness({
+      localeDetection: {
+        localePathRedirect: true,
+        languages: ['en'],
+        localeDetectionByEntry: {
+          main: {
+            localePathRedirect: true,
+            languages: ['en', 'cs'],
+            localisedUrls,
+          },
+        },
+      },
+    });
+
+    const result = await modifyRoutes({
+      entrypoint,
+      routes: [createRoute(':lang', [createRoute('about')])],
+    });
+
+    expect(
+      result.routes[0].children?.map((r: NestedRouteForCli) => r.path),
+    ).toContain('o-nas');
+  });
+});

package/tests/localisedUrls.test.ts

@@ -49,16 +49,33 @@ describe('cli modifyFileSystemRoutes', () => {
     expect(runtimePlugin?.config.reactI18next).toBe(false);
   });
 
-  test('upstream-style configs without a map keep routes untouched', () => {
-    const modifyRoutes = rstest.fn();
+  test('upstream-style configs without a map keep routes untouched', async () => {
+    // The hook is registered unconditionally now that route expansion is a
+    // native feature; what matters is that a config with no `localisedUrls`
+    // map gets its routes back byte-for-byte instead of a locale-expanded tree.
+    let handler:
+      | ((args: { entrypoint: unknown; routes: unknown[] }) => Promise<{
+          routes: unknown[];
+        }>)
+      | undefined;
+
     i18nCliPlugin({
       localeDetection: { localePathRedirect: true, languages: ['en', 'cs'] },
     }).setup({
       _internalRuntimePlugins: () => {},
       _internalServerPlugins: () => {},
-      modifyFileSystemRoutes: modifyRoutes,
+      modifyFileSystemRoutes: (fn: any) => {
+        handler = fn;
+      },
     } as any);
-    expect(modifyRoutes).not.toHaveBeenCalled();
+
+    const routes = [{ id: 'about', path: 'about', type: 'nested' }];
+    const result = await handler?.({
+      entrypoint: { entryName: 'main' },
+      routes,
+    });
+
+    expect(result?.routes).toEqual(routes);
   });
 });
 

package/tests/mappedUrlStrategyDerivation.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from '@rstest/core';
+import { resolveMappedUrlStrategy } from '../src/shared/mappedUrlStrategy';
+
+/**
+ * Mapped locale URLs must work for a bare `appTools()` consumer that only
+ * declares `localeDetection.localisedUrls`. The map is plain data, so it
+ * survives the JSON boundary a `urlStrategy` object does not; the runtime
+ * derives its policy from it, and the server derives the same policy from the
+ * same shared module.
+ */
+
+const localisedUrls = {
+  '/terms-of-service': { en: '/terms-of-service', cs: '/obchodni-podminky' },
+  '/products/:slug': { en: '/products/:slug', cs: '/produkty/:slug' },
+};
+const languages = ['en', 'cs'];
+
+describe('mapped url strategy derivation', () => {
+  test('derives a localizing strategy from localisedUrls', () => {
+    const strategy = resolveMappedUrlStrategy({ localisedUrls });
+
+    expect(strategy).toBeDefined();
+    expect(
+      strategy?.localizePathname?.('/terms-of-service', 'cs', languages),
+    ).toBe('/cs/obchodni-podminky');
+    expect(
+      strategy?.localizePathname?.('/terms-of-service', 'en', languages),
+    ).toBe('/en/terms-of-service');
+    expect(
+      strategy?.canonicalPathname?.('/cs/obchodni-podminky', languages),
+    ).toBe('/terms-of-service');
+  });
+
+  test('round-trips a parameterised mapped route', () => {
+    const strategy = resolveMappedUrlStrategy({ localisedUrls });
+    const localized = strategy?.localizePathname?.(
+      '/products/widget',
+      'cs',
+      languages,
+    );
+
+    expect(localized).toBe('/cs/produkty/widget');
+    expect(strategy?.canonicalPathname?.(localized!, languages)).toBe(
+      '/products/widget',
+    );
+  });
+
+  test('leaves unmapped paths on the plain language prefix', () => {
+    const strategy = resolveMappedUrlStrategy({ localisedUrls });
+
+    expect(strategy?.localizePathname?.('/unmapped', 'cs', languages)).toBe(
+      '/cs/unmapped',
+    );
+  });
+
+  test('derives nothing without a usable map', () => {
+    expect(resolveMappedUrlStrategy(undefined)).toBeUndefined();
+    expect(resolveMappedUrlStrategy({})).toBeUndefined();
+    expect(resolveMappedUrlStrategy({ localisedUrls: {} })).toBeUndefined();
+    expect(resolveMappedUrlStrategy({ localisedUrls: true })).toBeUndefined();
+  });
+});

package/tests/redirectPolicy.test.ts

@@ -6,6 +6,59 @@ import {
 } from '../src/server/redirectPolicy';
 
 describe('native locale redirect safeguards', () => {
+  test('never locale-redirects federation artifacts, with no URL strategy configured', () => {
+    // 3.9.0-ultramodern.9 regression: with `localisedUrls: {}` no strategy is
+    // derived, and the backend federation manifest was redirected to
+    // `/en/backend-mf-manifest.json` (an HTML page) — the Node backend
+    // federation proof then read a 404 instead of the manifest.
+    const languages = ['en', 'cs'];
+    for (const pathname of [
+      '/backend-mf-manifest.json',
+      '/backendRemoteEntry.cjs',
+      '/mf-manifest.json',
+      '/mf-stats.json',
+      '/remoteEntry.js',
+      '/remoteEntry.catalog.js',
+      '/backendRemoteEntry.catalog.cjs',
+      '/cs/backend-mf-manifest.json',
+    ]) {
+      expect(
+        shouldIgnoreServerRedirect(
+          pathname,
+          '/*',
+          undefined,
+          undefined,
+          languages,
+        ),
+      ).toBe(true);
+      expect(
+        shouldIgnoreServerRedirect(
+          `/app${pathname}`,
+          '/app/*',
+          undefined,
+          undefined,
+          languages,
+        ),
+      ).toBe(true);
+      expect(
+        shouldIgnoreRuntimeRedirect(pathname, languages, undefined, undefined),
+      ).toBe(true);
+    }
+    // A page is still redirected.
+    expect(
+      shouldIgnoreServerRedirect(
+        '/products',
+        '/*',
+        undefined,
+        undefined,
+        languages,
+      ),
+    ).toBe(false);
+    expect(
+      shouldIgnoreRuntimeRedirect('/products', languages, undefined, undefined),
+    ).toBe(false);
+  });
+
   test('retains configured ignores across runtime and server entry prefixes', () => {
     const rules = ['/private'];
     expect(