@bleedingdev/modern-js-plugin-i18n 3.5.0-ultramodern.4 → 3.5.0-ultramodern.41

package/src/server/detectorOptions.ts

@@ -0,0 +1,105 @@
+import {
+  DEFAULT_I18NEXT_DETECTION_OPTIONS,
+  mergeDetectionOptions,
+} from '../runtime/i18n/detection/config.js';
+import type { LanguageDetectorOptions } from '../runtime/i18n/instance';
+
+/**
+ * Convert i18next detection options to hono languageDetector options
+ */
+export const convertToHonoLanguageDetectorOptions = (
+  languages: string[],
+  fallbackLanguage: string,
+  detectionOptions?: LanguageDetectorOptions,
+) => {
+  // Merge user detection options with defaults
+  const mergedDetection = detectionOptions
+    ? mergeDetectionOptions(detectionOptions)
+    : DEFAULT_I18NEXT_DETECTION_OPTIONS;
+
+  // Get detection order, excluding 'path' and browser-only detectors
+  const order = (mergedDetection.order || []).filter(
+    (item: string) =>
+      !['path', 'localStorage', 'navigator', 'htmlTag', 'subdomain'].includes(
+        item,
+      ),
+  );
+
+  // If no order specified, use default server-side order
+  const detectionOrder =
+    order.length > 0 ? order : ['querystring', 'cookie', 'header'];
+
+  // Map i18next order to hono order
+  const honoOrder = detectionOrder.map(item => {
+    // Map 'querystring' to 'querystring', 'cookie' to 'cookie', 'header' to 'header'
+    if (item === 'querystring') return 'querystring';
+    if (item === 'cookie') return 'cookie';
+    if (item === 'header') return 'header';
+    return item;
+  }) as ('querystring' | 'cookie' | 'header' | 'path')[];
+
+  // Determine caches option
+  // hono languageDetector expects: false | "cookie"[] | undefined
+  const caches: false | ['cookie'] | undefined =
+    mergedDetection.caches === false
+      ? false
+      : Array.isArray(mergedDetection.caches) &&
+          !mergedDetection.caches.includes('cookie')
+        ? false
+        : (['cookie'] as ['cookie']);
+
+  const cookieMinutes = (mergedDetection as Record<string, unknown>)
+    .cookieMinutes;
+  const cookieMaxAge =
+    typeof cookieMinutes === 'number' && Number.isFinite(cookieMinutes)
+      ? Math.max(0, Math.floor(cookieMinutes * 60))
+      : DEFAULT_I18NEXT_DETECTION_OPTIONS.cookieMinutes * 60;
+
+  const cookieDomain = (mergedDetection as Record<string, unknown>)
+    .cookieDomain;
+  const cookieSecure = (mergedDetection as Record<string, unknown>)
+    .cookieSecure;
+  const cookieHttpOnly = (mergedDetection as Record<string, unknown>)
+    .cookieHttpOnly;
+  const cookieSameSite = (mergedDetection as Record<string, unknown>)
+    .cookieSameSite;
+
+  const normalizedCookieDomain =
+    typeof cookieDomain === 'string' ? cookieDomain : undefined;
+
+  // Keep cookie defaults aligned with i18next language detector behavior:
+  // language cookie should be readable from browser-side detector.
+  const cookieOptions = {
+    maxAge: cookieMaxAge,
+    sameSite:
+      cookieSameSite === 'None' || cookieSameSite === 'none'
+        ? ('None' as const)
+        : cookieSameSite === 'Lax' || cookieSameSite === 'lax'
+          ? ('Lax' as const)
+          : ('Strict' as const),
+    secure: typeof cookieSecure === 'boolean' ? cookieSecure : false,
+    httpOnly: typeof cookieHttpOnly === 'boolean' ? cookieHttpOnly : false,
+    ...(normalizedCookieDomain ? { domain: normalizedCookieDomain } : {}),
+  };
+
+  return {
+    supportedLanguages: languages.length > 0 ? languages : [fallbackLanguage],
+    fallbackLanguage,
+    order: honoOrder,
+    lookupQueryString:
+      mergedDetection.lookupQuerystring ||
+      DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupQuerystring ||
+      'lng',
+    lookupCookie:
+      mergedDetection.lookupCookie ||
+      DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupCookie ||
+      'i18next',
+    lookupFromHeaderKey:
+      mergedDetection.lookupHeader ||
+      DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupHeader ||
+      'accept-language',
+    ...(caches !== undefined && { caches }),
+    ...(caches !== false && { cookieOptions }),
+    ignoreCase: true,
+  };
+};

package/src/server/index.ts

@@ -3,331 +3,26 @@ import * as honoPkg from '@modern-js/server-core/hono';
 const { languageDetector } = honoPkg;
 
 import type { Context, Next, ServerPlugin } from '@modern-js/server-runtime';
-import {
-  DEFAULT_I18NEXT_DETECTION_OPTIONS,
-  mergeDetectionOptions,
-} from '../runtime/i18n/detection/config.js';
-import type { LanguageDetectorOptions } from '../runtime/i18n/instance';
-import {
-  localiseTargetPathname,
-  resolveLocalisedUrlsConfig,
-} from '../shared/localisedUrls.js';
+import { resolveLocalisedUrlsConfig } from '../shared/localisedUrls.js';
 import type { LocaleDetectionOptions } from '../shared/type';
 import { getLocaleDetectionOptions } from '../shared/utils.js';
+import { collectApiPrefixes, matchesApiPrefix } from './apiPrefix.js';
+import { convertToHonoLanguageDetectorOptions } from './detectorOptions.js';
+import {
+  buildLocalizedUrl,
+  createLocaleRedirectResponse,
+  getLanguageFromPath,
+  isStaticResourceRequest,
+  shouldIgnoreRedirect,
+} from './redirectPolicy.js';
+
+export { collectApiPrefixes, matchesApiPrefix } from './apiPrefix.js';
 
 export interface I18nPluginOptions {
   localeDetection: LocaleDetectionOptions;
   staticRoutePrefixes: string[];
 }
 
-type ApiPrefixInput = string | string[] | undefined;
-
-const normalizeApiPrefix = (prefix: string): string | null => {
-  const trimmedPrefix = prefix.trim();
-  if (!trimmedPrefix) {
-    return null;
-  }
-
-  const prefixedPath = trimmedPrefix.startsWith('/')
-    ? trimmedPrefix
-    : `/${trimmedPrefix}`;
-  const withoutWildcard = prefixedPath.replace(/\/\*$/, '');
-  const normalizedPrefix =
-    withoutWildcard.length > 1
-      ? withoutWildcard.replace(/\/+$/, '')
-      : withoutWildcard;
-
-  return normalizedPrefix === '/' ? null : normalizedPrefix;
-};
-
-export const collectApiPrefixes = (
-  routes: Array<{ isApi?: boolean; urlPath?: string }>,
-  bffPrefix?: ApiPrefixInput,
-): string[] => {
-  const prefixes = new Set<string>();
-
-  for (const route of routes) {
-    if (!route.isApi || !route.urlPath) {
-      continue;
-    }
-
-    const normalizedPrefix = normalizeApiPrefix(route.urlPath);
-    if (normalizedPrefix) {
-      prefixes.add(normalizedPrefix);
-    }
-  }
-
-  const bffPrefixes = Array.isArray(bffPrefix)
-    ? bffPrefix
-    : bffPrefix
-      ? [bffPrefix]
-      : [];
-
-  for (const prefix of bffPrefixes) {
-    const normalizedPrefix = normalizeApiPrefix(prefix);
-    if (normalizedPrefix) {
-      prefixes.add(normalizedPrefix);
-    }
-  }
-
-  return [...prefixes];
-};
-
-export const matchesApiPrefix = (
-  pathname: string,
-  apiPrefixes: string[],
-): boolean => {
-  const normalizedPathname = pathname.startsWith('/')
-    ? pathname
-    : `/${pathname}`;
-
-  return apiPrefixes.some(
-    prefix =>
-      normalizedPathname === prefix ||
-      normalizedPathname.startsWith(`${prefix}/`),
-  );
-};
-
-/**
- * Convert i18next detection options to hono languageDetector options
- */
-const convertToHonoLanguageDetectorOptions = (
-  languages: string[],
-  fallbackLanguage: string,
-  detectionOptions?: LanguageDetectorOptions,
-) => {
-  // Merge user detection options with defaults
-  const mergedDetection = detectionOptions
-    ? mergeDetectionOptions(detectionOptions)
-    : DEFAULT_I18NEXT_DETECTION_OPTIONS;
-
-  // Get detection order, excluding 'path' and browser-only detectors
-  const order = (mergedDetection.order || []).filter(
-    (item: string) =>
-      !['path', 'localStorage', 'navigator', 'htmlTag', 'subdomain'].includes(
-        item,
-      ),
-  );
-
-  // If no order specified, use default server-side order
-  const detectionOrder =
-    order.length > 0 ? order : ['querystring', 'cookie', 'header'];
-
-  // Map i18next order to hono order
-  const honoOrder = detectionOrder.map(item => {
-    // Map 'querystring' to 'querystring', 'cookie' to 'cookie', 'header' to 'header'
-    if (item === 'querystring') return 'querystring';
-    if (item === 'cookie') return 'cookie';
-    if (item === 'header') return 'header';
-    return item;
-  }) as ('querystring' | 'cookie' | 'header' | 'path')[];
-
-  // Determine caches option
-  // hono languageDetector expects: false | "cookie"[] | undefined
-  const caches: false | ['cookie'] | undefined =
-    mergedDetection.caches === false
-      ? false
-      : Array.isArray(mergedDetection.caches) &&
-          !mergedDetection.caches.includes('cookie')
-        ? false
-        : (['cookie'] as ['cookie']);
-
-  const cookieMinutes = (mergedDetection as Record<string, unknown>)
-    .cookieMinutes;
-  const cookieMaxAge =
-    typeof cookieMinutes === 'number' && Number.isFinite(cookieMinutes)
-      ? Math.max(0, Math.floor(cookieMinutes * 60))
-      : DEFAULT_I18NEXT_DETECTION_OPTIONS.cookieMinutes * 60;
-
-  const cookieDomain = (mergedDetection as Record<string, unknown>)
-    .cookieDomain;
-  const cookieSecure = (mergedDetection as Record<string, unknown>)
-    .cookieSecure;
-  const cookieHttpOnly = (mergedDetection as Record<string, unknown>)
-    .cookieHttpOnly;
-  const cookieSameSite = (mergedDetection as Record<string, unknown>)
-    .cookieSameSite;
-
-  const normalizedCookieDomain =
-    typeof cookieDomain === 'string' ? cookieDomain : undefined;
-
-  // Keep cookie defaults aligned with i18next language detector behavior:
-  // language cookie should be readable from browser-side detector.
-  const cookieOptions = {
-    maxAge: cookieMaxAge,
-    sameSite:
-      cookieSameSite === 'None' || cookieSameSite === 'none'
-        ? ('None' as const)
-        : cookieSameSite === 'Lax' || cookieSameSite === 'lax'
-          ? ('Lax' as const)
-          : ('Strict' as const),
-    secure: typeof cookieSecure === 'boolean' ? cookieSecure : false,
-    httpOnly: typeof cookieHttpOnly === 'boolean' ? cookieHttpOnly : false,
-    ...(normalizedCookieDomain ? { domain: normalizedCookieDomain } : {}),
-  };
-
-  return {
-    supportedLanguages: languages.length > 0 ? languages : [fallbackLanguage],
-    fallbackLanguage,
-    order: honoOrder,
-    lookupQueryString:
-      mergedDetection.lookupQuerystring ||
-      DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupQuerystring ||
-      'lng',
-    lookupCookie:
-      mergedDetection.lookupCookie ||
-      DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupCookie ||
-      'i18next',
-    lookupFromHeaderKey:
-      mergedDetection.lookupHeader ||
-      DEFAULT_I18NEXT_DETECTION_OPTIONS.lookupHeader ||
-      'accept-language',
-    ...(caches !== undefined && { caches }),
-    ...(caches !== false && { cookieOptions }),
-    ignoreCase: true,
-  };
-};
-
-/**
- * Check if the given pathname should ignore automatic locale redirect
- */
-const shouldIgnoreRedirect = (
-  pathname: string,
-  urlPath: string,
-  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
-): boolean => {
-  if (!ignoreRedirectRoutes) {
-    return false;
-  }
-
-  // Remove urlPath prefix to get remaining path for matching
-  const basePath = urlPath.replace('/*', '');
-  const remainingPath = pathname.startsWith(basePath)
-    ? pathname.slice(basePath.length)
-    : pathname;
-
-  // Normalize path (ensure it starts with /)
-  const normalizedPath = remainingPath.startsWith('/')
-    ? remainingPath
-    : `/${remainingPath}`;
-
-  if (typeof ignoreRedirectRoutes === 'function') {
-    return ignoreRedirectRoutes(normalizedPath);
-  }
-
-  // Check if pathname matches any of the ignore patterns
-  return ignoreRedirectRoutes.some(pattern => {
-    // Support both exact match and prefix match
-    return (
-      normalizedPath === pattern || normalizedPath.startsWith(`${pattern}/`)
-    );
-  });
-};
-
-/**
- * Check if the given pathname is a static resource request
- * This includes:
- * 1. Paths matching staticRoutePrefixes (from public directories)
- * 2. Standard static resource paths like /static/, /upload/
- * 3. Paths with language prefix like /en/static/, /zh/static/
- */
-const isStaticResourceRequest = (
-  pathname: string,
-  staticRoutePrefixes: string[],
-  languages: string[] = [],
-): boolean => {
-  // Check against staticRoutePrefixes (from public directories)
-  if (
-    staticRoutePrefixes.some(
-      prefix => pathname.startsWith(`${prefix}/`) || pathname === prefix,
-    )
-  ) {
-    return true;
-  }
-
-  // Check standard static resource paths
-  const standardStaticPrefixes = ['/static/', '/upload/'];
-  if (standardStaticPrefixes.some(prefix => pathname.startsWith(prefix))) {
-    return true;
-  }
-
-  // Check paths with language prefix (e.g., /en/static/, /zh/static/)
-  // Remove language prefix if present and check again
-  const pathSegments = pathname.split('/').filter(Boolean);
-  if (pathSegments.length > 0 && languages.includes(pathSegments[0])) {
-    const pathWithoutLang = '/' + pathSegments.slice(1).join('/');
-    if (
-      standardStaticPrefixes.some(prefix =>
-        pathWithoutLang.startsWith(prefix),
-      ) ||
-      staticRoutePrefixes.some(
-        prefix =>
-          pathWithoutLang.startsWith(`${prefix}/`) ||
-          pathWithoutLang === prefix,
-      )
-    ) {
-      return true;
-    }
-  }
-
-  return false;
-};
-
-const getLanguageFromPath = (
-  req: any,
-  urlPath: string,
-  languages: string[],
-): string | null => {
-  const url = new URL(req.url, `http://${req.header().host}`);
-  const pathname = url.pathname;
-
-  // Remove urlPath prefix to get remaining path
-  // urlPath format is /lang/*, need to remove /lang part
-  const basePath = urlPath.replace('/*', '');
-  const remainingPath = pathname.startsWith(basePath)
-    ? pathname.slice(basePath.length)
-    : pathname;
-
-  const segments = remainingPath.split('/').filter(Boolean);
-  const firstSegment = segments[0];
-
-  if (languages.includes(firstSegment)) {
-    return firstSegment;
-  }
-
-  return null;
-};
-
-const buildLocalizedUrl = (
-  req: any,
-  urlPath: string,
-  language: string,
-  languages: string[],
-  localisedUrls?: LocaleDetectionOptions['localisedUrls'],
-): string => {
-  const url = new URL(req.url);
-  const pathname = url.pathname;
-
-  // Remove urlPath prefix to get remaining path
-  const basePath = urlPath.replace('/*', '');
-  const remainingPath = pathname.startsWith(basePath)
-    ? pathname.slice(basePath.length)
-    : pathname;
-
-  const newPathname = localiseTargetPathname(
-    remainingPath,
-    language,
-    languages,
-    localisedUrls,
-  );
-  // Handle root path case to avoid double slashes like //en
-  const suffix = `${url.search}${url.hash}`;
-  const localizedUrl =
-    basePath === '/' ? newPathname + suffix : basePath + newPathname + suffix;
-
-  return localizedUrl;
-};
-
 export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
   name: '@modern-js/plugin-i18n/server',
   setup: api => {
@@ -475,7 +170,7 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
                   languages,
                   localisedUrls,
                 );
-                return c.redirect(localizedUrl);
+                return createLocaleRedirectResponse(localizedUrl);
               }
               const localisedUrlsConfig =
                 resolveLocalisedUrlsConfig(localisedUrls);
@@ -488,7 +183,7 @@ export const i18nServerPlugin = (options: I18nPluginOptions): ServerPlugin => ({
                   localisedUrls,
                 );
                 if (expectedUrl !== `${pathname}${url.search}${url.hash}`) {
-                  return c.redirect(expectedUrl);
+                  return createLocaleRedirectResponse(expectedUrl);
                 }
               }
               await next();

package/src/server/redirectPolicy.ts

@@ -0,0 +1,127 @@
+import {
+  isDefaultLocaleRedirectSkipPath,
+  localiseTargetPathname,
+  matchesPathPrefix,
+  shouldSkipLocaleRedirect,
+  stripLanguagePrefix,
+} from '../shared/localisedUrls.js';
+import type { LocaleDetectionOptions } from '../shared/type';
+
+interface LocaleRedirectRequest {
+  url: string;
+  header: () => {
+    host?: string;
+  };
+}
+
+const stripUrlPathPrefix = (pathname: string, urlPath: string): string => {
+  const basePath = urlPath.replace('/*', '');
+
+  if (!basePath || basePath === '/') {
+    return pathname;
+  }
+
+  const remainingPath = pathname.startsWith(basePath)
+    ? pathname.slice(basePath.length)
+    : pathname;
+
+  return remainingPath || '/';
+};
+
+/**
+ * Check if pathname should ignore automatic locale redirect.
+ */
+export const shouldIgnoreRedirect = (
+  pathname: string,
+  urlPath: string,
+  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean),
+): boolean => {
+  const remainingPath = stripUrlPathPrefix(pathname, urlPath);
+
+  return shouldSkipLocaleRedirect(remainingPath, [], ignoreRedirectRoutes);
+};
+
+/**
+ * Check if pathname is a static or federation resource request.
+ *
+ * This includes configured staticRoutePrefixes, the shared default skip policy
+ * from ADR-0002, and language-prefixed variants such as /en/static/app.js.
+ */
+export const isStaticResourceRequest = (
+  pathname: string,
+  staticRoutePrefixes: string[],
+  languages: string[] = [],
+): boolean => {
+  if (isDefaultLocaleRedirectSkipPath(pathname, languages)) {
+    return true;
+  }
+
+  const matchesStaticRoutePrefix = (targetPathname: string): boolean =>
+    staticRoutePrefixes.some(prefix =>
+      matchesPathPrefix(targetPathname, prefix),
+    );
+
+  if (matchesStaticRoutePrefix(pathname)) {
+    return true;
+  }
+
+  const pathWithoutLanguage = stripLanguagePrefix(pathname, languages);
+
+  return (
+    pathWithoutLanguage !== pathname &&
+    matchesStaticRoutePrefix(pathWithoutLanguage)
+  );
+};
+
+export const getLanguageFromPath = (
+  req: LocaleRedirectRequest,
+  urlPath: string,
+  languages: string[],
+): string | null => {
+  const url = new URL(req.url, `http://${req.header().host}`);
+  const pathname = url.pathname;
+  const remainingPath = stripUrlPathPrefix(pathname, urlPath);
+  const segments = remainingPath.split('/').filter(Boolean);
+  const firstSegment = segments[0];
+
+  if (languages.includes(firstSegment)) {
+    return firstSegment;
+  }
+
+  return null;
+};
+
+export const buildLocalizedUrl = (
+  req: LocaleRedirectRequest,
+  urlPath: string,
+  language: string,
+  languages: string[],
+  localisedUrls?: LocaleDetectionOptions['localisedUrls'],
+): string => {
+  const url = new URL(req.url);
+  const pathname = url.pathname;
+  const basePath = urlPath.replace('/*', '');
+  const remainingPath = stripUrlPathPrefix(pathname, urlPath);
+
+  const newPathname = localiseTargetPathname(
+    remainingPath,
+    language,
+    languages,
+    localisedUrls,
+  );
+  const suffix = `${url.search}${url.hash}`;
+  const localizedUrl =
+    basePath === '/' ? newPathname + suffix : basePath + newPathname + suffix;
+
+  return localizedUrl;
+};
+
+export const createLocaleRedirectResponse = (location: string): Response =>
+  new Response(null, {
+    status: 302,
+    headers: {
+      'Cache-Control': 'private, no-store',
+      Location: location,
+      Vary: 'Accept-Language, Cookie',
+    },
+  });

package/src/shared/detection.ts

@@ -8,7 +8,7 @@ import type { LanguageDetectorOptions } from '../runtime/i18n/instance';
  * Detect language from request using the same detection logic as i18next
  * This ensures consistency between server-side and client-side detection
  */
-export function detectLanguageFromRequest(
+function detectLanguageFromRequest(
   req: {
     url: string;
     headers:

package/src/shared/localisedUrls/config.ts

@@ -0,0 +1,18 @@
+import type { LocalisedUrlsOption, ResolvedLocalisedUrlsConfig } from './types';
+
+/**
+ * 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 && typeof option === 'object' && Object.keys(option).length > 0) {
+    return { enabled: true, map: option };
+  }
+
+  return { enabled: false, map: {} };
+};

package/src/shared/localisedUrls/index.ts

@@ -0,0 +1,24 @@
+export { resolveLocalisedUrlsConfig } from './config';
+export { normalisePathname, normalisePathPattern } from './normalise';
+export {
+  canonicalTargetPathname,
+  localiseTargetPathname,
+  stripLanguagePrefix,
+} from './pathname';
+export { buildPathFromPattern, matchPathPattern } from './patterns';
+export type { LocaleRedirectSkipRule } from './redirect';
+export {
+  DEFAULT_LOCALE_REDIRECT_SKIP_RULES,
+  isDefaultLocaleRedirectSkipPath,
+  matchesPathPrefix,
+  shouldSkipLocaleRedirect,
+} from './redirect';
+export { resolveCanonicalLocalisedPath, resolveLocalisedPath } from './resolve';
+export { applyLocalisedUrlsToRoutes, validateLocalisedUrls } from './routes';
+export type {
+  LocalisedRoute,
+  LocalisedUrlPathMap,
+  LocalisedUrlsMap,
+  LocalisedUrlsOption,
+  ResolvedLocalisedUrlsConfig,
+} from './types';