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

package/dist/types/urlRewrite.d.ts

@@ -0,0 +1,60 @@
+import { type LocalisedUrlsOption } from '@modern-js/runtime-extensions/localised-urls';
+/**
+ * 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 declare const createI18nUrlRewrite: (options: CreateI18nUrlRewriteOptions) => I18nLocationRewrite;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@bleedingdev/modern-js-i18n-runtime-extensions",
   "description": "Fork-owned UltraModern.js i18n runtime coordination and localized-route extensions.",
-  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "homepage": "https://github.com/ultramodernjs/ultramodern.js#readme",
   "bugs": {
-    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+    "url": "https://github.com/ultramodernjs/ultramodern.js/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "url": "git+https://github.com/ultramodernjs/ultramodern.js.git",
     "directory": "packages/runtime/i18n-extensions"
   },
   "license": "MIT",
@@ -17,7 +17,7 @@
     "modern.js",
     "i18n"
   ],
-  "version": "3.9.0-ultramodern.9",
+  "version": "3.9.3-ultramodern.1",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
@@ -30,6 +30,14 @@
       },
       "default": "./dist/esm/index.mjs"
     },
+    "./router-navigation": {
+      "types": "./dist/types/router-navigation/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/router-navigation/index.mjs",
+        "require": "./dist/cjs/router-navigation/index.js"
+      },
+      "default": "./dist/esm/router-navigation/index.mjs"
+    },
     "./package.json": "./package.json",
     "./paths": {
       "types": "./dist/types/paths.d.ts",
@@ -38,6 +46,46 @@
         "require": "./dist/cjs/paths.js"
       },
       "default": "./dist/esm/paths.mjs"
+    },
+    "./urlRewrite": {
+      "types": "./dist/types/urlRewrite.d.ts",
+      "node": {
+        "import": "./dist/esm-node/urlRewrite.mjs",
+        "require": "./dist/cjs/urlRewrite.js"
+      },
+      "default": "./dist/esm/urlRewrite.mjs"
+    },
+    "./ssrLanguageHandoff": {
+      "types": "./dist/types/ssrLanguageHandoff.d.ts",
+      "node": {
+        "import": "./dist/esm-node/ssrLanguageHandoff.mjs",
+        "require": "./dist/cjs/ssrLanguageHandoff.js"
+      },
+      "default": "./dist/esm/ssrLanguageHandoff.mjs"
+    },
+    "./language-sync/controller": {
+      "types": "./dist/types/language-sync/controller.d.ts",
+      "node": {
+        "import": "./dist/esm-node/language-sync/controller.mjs",
+        "require": "./dist/cjs/language-sync/controller.js"
+      },
+      "default": "./dist/esm/language-sync/controller.mjs"
+    },
+    "./request-language": {
+      "types": "./dist/types/requestLanguage.d.ts",
+      "node": {
+        "import": "./dist/esm-node/requestLanguage.mjs",
+        "require": "./dist/cjs/requestLanguage.js"
+      },
+      "default": "./dist/esm/requestLanguage.mjs"
+    },
+    "./native": {
+      "types": "./dist/types/native.d.ts",
+      "node": {
+        "import": "./dist/esm-node/native.mjs",
+        "require": "./dist/cjs/native.js"
+      },
+      "default": "./dist/esm/native.mjs"
     }
   },
   "typesVersions": {
@@ -48,36 +96,75 @@
       ],
       "paths": [
         "./dist/types/paths.d.ts"
+      ],
+      "router-navigation": [
+        "./dist/types/router-navigation/index.d.ts"
+      ],
+      "urlRewrite": [
+        "./dist/types/urlRewrite.d.ts"
+      ],
+      "ssrLanguageHandoff": [
+        "./dist/types/ssrLanguageHandoff.d.ts"
+      ],
+      "language-sync/controller": [
+        "./dist/types/language-sync/controller.d.ts"
+      ],
+      "request-language": [
+        "./dist/types/requestLanguage.d.ts"
+      ],
+      "native": [
+        "./dist/types/native.d.ts"
       ]
     }
   },
   "engines": {
-    "node": ">=26.7.0"
+    "node": ">=26.10.0"
   },
   "dependencies": {
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.9",
+    "@modern-js/renderer-core": "npm:@bleedingdev/modern-js-renderer-core@3.9.3-ultramodern.1",
+    "@modern-js/runtime-extensions": "npm:@bleedingdev/modern-js-runtime-extensions@3.9.3-ultramodern.1",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.3-ultramodern.1",
     "i18next-browser-languagedetector": "^8.2.1"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.9",
+    "@modern-js/runtime": "3.9.3-ultramodern.1",
+    "i18next": ">=25.7.4",
     "react": "^19.2.8"
   },
+  "peerDependenciesMeta": {
+    "@modern-js/runtime": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.9",
-    "@rslib/core": "1.0.0",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.3-ultramodern.1",
+    "@rslib/core": "1.0.3",
     "@scripts/rstest-config": "2.66.0",
-    "@types/node": "^26.4.1",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8"
+    "@types/node": "^26.6.3",
+    "i18next": "26.4.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "dev": "rslib build --watch",
     "build": "rslib build",
-    "test": "rstest --passWithNoTests"
+    "test": "rstest"
+  },
+  "ultramodern": {
+    "sourceName": "@modern-js/i18n-runtime-extensions"
   }
 }

package/src/index.ts

@@ -1,4 +1,4 @@
+export * from '@modern-js/runtime-extensions/localised-urls';
 export * from './language-sync/controller';
 export * from './language-sync/react';
 export * from './localeRedirectPolicy';
-export * from './localisedUrls/index';

package/src/localeRedirectPolicy.ts

@@ -1,11 +1,11 @@
-import type { LocalisedUrlsOption } from './localisedUrls/index';
+import type { LocalisedUrlsOption } from '@modern-js/runtime-extensions/localised-urls';
 import {
   isDefaultLocaleRedirectSkipPath,
   localiseTargetPathname,
   matchesPathPrefix,
   shouldSkipLocaleRedirect,
   stripLanguagePrefix,
-} from './localisedUrls/index';
+} from '@modern-js/runtime-extensions/localised-urls';
 
 interface LocaleRedirectRequest {
   url: string;

package/src/native.ts

@@ -0,0 +1,212 @@
+import type {
+  NativeEntryI18n,
+  NativeI18nResources,
+} from '@modern-js/renderer-core/entry-server';
+import type { LocalisedUrlsOption } from '@modern-js/runtime-extensions/localised-urls';
+import i18next, {
+  type BackendModule,
+  type i18n as I18nInstance,
+  type InitOptions,
+} from 'i18next';
+import { createLatestLanguageSyncBinding } from './language-sync/controller';
+import {
+  createRequestLanguageRedirect,
+  languageFromPathname,
+  type ResolveRequestLanguageOptions,
+  resolveRequestLanguage,
+} from './requestLanguage';
+import {
+  createI18nSsrHandoffInlineData,
+  readI18nSsrHandoff,
+} from './ssrLanguageHandoff';
+import { createI18nUrlRewrite } from './urlRewrite';
+
+export type { I18nInstance };
+
+export interface NativeI18nOptions extends ResolveRequestLanguageOptions {
+  /**
+   * JSON-serializable i18next `init` options. `lng`, `fallbackLng`,
+   * `supportedLngs`, `resources` and `ns` are owned by the native entry.
+   */
+  initOptions?: InitOptions;
+}
+
+/** language -> namespace -> lazily imported translation bundle. */
+export type NativeI18nLoaders = Readonly<
+  Record<string, Readonly<Record<string, () => Promise<unknown>>>>
+>;
+
+export type NativeI18n = NativeEntryI18n<I18nInstance, LocalisedUrlsOption>;
+
+function unwrapResource(module: unknown): Record<string, unknown> {
+  const resource =
+    typeof module === 'object' && module !== null && 'default' in module
+      ? module.default
+      : module;
+  return resource as Record<string, unknown>;
+}
+
+/**
+ * The localized routing and per-request i18next instances of a native
+ * Solid or Octane entry. Each language's bundles load on demand; an instance
+ * is never a module singleton.
+ */
+export function createNativeI18n(
+  options: NativeI18nOptions,
+  loaders: NativeI18nLoaders,
+): NativeI18n {
+  const { initOptions = {}, ...routing } = options;
+  const namespaces = [
+    ...new Set(Object.values(loaders).flatMap(Object.keys)),
+  ].sort();
+  const defaultNamespace =
+    typeof initOptions.defaultNS === 'string'
+      ? initOptions.defaultNS
+      : namespaces.includes('translation')
+        ? 'translation'
+        : (namespaces[0] ?? 'translation');
+  const cookie = routing.detection?.lookupCookie ?? 'i18next';
+  const backend: BackendModule = {
+    type: 'backend',
+    init() {},
+    read(language, namespace, callback) {
+      // Own keys only: `constructor` or `__proto__` never reaches Object.
+      const bundles = Object.hasOwn(loaders, language)
+        ? loaders[language]
+        : undefined;
+      const load =
+        bundles && Object.hasOwn(bundles, namespace)
+          ? bundles[namespace]
+          : undefined;
+      if (!load) {
+        callback(null, {});
+        return;
+      }
+      load().then(
+        module => callback(null, unwrapResource(module)),
+        error => callback(error as Error, false),
+      );
+    },
+  };
+  const currentLanguage = () =>
+    languageFromPathname(
+      window.location.pathname,
+      routing.languages,
+      routing.basePath,
+    );
+
+  return {
+    languages: routing.languages,
+    ...(routing.localisedUrls === undefined
+      ? {}
+      : { localisedUrls: routing.localisedUrls }),
+    resolveRequest: request => resolveRequestLanguage(request, routing),
+    redirect: createRequestLanguageRedirect,
+    async create(language, resources) {
+      // The default export resolves under both i18next module formats.
+      const instance = i18next.createInstance();
+      instance.use(backend);
+      await instance.init({
+        ...initOptions,
+        lng: language,
+        fallbackLng: routing.fallbackLanguage,
+        supportedLngs: [...routing.languages],
+        ns: namespaces,
+        defaultNS: defaultNamespace,
+        partialBundledLanguages: true,
+        resources: resources ? { [language]: resources } : {},
+        interpolation: { escapeValue: false, ...initOptions.interpolation },
+      });
+      return instance;
+    },
+    rewrite: getLanguage =>
+      createI18nUrlRewrite({
+        languages: routing.languages,
+        getLanguage,
+        localisedUrls: routing.localisedUrls,
+      }),
+    handoff(language, instance) {
+      return createI18nSsrHandoffInlineData({
+        language,
+        ...(instance
+          ? {
+              resources: Object.fromEntries(
+                namespaces.map(namespace => [
+                  namespace,
+                  (instance.getResourceBundle(language, namespace) ??
+                    {}) as Record<string, unknown>,
+                ]),
+              ) satisfies NativeI18nResources,
+            }
+          : {}),
+      });
+    },
+    clientHandoff() {
+      const handoff = readI18nSsrHandoff();
+      if (handoff && routing.languages.includes(handoff.language))
+        return handoff;
+      return { language: currentLanguage() ?? routing.fallbackLanguage };
+    },
+    syncWithRouter(router, instance) {
+      // Navigation to another language prefix switches the instance. A
+      // masked location (LocalizedLink to another language) publishes its
+      // language on the mask; the unmasked location stays canonical. Switches
+      // run through the shared sync policy: the latest URL language wins and
+      // rejected loads retry. When retries run out the router has already
+      // committed the URL, so a reload lets the server render that language.
+      const sync = createLatestLanguageSyncBinding<I18nInstance>();
+      sync.updateCallbacks({
+        changeLanguage: (target, language) => target.changeLanguage(language),
+        commitLanguage() {},
+        readLanguage: target => target.language,
+        reportFailure: () => window.location.reload(),
+      });
+      sync.activate(instance);
+      const unsubscribe = (router as LanguageRouter).subscribe(
+        'onBeforeLoad',
+        ({ toLocation }) => {
+          const publicHref =
+            toLocation.maskedLocation?.publicHref ?? toLocation.publicHref;
+          const pathname = new URL(publicHref, window.location.origin).pathname;
+          const language = languageFromPathname(
+            pathname,
+            routing.languages,
+            routing.basePath,
+          );
+          if (language) sync.request(language);
+        },
+      );
+      // A retired entry stops listening and retrying.
+      return () => {
+        unsubscribe();
+        sync.deactivate();
+      };
+    },
+    persist(instance) {
+      // Every language change reaches the document and the server's
+      // language detector, with or without a router.
+      const persist = (language: string) => {
+        document.documentElement.lang = language;
+        // biome-ignore lint/suspicious/noDocumentCookie: the server's language detector reads this cookie; CookieStore is not in every browser.
+        document.cookie = `${cookie}=${encodeURIComponent(language)}; path=/; max-age=31536000; samesite=lax`;
+      };
+      // The client starts in its URL's language, which a stale cookie from
+      // an earlier visit may not match; persist it before any later change.
+      if (instance.language) persist(instance.language);
+      instance.on('languageChanged', persist);
+      return () => instance.off('languageChanged', persist);
+    },
+  };
+}
+
+interface LanguageRouter {
+  subscribe(
+    event: 'onBeforeLoad',
+    listener: (event: {
+      toLocation: {
+        publicHref: string;
+        maskedLocation?: { publicHref: string };
+      };
+    }) => void,
+  ): () => void;
+}

package/src/paths.ts

@@ -1,15 +1,36 @@
-import { splitUrlTarget } from '@modern-js/runtime-utils/url';
 import {
   canonicalTargetPathname,
   type LocalisedUrlsOption,
   localiseTargetPathname,
-} from './localisedUrls';
+} from '@modern-js/runtime-extensions/localised-urls';
+import { splitUrlTarget } from '@modern-js/runtime-utils/url';
+
+export type { LocalisedUrlsOption };
 
 export interface LocalizedPathsConfig {
   languages: string[];
   localisedUrls?: LocalisedUrlsOption;
 }
 
+/**
+ * The configured spelling of a requested language, matched case-insensitively.
+ * Only a configured language has a locale prefix, so anything else throws
+ * rather than becoming an unknown path segment.
+ */
+export const configuredLanguage = (
+  requested: string,
+  languages: readonly string[],
+): string => {
+  const language = languages.find(
+    candidate => candidate.toLowerCase() === String(requested).toLowerCase(),
+  );
+  if (language === undefined)
+    throw new RangeError(
+      `Unsupported language "${requested}"; expected one of: ${languages.join(', ')}`,
+    );
+  return language;
+};
+
 /** Synchronous mapped URL construction, independent of React/plugin setup. */
 export const buildLocalizedUrl = (
   target: string,