@bleedingdev/modern-js-i18n-runtime-extensions 3.9.0-ultramodern.9 → 3.9.3-ultramodern.2

package/src/requestLanguage.ts

@@ -0,0 +1,311 @@
+import {
+  type LocalisedUrlsOption,
+  localiseTargetPathname,
+  shouldSkipLocaleRedirect,
+} from '@modern-js/runtime-extensions/localised-urls';
+
+/**
+ * Renderer-neutral request language resolution for path-prefixed locales.
+ * It is the Fetch-native counterpart of `@modern-js/plugin-i18n`'s Hono
+ * language-detector + redirect middleware pair: a native renderer's request
+ * handler calls it with the standard `Request`, so it needs neither Hono nor
+ * React and runs unchanged on Node and in workers.
+ */
+export type RequestLanguageDetector = 'querystring' | 'cookie' | 'header';
+
+export interface RequestLanguageDetection {
+  /** @default ['querystring', 'cookie', 'header'] */
+  order?: readonly RequestLanguageDetector[];
+  /** @default 'lng' */
+  lookupQuerystring?: string;
+  /** @default 'i18next' */
+  lookupCookie?: string;
+  /** @default 'accept-language' */
+  lookupHeader?: string;
+}
+
+export interface ResolveRequestLanguageOptions {
+  languages: readonly string[];
+  fallbackLanguage: string;
+  /** Public path the entry is mounted under. @default '/' */
+  basePath?: string;
+  localisedUrls?: LocalisedUrlsOption;
+  /**
+   * Detect the language of an unprefixed URL from the query string, cookie
+   * and `Accept-Language`. When false the fallback language is used.
+   * @default true
+   */
+  detect?: boolean;
+  detection?: RequestLanguageDetection;
+  /** Canonical paths that are served without a language prefix. */
+  ignoreRedirectRoutes?: readonly string[] | ((pathname: string) => boolean);
+}
+
+export type ResolvedRequestLanguage =
+  | { kind: 'language'; language: string; vary?: readonly string[] }
+  | { kind: 'redirect'; language: string; location: string };
+
+const DEFAULT_ORDER: readonly RequestLanguageDetector[] = [
+  'querystring',
+  'cookie',
+  'header',
+];
+
+const normaliseBasePath = (basePath: string | undefined): string => {
+  if (!basePath || basePath === '/') return '';
+  return `/${basePath.split('/').filter(Boolean).join('/')}`;
+};
+
+/** The pathname below the entry base path, or `undefined` outside it. */
+const entryPathname = (
+  pathname: string,
+  basePath: string | undefined,
+): string | undefined => {
+  const base = normaliseBasePath(basePath);
+  if (!base) return pathname || '/';
+  if (pathname === base) return '/';
+  return pathname.startsWith(`${base}/`)
+    ? pathname.slice(base.length)
+    : undefined;
+};
+
+const baseLanguage = (tag: string) => tag.toLowerCase().split(/[-_]/u)[0];
+
+/**
+ * Supported languages a range covers, best first: the exact tag, the range's
+ * base language (`cs-CZ` -> `cs`), then regional languages under a base range
+ * (`en` -> `en-US`, `en-GB`).
+ */
+const compatibleLanguages = (
+  candidate: string | null | undefined,
+  languages: readonly string[],
+): string[] => {
+  const value = candidate?.trim().toLowerCase();
+  if (!value) return [];
+  const base = baseLanguage(value);
+  return [
+    ...languages.filter(language => language.toLowerCase() === value),
+    ...languages.filter(language => language.toLowerCase() === base),
+    ...(base === value
+      ? languages.filter(language => baseLanguage(language) === value)
+      : []),
+  ].filter((language, index, all) => all.indexOf(language) === index);
+};
+
+const matchLanguage = (
+  candidate: string | null | undefined,
+  languages: readonly string[],
+): string | undefined => compatibleLanguages(candidate, languages)[0];
+
+/** The supported language carried by a public pathname's first segment. */
+export function languageFromPathname(
+  pathname: string,
+  languages: readonly string[],
+  basePath?: string,
+): string | undefined {
+  const remaining = entryPathname(pathname, basePath);
+  if (remaining === undefined) return undefined;
+  const first = remaining.split('/').filter(Boolean)[0];
+  if (!first) return undefined;
+  return languages.find(
+    language => language.toLowerCase() === first.toLowerCase(),
+  );
+}
+
+const readCookie = (header: string | null, name: string): string | null => {
+  if (!header) return null;
+  for (const part of header.split(';')) {
+    const separator = part.indexOf('=');
+    if (separator < 0) continue;
+    if (part.slice(0, separator).trim() !== name) continue;
+    const raw = part.slice(separator + 1).trim();
+    try {
+      return decodeURIComponent(raw);
+    } catch {
+      return raw;
+    }
+  }
+  return null;
+};
+
+const QVALUE = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+
+/**
+ * How specifically a range covers a supported language: the exact tag, then
+ * longer prefix ranges (`en` for `en-US`), then a regional range naming the
+ * base language (`cs-CZ` for `cs`), then `*`. `undefined` when it does not.
+ */
+const rangeSpecificity = (
+  range: string,
+  language: string,
+): number | undefined => {
+  const value = range.toLowerCase().replaceAll('_', '-');
+  const supported = language.toLowerCase().replaceAll('_', '-');
+  if (value === '*') return 0;
+  if (value === supported) return Number.MAX_SAFE_INTEGER;
+  if (supported.startsWith(`${value}-`)) return 1 + value.split('-').length;
+  if (baseLanguage(value) === supported) return 1;
+  return undefined;
+};
+
+/**
+ * Supported languages in `Accept-Language` order, highest quality first. A
+ * language's quality comes from the most specific range covering it, and `*`
+ * covers every language no other range names.
+ */
+const acceptedLanguages = (
+  header: string | null,
+  languages: readonly string[],
+): string[] => {
+  const items = (header ?? '')
+    .split(',')
+    .map((item, index) => {
+      const [tag, ...parameters] = item.trim().split(';');
+      const quality = parameters
+        .map(parameter => parameter.trim())
+        .find(parameter => parameter.toLowerCase().startsWith('q='));
+      // RFC 9110 qvalue: 0 to 1 with at most three decimals. A malformed
+      // weight drops the item, so it neither ranks nor shadows other ranges.
+      const value = quality?.slice(2).trim();
+      const q =
+        value === undefined ? 1 : QVALUE.test(value) ? Number(value) : NaN;
+      return { tag: tag.trim(), q, index };
+    })
+    .filter(item => item.tag && !Number.isNaN(item.q));
+  // Each supported language takes the quality of its most specific range, so
+  // `en;q=0, en-US` keeps en-US while excluding the other English locales.
+  const ranked = languages.flatMap((language, position) => {
+    let best: { q: number; index: number; specificity: number } | undefined;
+    for (const item of items) {
+      const specificity = rangeSpecificity(item.tag, language);
+      if (
+        specificity !== undefined &&
+        (!best || specificity > best.specificity)
+      )
+        best = { q: item.q, index: item.index, specificity };
+    }
+    return best && best.q > 0 ? [{ language, position, ...best }] : [];
+  });
+  return ranked
+    .sort(
+      (left, right) =>
+        right.q - left.q ||
+        left.index - right.index ||
+        right.specificity - left.specificity ||
+        left.position - right.position,
+    )
+    .map(entry => entry.language);
+};
+
+/**
+ * Detect a supported language from the request alone (no path), in the
+ * configured detector order. Returns `undefined` when nothing matches.
+ */
+export function detectRequestLanguage(
+  request: Request,
+  languages: readonly string[],
+  detection: RequestLanguageDetection = {},
+): string | undefined {
+  const url = new URL(request.url);
+  for (const detector of detection.order ?? DEFAULT_ORDER) {
+    let language: string | undefined;
+    if (detector === 'querystring') {
+      language = matchLanguage(
+        url.searchParams.get(detection.lookupQuerystring ?? 'lng'),
+        languages,
+      );
+    } else if (detector === 'cookie') {
+      language = matchLanguage(
+        readCookie(
+          request.headers.get('cookie'),
+          detection.lookupCookie ?? 'i18next',
+        ),
+        languages,
+      );
+    } else if (detector === 'header') {
+      language = acceptedLanguages(
+        request.headers.get(detection.lookupHeader ?? 'accept-language'),
+        languages,
+      ).find(Boolean);
+    }
+    if (language) return language;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the language a request renders in. A URL that already carries a
+ * supported language prefix renders in it; an unprefixed page URL is
+ * redirected to the detected (or fallback) language's localized URL, keeping
+ * search and the base path, unless it is an ignored or framework-owned path.
+ */
+export function resolveRequestLanguage(
+  request: Request,
+  options: ResolveRequestLanguageOptions,
+): ResolvedRequestLanguage {
+  const { languages, fallbackLanguage } = options;
+  const url = new URL(request.url);
+  const fromPath = languageFromPathname(
+    url.pathname,
+    languages,
+    options.basePath,
+  );
+  if (fromPath) return { kind: 'language', language: fromPath };
+  const detected =
+    (options.detect === false
+      ? undefined
+      : detectRequestLanguage(request, languages, options.detection)) ??
+    fallbackLanguage;
+  const remaining = entryPathname(url.pathname, options.basePath);
+  if (
+    remaining === undefined ||
+    shouldSkipLocaleRedirect(
+      remaining,
+      [...languages],
+      options.ignoreRedirectRoutes as
+        | string[]
+        | ((pathname: string) => boolean)
+        | undefined,
+    )
+  ) {
+    // An unprefixed page that is not redirected still renders in a language
+    // read from request headers, so its response depends on them.
+    const vary = (
+      options.detect === false
+        ? []
+        : (options.detection?.order ?? DEFAULT_ORDER)
+    ).flatMap(detector =>
+      detector === 'header'
+        ? [options.detection?.lookupHeader ?? 'Accept-Language']
+        : detector === 'cookie'
+          ? ['Cookie']
+          : [],
+    );
+    return vary.length
+      ? { kind: 'language', language: detected, vary }
+      : { kind: 'language', language: detected };
+  }
+  const localized = localiseTargetPathname(
+    remaining,
+    detected,
+    [...languages],
+    options.localisedUrls,
+  );
+  return {
+    kind: 'redirect',
+    language: detected,
+    location: `${normaliseBasePath(options.basePath)}${localized}${url.search}`,
+  };
+}
+
+/** The same uncacheable 302 the React server middleware answers with. */
+export function createRequestLanguageRedirect(location: string): Response {
+  return new Response(null, {
+    status: 302,
+    headers: {
+      'cache-control': 'private, no-store',
+      location,
+      vary: 'Accept-Language, Cookie',
+    },
+  });
+}

package/src/router-navigation/adapter.tsx

@@ -0,0 +1,120 @@
+import { RuntimeContext } from '@modern-js/runtime';
+import { InternalRuntimeContext } from '@modern-js/runtime/context';
+import {
+  getRouterRuntimeState,
+  type RouterLinkTarget,
+  type RouterNavigationCapability,
+  type RouterNavigationSnapshot,
+  subscribeRouterRuntimeState,
+} from '@modern-js/runtime-extensions/router-state';
+import type React from 'react';
+import { useCallback, useContext, useSyncExternalStore } from 'react';
+
+export interface I18nRouterNavigationDependencies<
+  Adapter extends I18nRouterAdapterShape,
+> {
+  I18nNavigationProvider: React.ComponentType<
+    React.PropsWithChildren<{ value: Adapter }>
+  >;
+  useNativeI18nRouterAdapter: () => Adapter;
+}
+
+export type I18nRouterLinkTarget = RouterLinkTarget;
+
+export interface I18nRouterAdapterShape {
+  framework?: string;
+  hasRouter: boolean;
+  location: RouterNavigationSnapshot['location'] | null;
+  navigate: RouterNavigationCapability['navigate'] | null;
+  Link: RouterNavigationCapability['Link'] | null;
+  params: Record<string, string>;
+  createLinkProps?: RouterNavigationCapability['createLinkProps'];
+}
+
+const subscribeNone = () => () => {};
+const getEmptySnapshot = () => null;
+
+/** The router provider owns navigation; this seam only observes its capability. */
+export const createI18nRouterNavigation = <
+  Adapter extends I18nRouterAdapterShape,
+>({
+  I18nNavigationProvider,
+  useNativeI18nRouterAdapter,
+}: I18nRouterNavigationDependencies<Adapter>) => {
+  // The injected context accepts null to preserve native-router fallback.
+  const NavigationProvider = I18nNavigationProvider as React.ComponentType<
+    React.PropsWithChildren<{ value: Adapter | null }>
+  >;
+  const useIntegratedRouterAdapter = (): Adapter => {
+    const runtimeContext = useContext(RuntimeContext);
+    const internalContext = useContext(InternalRuntimeContext);
+    const native = useNativeI18nRouterAdapter();
+    const getCapability = useCallback(
+      () =>
+        getRouterRuntimeState(internalContext)?.navigation ??
+        getRouterRuntimeState(runtimeContext)?.navigation,
+      [internalContext, runtimeContext],
+    );
+    const subscribeCapability = useCallback(
+      (update: () => void) => {
+        const stopInternal = subscribeRouterRuntimeState(
+          internalContext,
+          update,
+        );
+        const stopPublic =
+          internalContext === runtimeContext
+            ? undefined
+            : subscribeRouterRuntimeState(runtimeContext, update);
+        return () => {
+          stopInternal();
+          stopPublic?.();
+        };
+      },
+      [internalContext, runtimeContext],
+    );
+    // Separate subscriptions handle both delayed installation/replacement and
+    // navigation inside the currently selected provider, without hook guessing.
+    const capability = useSyncExternalStore(
+      subscribeCapability,
+      getCapability,
+      getCapability,
+    );
+    const snapshot = useSyncExternalStore(
+      capability?.subscribe ?? subscribeNone,
+      capability?.getSnapshot ?? getEmptySnapshot,
+      capability?.getSnapshot ?? getEmptySnapshot,
+    );
+    if (native.hasRouter || !capability || !snapshot) {
+      return native;
+    }
+    const internalState = getRouterRuntimeState(internalContext);
+    return {
+      framework:
+        internalState?.navigation === capability
+          ? internalState.framework
+          : getRouterRuntimeState(runtimeContext)?.framework,
+      hasRouter: true,
+      ...snapshot,
+      navigate: capability.navigate,
+      Link: capability.Link,
+      createLinkProps: capability.createLinkProps,
+    } as Adapter;
+  };
+
+  const I18nRouterNavigationProvider = ({
+    children,
+  }: React.PropsWithChildren) => {
+    const value = useIntegratedRouterAdapter();
+    const native = useNativeI18nRouterAdapter();
+    // Keep the router subtree mounted when a capability arrives or disappears.
+    return (
+      <NavigationProvider
+        value={value.hasRouter && !native.hasRouter ? value : null}
+      >
+        {children}
+      </NavigationProvider>
+    );
+  };
+
+  return { useIntegratedRouterAdapter, I18nRouterNavigationProvider };
+};

package/src/router-navigation/index.ts

@@ -0,0 +1,6 @@
+export {
+  createI18nRouterNavigation,
+  type I18nRouterAdapterShape,
+  type I18nRouterLinkTarget,
+  type I18nRouterNavigationDependencies,
+} from './adapter';

package/src/ssrLanguageHandoff.ts

@@ -0,0 +1,138 @@
+import {
+  parsePublicData,
+  serializePublicData,
+} from '@modern-js/renderer-core/data';
+import { serializeInlineData } from '@modern-js/renderer-core/document';
+
+/**
+ * Renderer-neutral replacement for React's `window._SSR_DATA.data.i18nData`
+ * handoff (see `plugin-i18n/src/runtime/i18n/detection/ssr.ts` and
+ * `pluginSetup.ts`'s `exportServerLngToWindow`). That path only exists
+ * because the React renderer serializes its own `_SSR_DATA` global; native
+ * renderers have no equivalent global, so the language (and an optional
+ * resource subset, for first-paint translation without a network round
+ * trip) travels in its own inline `<script type="application/json">`
+ * element instead, using renderer-core's public-data codec — the same
+ * XSS-safe escaping and size/depth limits used for loader/action data.
+ */
+export const I18N_SSR_HANDOFF_ELEMENT_ID = '__modernjs_i18n_ssr__';
+
+/** `{ [namespace]: { [key]: value } }`, scoped to a single language. */
+export type I18nSsrHandoffResources = Record<string, Record<string, unknown>>;
+
+export interface I18nSsrHandoffPayload {
+  /** The language the server resolved for this request. */
+  language: string;
+  /** Optional subset of resources for `language`, keyed by namespace. */
+  resources?: I18nSsrHandoffResources;
+}
+
+export interface SerializeI18nSsrHandoffOptions {
+  /** @default I18N_SSR_HANDOFF_ELEMENT_ID */
+  id?: string;
+  nonce?: string;
+}
+
+function assertPayload(
+  payload: I18nSsrHandoffPayload,
+): asserts payload is I18nSsrHandoffPayload {
+  if (typeof payload.language !== 'string' || payload.language.length === 0) {
+    throw new TypeError(
+      'An i18n SSR handoff payload requires a nonempty language.',
+    );
+  }
+  if (
+    payload.resources !== undefined &&
+    (typeof payload.resources !== 'object' || payload.resources === null)
+  ) {
+    throw new TypeError(
+      'An i18n SSR handoff payload resources field must be a plain object.',
+    );
+  }
+}
+
+/** An inline data element a native document serializes with its own nonce. */
+export interface I18nSsrHandoffInlineData {
+  readonly id: string;
+  readonly payload: ReturnType<typeof serializePublicData>;
+}
+
+/**
+ * Encode the handoff as `{ id, payload }` for a native document's
+ * `inlineData` option, which places it before the client modules and stamps
+ * it with the document's CSP nonce.
+ */
+export function createI18nSsrHandoffInlineData(
+  payload: I18nSsrHandoffPayload,
+  options: Pick<SerializeI18nSsrHandoffOptions, 'id'> = {},
+): I18nSsrHandoffInlineData {
+  assertPayload(payload);
+  return {
+    id: options.id ?? I18N_SSR_HANDOFF_ELEMENT_ID,
+    payload: serializePublicData({
+      language: payload.language,
+      ...(payload.resources ? { resources: payload.resources } : {}),
+    }),
+  };
+}
+
+/**
+ * Serialize the language/resources handoff into a complete, inert
+ * `<script type="application/json">` element string. The native renderer's
+ * document composition decides where to place it (before any module that
+ * reads it on the client).
+ */
+export function serializeI18nSsrHandoff(
+  payload: I18nSsrHandoffPayload,
+  options: SerializeI18nSsrHandoffOptions = {},
+): string {
+  return serializeInlineData({
+    ...createI18nSsrHandoffInlineData(payload, options),
+    nonce: options.nonce,
+  });
+}
+
+function isHandoffPayload(value: unknown): value is I18nSsrHandoffPayload {
+  return (
+    Boolean(value) &&
+    typeof value === 'object' &&
+    typeof (value as { language?: unknown }).language === 'string'
+  );
+}
+
+/**
+ * Decode a handoff payload from the raw text content of the element
+ * `serializeI18nSsrHandoff` produced. Pure — no DOM access — so it can be
+ * unit tested or used from a non-browser client runtime directly.
+ * Returns `undefined` for missing, malformed or oversized input rather than
+ * throwing, since a corrupted handoff should fall back to client detection.
+ */
+export function readI18nSsrHandoffFromText(
+  text: string | null | undefined,
+): I18nSsrHandoffPayload | undefined {
+  if (!text) {
+    return undefined;
+  }
+  try {
+    const result = parsePublicData(text);
+    return isHandoffPayload(result) ? result : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Browser convenience wrapper: reads the handoff element from `document` (or
+ * a supplied document-like object) by id and decodes it.
+ */
+export function readI18nSsrHandoff(
+  options: { id?: string; doc?: Pick<Document, 'getElementById'> } = {},
+): I18nSsrHandoffPayload | undefined {
+  const doc =
+    options.doc ?? (typeof document === 'undefined' ? undefined : document);
+  if (!doc) {
+    return undefined;
+  }
+  const element = doc.getElementById(options.id ?? I18N_SSR_HANDOFF_ELEMENT_ID);
+  return readI18nSsrHandoffFromText(element?.textContent ?? null);
+}

package/src/urlRewrite.ts

@@ -0,0 +1,107 @@
+import {
+  canonicalTargetPathname,
+  type LocalisedUrlsOption,
+  localiseTargetPathname,
+} from '@modern-js/runtime-extensions/localised-urls';
+import { languageFromPathname } from './requestLanguage';
+
+/**
+ * Structurally identical to `@tanstack/router-core`'s `LocationRewriteFunction`.
+ * Defined locally so this module has no runtime dependency on router-core —
+ * any router built on that contract (TanStack Router, `@octanejs/tanstack-router`,
+ * which re-exports it verbatim) can consume the rewrite this module builds.
+ */
+export type I18nLocationRewriteFunction = (args: {
+  url: URL;
+}) => undefined | string | URL;
+
+/** Structurally identical to `@tanstack/router-core`'s `LocationRewrite`. */
+export interface I18nLocationRewrite {
+  input?: I18nLocationRewriteFunction;
+  output?: I18nLocationRewriteFunction;
+}
+
+export interface CreateI18nUrlRewriteOptions {
+  /** Supported language codes, e.g. `['en', 'cs']`. */
+  languages: readonly string[];
+  /**
+   * The language an outgoing (internal -> public) location is localized to
+   * when its pathname does not already start with a supported language.
+   */
+  getLanguage: () => string;
+  /**
+   * Canonical-path -> per-language path map; mirrors
+   * `localeDetection.localisedUrls`. Omit for the plain language-prefix policy.
+   */
+  localisedUrls?: LocalisedUrlsOption;
+  /**
+   * Called with the language segment found in an incoming public pathname,
+   * before it is stripped to its canonical form. Not called when the
+   * pathname carries no recognizable language segment.
+   */
+  onLanguageDetected?: (language: string) => void;
+}
+
+/**
+ * Build a TanStack router-core `LocationRewrite` from the fork's localized-URL
+ * pathname helpers: the router matches against canonical (language-agnostic)
+ * paths internally, while every public href it produces carries the current
+ * language prefix (and any mapped locale slug). An outgoing pathname that
+ * already starts with a supported language keeps that language, which is how
+ * a route mask such as `LocalizedLink`'s publishes another language's URL.
+ *
+ * Pass the result directly as a router's `rewrite` option:
+ *
+ * ```ts
+ * createRouter({ routeTree, rewrite: createI18nUrlRewrite({ languages, getLanguage }) })
+ * ```
+ *
+ * If the router also configures a `basepath`, router-core composes the two
+ * for you — its constructor internally does
+ * `this.rewrite = rewriteBasepath(basepath, caseSensitive, options.rewrite)`
+ * (that helper is an internal, not part of router-core's public exports; the
+ * composition happens automatically, nothing extra to call here). It strips
+ * the basepath before this rewrite's `input` runs, and applies this
+ * rewrite's `output` before the basepath is re-added, so the public URL
+ * shape is `${basepath}${languagePrefix}${canonicalPath}` — e.g.
+ * `/app/en/dashboard` while the router itself only ever sees `/dashboard`.
+ */
+export const createI18nUrlRewrite = (
+  options: CreateI18nUrlRewriteOptions,
+): I18nLocationRewrite => {
+  const { languages, getLanguage, localisedUrls, onLanguageDetected } = options;
+  const languageList = [...languages];
+
+  return {
+    input: ({ url }) => {
+      const pathname = url.pathname;
+      if (onLanguageDetected) {
+        const segments = pathname.split('/').filter(Boolean);
+        const firstSegment = segments[0];
+        const detected = firstSegment
+          ? languageList.find(
+              language => language.toLowerCase() === firstSegment.toLowerCase(),
+            )
+          : undefined;
+        if (detected) {
+          onLanguageDetected(detected);
+        }
+      }
+      url.pathname = canonicalTargetPathname(
+        pathname,
+        languageList,
+        localisedUrls,
+      );
+      return url;
+    },
+    output: ({ url }) => {
+      url.pathname = localiseTargetPathname(
+        url.pathname,
+        languageFromPathname(url.pathname, languageList) ?? getLanguage(),
+        languageList,
+        localisedUrls,
+      );
+      return url;
+    },
+  };
+};