@mpgd/i18n 0.1.0

package/dist/paraglide/runtime.js

@@ -0,0 +1,1852 @@
+/* eslint-disable */
+
+/** @type {any} */
+const URLPattern = {}
+
+/**
+ * The project's base locale.
+ *
+ * @example
+ *   if (locale === baseLocale) {
+ *     // do something
+ *   }
+ */
+export const baseLocale = "en";
+/**
+ * The project's locales that have been specified in the settings.
+ *
+ * @example
+ *   if (locales.includes(userSelectedLocale) === false) {
+ *     throw new Error('Locale is not available');
+ *   }
+ */
+export const locales = /** @type {const} */ (["en","ko"]);
+/** @type {string} */
+export const cookieName = "PARAGLIDE_LOCALE";
+/** @type {number} */
+export const cookieMaxAge = 34560000;
+/** @type {string} */
+export const cookieDomain = "";
+/** @type {string} */
+export const localStorageKey = "PARAGLIDE_LOCALE";
+/**
+ * @type {Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>}
+ */
+export const strategy = [
+  "cookie",
+  "globalVariable",
+  "baseLocale"
+];
+/**
+ * Route-level strategy overrides.
+ *
+ * `match` uses URLPattern syntax.
+ *
+ * @type {Array<{
+ *   match: string;
+ *   strategy?: Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>;
+ *   exclude?: boolean;
+ * }>}
+ */
+export const routeStrategies = [];
+/**
+ * The used URL patterns.
+ *
+ * @type {Array<{ pattern: string, localized: Array<[Locale, string]> }>}
+ */
+export const urlPatterns = [
+  {
+    "pattern": ":protocol://:domain(.*)::port?/:path(.*)?",
+    "localized": [
+      [
+        "ko",
+        ":protocol://:domain(.*)::port?/ko/:path(.*)?"
+      ],
+      [
+        "en",
+        ":protocol://:domain(.*)::port?/:path(.*)?"
+      ]
+    ]
+  }
+];
+/** @type {string | undefined} */
+let cachedRouteStrategyUrl;
+/** @type {{ match: string; strategy?: typeof strategy; exclude?: boolean } | undefined} */
+let cachedRouteStrategy;
+/**
+ * @param {string | URL} url
+ * @returns {{ match: string; strategy?: typeof strategy; exclude?: boolean } | undefined}
+ */
+function findMatchingRouteStrategy(url) {
+    if (routeStrategies.length === 0) {
+        return undefined;
+    }
+    const urlString = typeof url === "string" ? url : url.href;
+    if (cachedRouteStrategyUrl === urlString) {
+        return cachedRouteStrategy;
+    }
+    const urlObject = new URL(urlString, "http://dummy.com");
+    let match;
+    for (const routeStrategy of routeStrategies) {
+        const pattern = new URLPattern(routeStrategy.match, urlObject.href);
+        if (pattern.exec(urlObject.href)) {
+            match = routeStrategy;
+            break;
+        }
+    }
+    cachedRouteStrategyUrl = urlString;
+    cachedRouteStrategy = match;
+    return match;
+}
+/**
+ * Returns the strategy to use for a specific URL.
+ *
+ * If no route strategy matches (or the matching rule is `exclude: true`),
+ * the global strategy is returned.
+ *
+ * @param {string | URL} url
+ * @returns {typeof strategy}
+ */
+export function getStrategyForUrl(url) {
+    const routeStrategy = findMatchingRouteStrategy(url);
+    if (routeStrategy &&
+        routeStrategy.exclude !== true &&
+        Array.isArray(routeStrategy.strategy)) {
+        return routeStrategy.strategy;
+    }
+    return strategy;
+}
+/**
+ * Returns whether the given URL is excluded from middleware i18n processing.
+ *
+ * @param {string | URL} url
+ * @returns {boolean}
+ */
+export function isExcludedByRouteStrategy(url) {
+    return findMatchingRouteStrategy(url)?.exclude === true;
+}
+/**
+ * @typedef {{
+ * 		getStore(): {
+ *   		locale?: Locale,
+ * 			origin?: string,
+ * 			messageCalls?: Set<string>
+ *   	} | undefined,
+ * 		run: (store: { locale?: Locale, origin?: string, messageCalls?: Set<string>},
+ *    cb: any) => any
+ * }} ParaglideAsyncLocalStorage
+ */
+/**
+ * Server side async local storage that is set by `serverMiddleware()`.
+ *
+ * The variable is used to retrieve the locale and origin in a server-side
+ * rendering context without effecting other requests.
+ *
+ * @type {ParaglideAsyncLocalStorage | undefined}
+ */
+export let serverAsyncLocalStorage = undefined;
+export const disableAsyncLocalStorage = false;
+export const experimentalMiddlewareLocaleSplitting = false;
+export const isServer = typeof window === 'undefined';
+/** @type {Locale | undefined} */
+export const experimentalStaticLocale = undefined;
+/**
+ * Sets the server side async local storage.
+ *
+ * The function is needed because the `runtime.js` file
+ * must define the `serverAsyncLocalStorage` variable to
+ * avoid a circular import between `runtime.js` and
+ * `server.js` files.
+ *
+ * @param {ParaglideAsyncLocalStorage | undefined} value
+ */
+export function overwriteServerAsyncLocalStorage(value) {
+    serverAsyncLocalStorage = value;
+}
+const TREE_SHAKE_COOKIE_STRATEGY_USED = true;
+const TREE_SHAKE_URL_STRATEGY_USED = false;
+const TREE_SHAKE_GLOBAL_VARIABLE_STRATEGY_USED = true;
+const TREE_SHAKE_PREFERRED_LANGUAGE_STRATEGY_USED = false;
+const TREE_SHAKE_DEFAULT_URL_PATTERN_USED = true;
+const TREE_SHAKE_LOCAL_STORAGE_STRATEGY_USED = false;
+
+/** @type {any} */ (globalThis).__paraglide =
+	/** @type {any} */ (globalThis).__paraglide ?? {};
+/** @type {any} */ (globalThis).__paraglide.ssr =
+	/** @type {any} */ (globalThis).__paraglide.ssr ?? {};
+
+/**
+ * This is a fallback to get started with a custom
+ * strategy and avoid type errors.
+ *
+ * The implementation is overwritten
+ * by `overwriteGetLocale()` and `defineSetLocale()`.
+ *
+ * @type {Locale | undefined}
+ */
+let _locale;
+let localeInitiallySet = false;
+/**
+ * Get the current locale.
+ *
+ * The locale is resolved using your configured strategies (URL, cookie, localStorage, etc.)
+ * in the order they are defined. In SSR contexts, the locale is retrieved from AsyncLocalStorage
+ * which is set by the `paraglideMiddleware()`.
+ *
+ * @see https://paraglidejs.com/strategy - Configure locale detection strategies
+ *
+ * @example
+ *   if (getLocale() === 'de') {
+ *     console.log('Germany 🇩🇪');
+ *   } else if (getLocale() === 'nl') {
+ *     console.log('Netherlands 🇳🇱');
+ *   }
+ *
+ * @returns {Locale} The current locale.
+ */
+export let getLocale = () => {
+    if (experimentalStaticLocale !== undefined) {
+        return experimentalStaticLocale;
+    }
+    // if running in a server-side rendering context
+    // retrieve the locale from the async local storage
+    if (serverAsyncLocalStorage) {
+        const locale = serverAsyncLocalStorage?.getStore()?.locale;
+        if (locale) {
+            return locale;
+        }
+    }
+    let strategyToUse = strategy;
+    if (!isServer && typeof window !== "undefined" && window.location?.href) {
+        strategyToUse = getStrategyForUrl(window.location.href);
+    }
+    const resolved = resolveLocaleWithStrategies(strategyToUse, typeof window !== "undefined" ? window.location?.href : undefined);
+    if (resolved) {
+        if (!localeInitiallySet) {
+            _locale = resolved;
+            // https://github.com/opral/inlang-paraglide-js/issues/455
+            localeInitiallySet = true;
+            setLocale(resolved, { reload: false });
+        }
+        return resolved;
+    }
+    throw new Error("No locale found. Read the docs https://paraglidejs.com/errors#no-locale-found");
+};
+/**
+ * Resolve locale for a given URL using route-aware strategies.
+ *
+ * @param {string | URL} url
+ * @returns {Locale}
+ */
+export function getLocaleForUrl(url) {
+    if (experimentalStaticLocale !== undefined) {
+        return experimentalStaticLocale;
+    }
+    const strategyToUse = getStrategyForUrl(url);
+    const resolved = resolveLocaleWithStrategies(strategyToUse, typeof url === "string" ? url : url.href);
+    if (resolved) {
+        return resolved;
+    }
+    throw new Error("No locale found. Read the docs https://paraglidejs.com/errors#no-locale-found");
+}
+/**
+ * @param {typeof strategy} strategyToUse
+ * @param {string | undefined} urlForUrlStrategy
+ * @returns {Locale | undefined}
+ */
+function resolveLocaleWithStrategies(strategyToUse, urlForUrlStrategy) {
+    /** @type {string | undefined} */
+    let locale;
+    for (const strat of strategyToUse) {
+        if (TREE_SHAKE_COOKIE_STRATEGY_USED && strat === "cookie") {
+            locale = extractLocaleFromCookie();
+        }
+        else if (strat === "baseLocale") {
+            locale = baseLocale;
+        }
+        else if (TREE_SHAKE_URL_STRATEGY_USED &&
+            strat === "url" &&
+            !isServer &&
+            typeof urlForUrlStrategy === "string") {
+            locale = extractLocaleFromUrl(urlForUrlStrategy);
+        }
+        else if (TREE_SHAKE_GLOBAL_VARIABLE_STRATEGY_USED &&
+            strat === "globalVariable" &&
+            _locale !== undefined) {
+            locale = _locale;
+        }
+        else if (TREE_SHAKE_PREFERRED_LANGUAGE_STRATEGY_USED &&
+            strat === "preferredLanguage" &&
+            !isServer) {
+            locale = extractLocaleFromNavigator();
+        }
+        else if (TREE_SHAKE_LOCAL_STORAGE_STRATEGY_USED &&
+            strat === "localStorage" &&
+            !isServer) {
+            locale = localStorage.getItem(localStorageKey) ?? undefined;
+        }
+        else if (isCustomStrategy(strat) && customClientStrategies.has(strat)) {
+            const handler = customClientStrategies.get(strat);
+            if (handler) {
+                const result = handler.getLocale();
+                // Handle both sync and async results - skip async in sync getLocale
+                if (result instanceof Promise) {
+                    // Can't await in sync function, skip async strategies
+                    continue;
+                }
+                if (result !== undefined) {
+                    return assertIsLocale(result);
+                }
+            }
+        }
+        const matchedLocale = toLocale(locale);
+        if (matchedLocale) {
+            return matchedLocale;
+        }
+    }
+    return undefined;
+}
+/**
+ * Overwrite the `getLocale()` function.
+ *
+ * Use this function to overwrite how the locale is resolved. This is useful
+ * for custom locale resolution or advanced use cases like SSG with concurrent rendering.
+ *
+ * @see https://paraglidejs.com/strategy
+ *
+ * @example
+ *   overwriteGetLocale(() => {
+ *     return Cookies.get('locale') ?? baseLocale
+ *   });
+ *
+ * @param {() => Locale} fn - The new implementation for `getLocale()`.
+ */
+export const overwriteGetLocale = (fn) => {
+    getLocale = fn;
+};
+
+const rtlLanguages = new Set([
+    "ar",
+    "dv",
+    "fa",
+    "he",
+    "ks",
+    "ku",
+    "ps",
+    "sd",
+    "ug",
+    "ur",
+    "yi",
+]);
+/**
+ * Get writing direction for a locale.
+ *
+ * Uses `Intl.Locale` text info when available and falls back to a
+ * language-based RTL check for runtimes without `getTextInfo()`.
+ *
+ * @example
+ *   getTextDirection(); // "ltr" or "rtl" for current locale
+ *   getTextDirection("ar"); // "rtl"
+ *   getTextDirection("en"); // "ltr"
+ *
+ * @param {string} [locale] - Target locale. If not provided, uses `getLocale()`
+ * @returns {"ltr" | "rtl"}
+ */
+export function getTextDirection(locale = getLocale()) {
+    try {
+        const intlLocale = /** @type {Intl.Locale & {
+            getTextInfo?: () => { direction?: string };
+            textInfo?: { direction?: string };
+        }} */ (new Intl.Locale(locale));
+        const direction = intlLocale.getTextInfo?.().direction ?? intlLocale.textInfo?.direction;
+        if (direction === "ltr" || direction === "rtl") {
+            return direction;
+        }
+    }
+    catch {
+        // Ignore Intl.Locale parsing/runtime errors and use fallback below.
+    }
+    const language = locale.split("-")[0]?.toLowerCase();
+    return rtlLanguages.has(language ?? "") ? "rtl" : "ltr";
+}
+
+/**
+ * Navigates to the localized URL, or reloads the current page
+ *
+ * @param {string} [newLocation] The new location
+ */
+const navigateOrReload = (newLocation) => {
+    if (newLocation) {
+        // reload the page by navigating to the new url
+        window.location.href = newLocation;
+    }
+    else {
+        // reload the page to reflect the new locale
+        window.location.reload();
+    }
+};
+/**
+ * @typedef {(newLocale: Locale, options?: { reload?: boolean }) => void | Promise<void>} SetLocaleFn
+ */
+/**
+ * Set the locale.
+ *
+ * Updates the locale using your configured strategies (cookie, localStorage, URL, etc.).
+ * By default, this reloads the page on the client to reflect the new locale. Reloading
+ * can be disabled by passing `reload: false` as an option, but you'll need to ensure
+ * the UI updates to reflect the new locale.
+ *
+ * If any custom strategy's `setLocale` function is async, then this function
+ * will become async as well.
+ *
+ * @see https://paraglidejs.com/strategy
+ *
+ * @example
+ *   setLocale('en');
+ *
+ * @example
+ *   setLocale('en', { reload: false });
+ *
+ * @type {SetLocaleFn}
+ */
+export let setLocale = (newLocale, options) => {
+    const optionsWithDefaults = {
+        reload: true,
+        ...options,
+    };
+    // locale is already set
+    // https://github.com/opral/inlang-paraglide-js/issues/430
+    /** @type {Locale | undefined} */
+    let currentLocale;
+    try {
+        currentLocale = getLocale();
+    }
+    catch {
+        // do nothing, no locale has been set yet.
+    }
+    /** @type {Array<Promise<void>>} */
+    const customSetLocalePromises = [];
+    /** @type {string | undefined} */
+    let newLocation = undefined;
+    let strategyToUse = strategy;
+    if (!isServer && typeof window !== "undefined" && window.location?.href) {
+        strategyToUse = getStrategyForUrl(window.location.href);
+    }
+    for (const strat of strategyToUse) {
+        if (TREE_SHAKE_GLOBAL_VARIABLE_STRATEGY_USED &&
+            strat === "globalVariable") {
+            // a default for a custom strategy to get started quickly
+            // is likely overwritten by `defineSetLocale()`
+            _locale = newLocale;
+        }
+        else if (TREE_SHAKE_COOKIE_STRATEGY_USED && strat === "cookie") {
+            if (isServer ||
+                typeof document === "undefined" ||
+                typeof window === "undefined") {
+                continue;
+            }
+            // set the cookie
+            const cookieString = `${cookieName}=${newLocale}; path=/; max-age=${cookieMaxAge}`;
+            document.cookie = cookieDomain
+                ? `${cookieString}; domain=${cookieDomain}`
+                : cookieString;
+            clearLocaleCookieCache();
+        }
+        else if (strat === "baseLocale") {
+            // nothing to be set here. baseLocale is only a fallback
+            continue;
+        }
+        else if (TREE_SHAKE_URL_STRATEGY_USED &&
+            strat === "url" &&
+            typeof window !== "undefined") {
+            // route to the new url
+            //
+            // this triggers a page reload but a user rarely
+            // switches locales, so this should be fine.
+            //
+            // if the behavior is not desired, the implementation
+            // can be overwritten by `defineSetLocale()` to avoid
+            // a full page reload.
+            newLocation = localizeUrl(window.location.href, {
+                locale: newLocale,
+            }).href;
+        }
+        else if (TREE_SHAKE_LOCAL_STORAGE_STRATEGY_USED &&
+            strat === "localStorage" &&
+            typeof window !== "undefined") {
+            // set the localStorage
+            localStorage.setItem(localStorageKey, newLocale);
+        }
+        else if (isCustomStrategy(strat) && customClientStrategies.has(strat)) {
+            const handler = customClientStrategies.get(strat);
+            if (handler) {
+                let result = handler.setLocale(newLocale);
+                // Handle async setLocale
+                if (result instanceof Promise) {
+                    result = result.catch((error) => {
+                        throw new Error(`Custom strategy "${strat}" setLocale failed.`, {
+                            cause: error,
+                        });
+                    });
+                    customSetLocalePromises.push(result);
+                }
+            }
+        }
+    }
+    const runReload = () => {
+        if (!isServer &&
+            optionsWithDefaults.reload &&
+            window.location &&
+            newLocale !== currentLocale) {
+            navigateOrReload(newLocation);
+        }
+    };
+    if (customSetLocalePromises.length) {
+        return Promise.all(customSetLocalePromises).then(() => {
+            runReload();
+        });
+    }
+    runReload();
+    return;
+};
+/**
+ * Overwrite the `setLocale()` function.
+ *
+ * Use this function to overwrite how the locale is set. For example,
+ * modify a cookie, env variable, or a user's preference.
+ *
+ * @example
+ *   overwriteSetLocale((newLocale) => {
+ *     // set the locale in a cookie
+ *     return Cookies.set('locale', newLocale)
+ *   });
+ *
+ * @param {SetLocaleFn} fn
+ */
+export const overwriteSetLocale = (fn) => {
+    setLocale = fn;
+};
+
+/**
+ * The origin of the current URL.
+ *
+ * Defaults to "http://y.com" in non-browser environments. If this
+ * behavior is not desired, the implementation can be overwritten
+ * by `overwriteGetUrlOrigin()`.
+ *
+ * @type {() => string}
+ */
+export let getUrlOrigin = () => {
+    if (serverAsyncLocalStorage) {
+        return serverAsyncLocalStorage.getStore()?.origin ?? "http://fallback.com";
+    }
+    else if (typeof window !== "undefined") {
+        return window.location.origin;
+    }
+    return "http://fallback.com";
+};
+/**
+ * Overwrite the getUrlOrigin function.
+ *
+ * Use this function in server environments to
+ * define how the URL origin is resolved.
+ *
+ * @param {() => string} fn - The new implementation for `getUrlOrigin()`.
+ */
+export let overwriteGetUrlOrigin = (fn) => {
+    getUrlOrigin = fn;
+};
+
+/**
+ * Coerces a locale-like string to the canonical locale value used by the runtime.
+ *
+ * @param {unknown} value
+ * @returns {Locale | undefined}
+ */
+export function toLocale(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const lowerValue = value.toLowerCase();
+    for (const locale of locales) {
+        if (locale.toLowerCase() === lowerValue) {
+            return locale;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if something is an available locale with the canonical project casing.
+ *
+ * @example
+ *   if (isLocale(params.locale)) {
+ *     setLocale(params.locale);
+ *   } else {
+ *     setLocale('en');
+ *   }
+ *
+ * Use `toLocale()` when you want case-insensitive matching and canonicalization.
+ *
+ * @param {unknown} locale
+ * @returns {locale is Locale}
+ */
+export function isLocale(locale) {
+    return !!locale && locales.some((item) => item === locale);
+}
+/**
+ * Asserts that the input can be normalized to a locale.
+ *
+ * @param {unknown} input - The input to check.
+ * @returns {Locale} The input normalized to a Locale.
+ * @throws {Error} If the input is not a locale.
+ */
+export function assertIsLocale(input) {
+    const locale = toLocale(input);
+    if (locale)
+        return locale;
+    throw new Error(`Invalid locale: ${input}. Expected one of: ${locales.join(", ")}`);
+}
+
+/**
+ * @typedef {object} ExtractLocaleFromRequestOptions
+ * @property {string | URL} [effectiveRequestUrl] - Effective request URL to use for route matching and locale detection with the URL strategy.
+ */
+/**
+ * Extracts a locale from a request.
+ *
+ * Use the function on the server to extract the locale
+ * from a request.
+ *
+ * The function goes through the strategies in the order
+ * they are defined. If a strategy returns an invalid locale,
+ * it will fall back to the next strategy.
+ *
+ * Note: Custom server strategies are not supported in this synchronous version.
+ * Use `extractLocaleFromRequestAsync` if you need custom server strategies with async getLocale methods.
+ *
+ * @example
+ *   const locale = extractLocaleFromRequest(request);
+ *
+ * @param {Request} request
+ * @param {ExtractLocaleFromRequestOptions} [options]
+ * @returns {Locale}
+ */
+export const extractLocaleFromRequest = (request, options = {}) => {
+    const effectiveRequestUrl = resolveEffectiveRequestUrl(request, options.effectiveRequestUrl);
+    return extractLocaleFromRequestWithStrategies(request, getStrategyForUrl(effectiveRequestUrl), effectiveRequestUrl);
+};
+/**
+ * Extracts a locale from a request using the provided strategy order.
+ *
+ * @param {Request} request
+ * @param {typeof strategy} strategies
+ * @param {string | URL} [url]
+ * @returns {Locale}
+ */
+export const extractLocaleFromRequestWithStrategies = (request, strategies, url = request.url) => {
+    const effectiveRequestUrl = resolveEffectiveRequestUrl(request, url);
+    /** @type {string|undefined} */
+    let locale;
+    for (const strat of strategies) {
+        if (TREE_SHAKE_COOKIE_STRATEGY_USED && strat === "cookie") {
+            const cookiePrefix = cookieName + "=";
+            locale = request.headers
+                .get("cookie")
+                ?.split(";")
+                .map((c) => c.trim())
+                .find((c) => c.startsWith(cookiePrefix))
+                ?.slice(cookiePrefix.length);
+        }
+        else if (TREE_SHAKE_URL_STRATEGY_USED && strat === "url") {
+            locale = extractLocaleFromUrl(effectiveRequestUrl);
+        }
+        else if (TREE_SHAKE_PREFERRED_LANGUAGE_STRATEGY_USED &&
+            strat === "preferredLanguage") {
+            locale = extractLocaleFromHeader(request);
+        }
+        else if (strat === "globalVariable") {
+            locale = _locale;
+        }
+        else if (strat === "baseLocale") {
+            return baseLocale;
+        }
+        else if (strat === "localStorage") {
+            continue;
+        }
+        else if (isCustomStrategy(strat)) {
+            // Custom strategies are not supported in sync version
+            // Use extractLocaleFromRequestAsync for custom server strategies
+            continue;
+        }
+        const matchedLocale = toLocale(locale);
+        if (matchedLocale) {
+            return matchedLocale;
+        }
+    }
+    throw new Error("No locale found. There is an error in your strategy. Try adding 'baseLocale' as the very last strategy. Read more here https://paraglidejs.com/errors#no-locale-found");
+};
+/**
+ * @param {Request} request
+ * @param {string | URL | undefined} effectiveRequestUrl
+ * @returns {URL}
+ */
+function resolveEffectiveRequestUrl(request, effectiveRequestUrl = request.url) {
+    if (effectiveRequestUrl instanceof URL) {
+        return new URL(effectiveRequestUrl.href);
+    }
+    return new URL(effectiveRequestUrl, request.url);
+}
+
+/**
+ * Asynchronously extracts a locale from a request.
+ *
+ * This function supports async custom server strategies, unlike the synchronous
+ * `extractLocaleFromRequest`. Use this function when you have custom server strategies
+ * that need to perform asynchronous operations (like database calls) in their getLocale method.
+ *
+ * The function first processes any custom server strategies asynchronously, then falls back
+ * to the synchronous `extractLocaleFromRequest` for all other strategies.
+ *
+ * @see {@link https://github.com/opral/inlang-paraglide-js/issues/527#issuecomment-2978151022}
+ *
+ * @example
+ *   // Basic usage
+ *   const locale = await extractLocaleFromRequestAsync(request);
+ *
+ * @example
+ *   // With custom async server strategy
+ *   defineCustomServerStrategy("custom-database", {
+ *     getLocale: async (request) => {
+ *       const userId = extractUserIdFromRequest(request);
+ *       return await getUserLocaleFromDatabase(userId);
+ *     }
+ *   });
+ *
+ *   const locale = await extractLocaleFromRequestAsync(request);
+ *
+ * @param {Request} request - The request object to extract the locale from.
+ * @param {{ effectiveRequestUrl?: string | URL }} [options] - Effective request URL to use for route matching and locale detection with the URL strategy.
+ * @returns {Promise<Locale>} The extracted locale.
+ */
+export const extractLocaleFromRequestAsync = async (request, options = {}) => {
+    /** @type {string|undefined} */
+    let locale;
+    const effectiveRequestUrl = resolveEffectiveRequestUrlFromRequestAsync(request, options.effectiveRequestUrl);
+    const strategy = getStrategyForUrl(effectiveRequestUrl);
+    // Process custom strategies first, in order
+    for (const strat of strategy) {
+        if (isCustomStrategy(strat) && customServerStrategies.has(strat)) {
+            const handler = customServerStrategies.get(strat);
+            if (handler) {
+                /** @type {string|undefined} */
+                locale = await handler.getLocale(request);
+            }
+            // If we got a valid locale from this custom strategy, use it
+            const matchedLocale = toLocale(locale);
+            if (matchedLocale) {
+                return matchedLocale;
+            }
+        }
+    }
+    // If no custom strategy provided a valid locale, fall back to sync version
+    return extractLocaleFromRequestWithStrategies(request, strategy, effectiveRequestUrl);
+};
+/**
+ * @param {Request} request
+ * @param {string | URL | undefined} effectiveRequestUrl
+ * @returns {URL}
+ */
+function resolveEffectiveRequestUrlFromRequestAsync(request, effectiveRequestUrl = request.url) {
+    if (effectiveRequestUrl instanceof URL) {
+        return new URL(effectiveRequestUrl.href);
+    }
+    return new URL(effectiveRequestUrl, request.url);
+}
+
+const cookieNamePattern = cookieName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const localeCookiePattern = new RegExp(`(?:^|;\\s*)${cookieNamePattern}=([^;]*)`);
+const noCachedLocale = Symbol();
+/** @type {Locale | undefined | typeof noCachedLocale} */
+let cachedLocaleFromCookie = noCachedLocale;
+/**
+ * Clears the cached locale from `document.cookie`.
+ */
+function clearLocaleCookieCache() {
+    cachedLocaleFromCookie = noCachedLocale;
+}
+function scheduleLocaleCookieCacheClear() {
+    if (typeof queueMicrotask === "function") {
+        queueMicrotask(clearLocaleCookieCache);
+    }
+    else {
+        Promise.resolve().then(clearLocaleCookieCache);
+    }
+}
+/**
+ * Extracts a cookie from the document.
+ *
+ * Will return undefined if the document is not available or if the cookie is not set.
+ * The `document` object is not available in server-side rendering, so this function should not be called in that context.
+ *
+ * @returns {Locale | undefined}
+ */
+export function extractLocaleFromCookie() {
+    if (typeof document === "undefined") {
+        return;
+    }
+    if (cachedLocaleFromCookie !== noCachedLocale) {
+        return cachedLocaleFromCookie;
+    }
+    const match = document.cookie.match(localeCookiePattern);
+    const locale = match?.[1];
+    cachedLocaleFromCookie = toLocale(locale);
+    scheduleLocaleCookieCacheClear();
+    return cachedLocaleFromCookie;
+}
+
+/**
+ * Extracts a locale from the accept-language header.
+ *
+ * Use the function on the server to extract the locale
+ * from the accept-language header that is sent by the client.
+ *
+ * @example
+ *   const locale = extractLocaleFromHeader(request);
+ *
+ * @param {Request} request - The request object to extract the locale from.
+ * @returns {Locale | undefined} The negotiated preferred language.
+ */
+export function extractLocaleFromHeader(request) {
+    const acceptLanguageHeader = request.headers.get("accept-language");
+    if (acceptLanguageHeader) {
+        // Parse language preferences with their q-values and base language codes
+        const languages = acceptLanguageHeader
+            .split(",")
+            .map((lang) => {
+            const [tag, q = "1"] = lang.trim().split(";q=");
+            // Get both the full tag and base language code
+            const baseTag = tag?.split("-")[0];
+            return {
+                fullTag: tag,
+                baseTag,
+                q: Number(q),
+            };
+        })
+            .sort((a, b) => b.q - a.q);
+        for (const lang of languages) {
+            const fullLocale = toLocale(lang.fullTag);
+            if (fullLocale) {
+                return fullLocale;
+            }
+            const baseLocale = toLocale(lang.baseTag);
+            if (baseLocale) {
+                return baseLocale;
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+}
+
+/**
+ * Negotiates a preferred language from navigator.languages.
+ *
+ * Use the function on the client to extract the locale
+ * from the navigator.languages array.
+ *
+ * @example
+ *   const locale = extractLocaleFromNavigator();
+ *
+ * @returns {Locale | undefined}
+ */
+export function extractLocaleFromNavigator() {
+    if (!navigator?.languages?.length) {
+        return undefined;
+    }
+    const languages = navigator.languages.map((lang) => ({
+        fullTag: lang,
+        baseTag: lang.split("-")[0],
+    }));
+    for (const lang of languages) {
+        const fullLocale = toLocale(lang.fullTag);
+        if (fullLocale) {
+            return fullLocale;
+        }
+        const baseLocale = toLocale(lang.baseTag);
+        if (baseLocale) {
+            return baseLocale;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * If extractLocaleFromUrl is called many times on the same page and the URL
+ * hasn't changed, we don't need to recompute it every time which can get expensive.
+ * We might use a LRU cache if needed, but for now storing only the last result is enough.
+ * https://github.com/opral/monorepo/pull/3575#discussion_r2066731243
+ */
+/** @type {string|undefined} */
+let cachedUrl;
+/** @type {Locale|undefined} */
+let cachedLocale;
+/**
+ * Extracts the locale from a given URL using native URLPattern.
+ *
+ * The built-in default `/:locale/...` routing is case-insensitive because it
+ * canonicalizes the first path segment with `toLocale()`. Custom `urlPatterns`
+ * keep URLPattern's normal exact matching semantics for path segments.
+ *
+ * @param {URL|string} url - The full URL from which to extract the locale.
+ * @returns {Locale|undefined} The extracted locale, or undefined if no locale is found.
+ */
+export function extractLocaleFromUrl(url) {
+    const urlString = typeof url === "string" ? url : url.href;
+    if (cachedUrl === urlString) {
+        return cachedLocale;
+    }
+    /** @type {Locale | undefined} */
+    let result;
+    if (TREE_SHAKE_DEFAULT_URL_PATTERN_USED) {
+        result = defaultUrlPatternExtractLocale(url);
+    }
+    else {
+        const urlObj = typeof url === "string" ? new URL(url) : url;
+        // Iterate over URL patterns
+        for (const element of urlPatterns) {
+            for (const [locale, localizedPattern] of element.localized) {
+                const match = new URLPattern(localizedPattern, urlObj.href).exec(urlObj.href);
+                if (match) {
+                    result = locale;
+                    break;
+                }
+            }
+            if (result)
+                break;
+        }
+    }
+    cachedUrl = urlString;
+    cachedLocale = result;
+    return result;
+}
+/**
+ * https://github.com/opral/inlang-paraglide-js/issues/381
+ *
+ * @param {URL | string} url - The full URL from which to extract the locale.
+ * @returns {Locale | undefined} The extracted locale, or undefined if no locale is found.
+ */
+function defaultUrlPatternExtractLocale(url) {
+    const urlObj = new URL(url, "http://dummy.com");
+    const pathSegments = urlObj.pathname.split("/").filter(Boolean);
+    return toLocale(pathSegments[0]) || baseLocale;
+}
+
+/**
+ * Lower-level URL localization function, primarily used in server contexts.
+ *
+ * This function is designed for server-side usage where you need precise control
+ * over URL localization, such as in middleware or request handlers. It works with
+ * URL objects and always returns absolute URLs.
+ *
+ * For client-side UI components, use `localizeHref()` instead, which provides
+ * a more convenient API with relative paths and automatic locale detection.
+ *
+ * @see https://paraglidejs.com/i18n-routing
+ *
+ * @example
+ * ```typescript
+ * // Server middleware example
+ * app.use((req, res, next) => {
+ *   const url = new URL(req.url, `${req.protocol}://${req.headers.host}`);
+ *   const localized = localizeUrl(url, { locale: "de" });
+ *
+ *   if (localized.href !== url.href) {
+ *     return res.redirect(localized.href);
+ *   }
+ *   next();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with URL patterns
+ * const url = new URL("https://example.com/about");
+ * localizeUrl(url, { locale: "de" });
+ * // => URL("https://example.com/de/about")
+ *
+ * // Using with domain-based localization
+ * const url = new URL("https://example.com/store");
+ * localizeUrl(url, { locale: "de" });
+ * // => URL("https://de.example.com/store")
+ * ```
+ *
+ * @param {string | URL} url - The URL to localize. If string, must be absolute.
+ * @param {object} [options] - Options for localization
+ * @param {Locale} [options.locale] - Target locale. If not provided, uses getLocale()
+ * @returns {URL} The localized URL, always absolute
+ */
+export function localizeUrl(url, options) {
+    const targetLocale = options?.locale
+        ? assertIsLocale(options?.locale)
+        : getLocale();
+    if (TREE_SHAKE_DEFAULT_URL_PATTERN_USED) {
+        return localizeUrlDefaultPattern(url, targetLocale);
+    }
+    const urlObj = typeof url === "string" ? new URL(url) : url;
+    // Iterate over URL patterns
+    for (const element of urlPatterns) {
+        // match localized patterns
+        for (const [, localizedPattern] of element.localized) {
+            const match = new URLPattern(localizedPattern, urlObj.href).exec(urlObj.href);
+            if (!match) {
+                continue;
+            }
+            const targetPattern = element.localized.find(([locale]) => locale === targetLocale)?.[1];
+            if (!targetPattern) {
+                continue;
+            }
+            const localizedUrl = fillPattern(targetPattern, aggregateGroups(match), urlObj.origin);
+            return fillMissingUrlParts(localizedUrl, match);
+        }
+        const unlocalizedMatch = new URLPattern(element.pattern, urlObj.href).exec(urlObj.href);
+        if (unlocalizedMatch) {
+            const targetPattern = element.localized.find(([locale]) => locale === targetLocale)?.[1];
+            if (targetPattern) {
+                const localizedUrl = fillPattern(targetPattern, aggregateGroups(unlocalizedMatch), urlObj.origin);
+                return fillMissingUrlParts(localizedUrl, unlocalizedMatch);
+            }
+        }
+    }
+    // If no match found, return the original URL
+    return urlObj;
+}
+/**
+ * https://github.com/opral/inlang-paraglide-js/issues/381
+ *
+ * @param {string | URL} url
+ * @param {Locale} locale
+ * @returns {URL}
+ */
+function localizeUrlDefaultPattern(url, locale) {
+    const urlObj = typeof url === "string" ? new URL(url, getUrlOrigin()) : new URL(url);
+    const currentLocale = extractLocaleFromUrl(urlObj);
+    // If current locale matches target locale, no change needed
+    if (currentLocale === locale) {
+        return urlObj;
+    }
+    const pathSegments = urlObj.pathname.split("/").filter(Boolean);
+    // If current path starts with a locale, remove it
+    if (pathSegments.length > 0 && toLocale(pathSegments[0])) {
+        pathSegments.shift();
+    }
+    // For base locale, don't add prefix
+    if (locale === baseLocale) {
+        urlObj.pathname = "/" + pathSegments.join("/");
+    }
+    else {
+        // For other locales, add prefix
+        urlObj.pathname = "/" + locale + "/" + pathSegments.join("/");
+    }
+    return urlObj;
+}
+/**
+ * Low-level URL de-localization function, primarily used in server contexts.
+ *
+ * This function is designed for server-side usage where you need precise control
+ * over URL de-localization, such as in middleware or request handlers. It works with
+ * URL objects and always returns absolute URLs.
+ *
+ * For client-side UI components, use `deLocalizeHref()` instead, which provides
+ * a more convenient API with relative paths.
+ *
+ * @see https://paraglidejs.com/i18n-routing
+ *
+ * @example
+ * ```typescript
+ * // Server middleware example
+ * app.use((req, res, next) => {
+ *   const url = new URL(req.url, `${req.protocol}://${req.headers.host}`);
+ *   const baseUrl = deLocalizeUrl(url);
+ *
+ *   // Store the base URL for later use
+ *   req.baseUrl = baseUrl;
+ *   next();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with URL patterns
+ * const url = new URL("https://example.com/de/about");
+ * deLocalizeUrl(url); // => URL("https://example.com/about")
+ *
+ * // Using with domain-based localization
+ * const url = new URL("https://de.example.com/store");
+ * deLocalizeUrl(url); // => URL("https://example.com/store")
+ * ```
+ *
+ * @param {string | URL} url - The URL to de-localize. If string, must be absolute.
+ * @returns {URL} The de-localized URL, always absolute
+ */
+export function deLocalizeUrl(url) {
+    if (TREE_SHAKE_DEFAULT_URL_PATTERN_USED) {
+        return deLocalizeUrlDefaultPattern(url);
+    }
+    const urlObj = typeof url === "string" ? new URL(url) : url;
+    // Iterate over URL patterns
+    for (const element of urlPatterns) {
+        // Iterate over localized versions
+        for (const [, localizedPattern] of element.localized) {
+            const match = new URLPattern(localizedPattern, urlObj.href).exec(urlObj.href);
+            if (match) {
+                // Convert localized URL back to the base pattern
+                const groups = aggregateGroups(match);
+                const baseUrl = fillPattern(element.pattern, groups, urlObj.origin);
+                return fillMissingUrlParts(baseUrl, match);
+            }
+        }
+        // match unlocalized pattern
+        const unlocalizedMatch = new URLPattern(element.pattern, urlObj.href).exec(urlObj.href);
+        if (unlocalizedMatch) {
+            const baseUrl = fillPattern(element.pattern, aggregateGroups(unlocalizedMatch), urlObj.origin);
+            return fillMissingUrlParts(baseUrl, unlocalizedMatch);
+        }
+    }
+    // no match found return the original url
+    return urlObj;
+}
+/**
+ * De-localizes a URL using the default pattern (/:locale/*)
+ * @param {string|URL} url
+ * @returns {URL}
+ */
+function deLocalizeUrlDefaultPattern(url) {
+    const urlObj = typeof url === "string" ? new URL(url, getUrlOrigin()) : new URL(url);
+    const pathSegments = urlObj.pathname.split("/").filter(Boolean);
+    // If first segment is a locale, remove it
+    if (pathSegments.length > 0 && toLocale(pathSegments[0])) {
+        urlObj.pathname = "/" + pathSegments.slice(1).join("/");
+    }
+    return urlObj;
+}
+/**
+ * Takes matches of implicit wildcards in the UrlPattern (when a part is missing
+ * it is equal to '*') and adds them back to the result of fillPattern.
+ *
+ * At least protocol and hostname are required to create a valid URL inside fillPattern.
+ *
+ * @param {URL} url
+ * @param {any} match
+ * @returns {URL}
+ */
+function fillMissingUrlParts(url, match) {
+    if (match.protocol.groups["0"]) {
+        url.protocol = match.protocol.groups["0"] ?? "";
+    }
+    if (match.hostname.groups["0"]) {
+        url.hostname = match.hostname.groups["0"] ?? "";
+    }
+    if (match.username.groups["0"]) {
+        url.username = match.username.groups["0"] ?? "";
+    }
+    if (match.password.groups["0"]) {
+        url.password = match.password.groups["0"] ?? "";
+    }
+    if (match.port.groups["0"]) {
+        url.port = match.port.groups["0"] ?? "";
+    }
+    if (match.pathname.groups["0"]) {
+        url.pathname = match.pathname.groups["0"] ?? "";
+    }
+    if (match.search.groups["0"]) {
+        url.search = match.search.groups["0"] ?? "";
+    }
+    if (match.hash.groups["0"]) {
+        url.hash = match.hash.groups["0"] ?? "";
+    }
+    return url;
+}
+/**
+ * Fills a URL pattern with values for named groups, supporting all URLPattern-style modifiers.
+ *
+ * This function will eventually be replaced by https://github.com/whatwg/urlpattern/issues/73
+ *
+ * Matches:
+ * - :name        -> Simple
+ * - :name?       -> Optional
+ * - :name+       -> One or more
+ * - :name*       -> Zero or more
+ * - :name(...)   -> Regex group
+ * - {text}       -> Group delimiter
+ * - {text}?      -> Optional group delimiter
+ *
+ * If the value is `null`, the segment is removed.
+ *
+ * @param {string} pattern - The URL pattern containing named groups.
+ * @param {Record<string, string | null | undefined>} values - Object of values for named groups.
+ * @param {string} origin - Base URL to use for URL construction.
+ * @returns {URL} - The constructed URL with named groups filled.
+ */
+function fillPattern(pattern, values, origin) {
+    // Pre-process the pattern to handle explicit port numbers
+    // This detects patterns like "http://localhost:5173" and protects the port number
+    // from being interpreted as a parameter
+    let processedPattern = pattern.replace(/(https?:\/\/[^:/]+):(\d+)(\/|$)/g, (_, protocol, port, slash) => {
+        // Replace ":5173" with "#PORT-5173#" to protect it from parameter replacement
+        return `${protocol}#PORT-${port}#${slash}`;
+    });
+    // First, handle group delimiters with curly braces
+    let processedGroupDelimiters = processedPattern.replace(/\{([^{}]*)\}([?+*]?)/g, (_, content, modifier) => {
+        // For optional group delimiters
+        if (modifier === "?") {
+            // For optional groups, we'll include the content
+            return content;
+        }
+        // For non-optional group delimiters, always include the content
+        return content;
+    });
+    // Then handle named groups
+    let filled = processedGroupDelimiters.replace(/(\/?):([a-zA-Z0-9_]+)(\([^)]*\))?([?+*]?)/g, (_, slash, name, __, modifier) => {
+        const value = values[name];
+        if (value === null) {
+            // If value is null, remove the entire segment including the preceding slash
+            return "";
+        }
+        if (modifier === "?") {
+            // Optional segment
+            return value !== undefined ? `${slash}${value}` : "";
+        }
+        if (modifier === "+" || modifier === "*") {
+            // Repeatable segments
+            if (value === undefined && modifier === "+") {
+                throw new Error(`Missing value for "${name}" (one or more required)`);
+            }
+            return value ? `${slash}${value}` : "";
+        }
+        // Simple named group (no modifier)
+        if (value === undefined) {
+            throw new Error(`Missing value for "${name}"`);
+        }
+        return `${slash}${value}`;
+    });
+    // Restore port numbers
+    filled = filled.replace(/#PORT-(\d+)#/g, ":$1");
+    return new URL(filled, origin);
+}
+/**
+ * Aggregates named groups from various parts of the URLPattern match result.
+ *
+ *
+ * @param {any} match - The URLPattern match result object.
+ * @returns {Record<string, string | null | undefined>} An object containing all named groups from the match.
+ */
+export function aggregateGroups(match) {
+    return {
+        ...match.hash.groups,
+        ...match.hostname.groups,
+        ...match.password.groups,
+        ...match.pathname.groups,
+        ...match.port.groups,
+        ...match.protocol.groups,
+        ...match.search.groups,
+        ...match.username.groups,
+    };
+}
+
+/**
+ * @typedef {object} ShouldRedirectServerInput
+ * @property {Request} request
+ * @property {string | URL} [effectiveRequestUrl] - Effective request URL to use for route matching, locale detection with the URL strategy, and redirect targets.
+ * @property {Locale} [locale]
+ *
+ * @typedef {object} ShouldRedirectClientInput
+ * @property {undefined} [request]
+ * @property {string | URL} [url]
+ * @property {Locale} [locale]
+ *
+ * @typedef {ShouldRedirectServerInput | ShouldRedirectClientInput} ShouldRedirectInput
+ *
+ * @typedef {object} ShouldRedirectResult
+ * @property {boolean} shouldRedirect - Indicates whether the consumer should perform a redirect.
+ * @property {Locale} locale - Locale resolved using the configured strategies.
+ * @property {URL | undefined} redirectUrl - Destination URL when a redirect is required.
+ */
+/**
+ * Determines whether a redirect is required to align the current URL with the active locale.
+ *
+ * This helper mirrors the logic that powers `paraglideMiddleware`, but works in both server
+ * and client environments. It evaluates the configured strategies in order, computes the
+ * canonical localized URL, and reports when the current URL does not match.
+ *
+ * When called in the browser without arguments, the current `window.location.href` is used.
+ *
+ * @see https://paraglidejs.com/i18n-routing#redirects
+ *
+ * @example
+ * // Client side usage (e.g. TanStack Router beforeLoad hook)
+ * async function beforeLoad({ location }) {
+ *   const decision = await shouldRedirect({ url: location.href });
+ *
+ *   if (decision.shouldRedirect) {
+ *     throw redirect({ to: decision.redirectUrl.href });
+ *   }
+ * }
+ *
+ * @example
+ * // Server side usage with a Request
+ * export async function handle(request) {
+ *   const decision = await shouldRedirect({ request });
+ *
+ *   if (decision.shouldRedirect) {
+ *     return Response.redirect(decision.redirectUrl, 307);
+ *   }
+ *
+ *   return render(request, decision.locale);
+ * }
+ *
+ * @example
+ * // Server side usage behind a proxy where request.url is not public-facing
+ * export async function handle(request) {
+ *   const effectiveRequestUrl = new URL(request.url);
+ *   effectiveRequestUrl.protocol = "https:";
+ *   effectiveRequestUrl.host = "example.com";
+ *
+ *   const decision = await shouldRedirect({
+ *     request,
+ *     effectiveRequestUrl,
+ *   });
+ *
+ *   if (decision.shouldRedirect) {
+ *     return Response.redirect(decision.redirectUrl, 307);
+ *   }
+ * }
+ *
+ * @param {ShouldRedirectInput} [input]
+ * @returns {Promise<ShouldRedirectResult>}
+ */
+export async function shouldRedirect(input = {}) {
+    const currentUrl = resolveUrl(input);
+    const locale = await resolveLocale(input, currentUrl);
+    const strategy = getStrategyForUrl(currentUrl.href);
+    if (isExcludedByRouteStrategy(currentUrl.href) || !strategy.includes("url")) {
+        return { shouldRedirect: false, locale, redirectUrl: undefined };
+    }
+    const localizedUrl = localizeUrl(currentUrl.href, { locale });
+    const shouldRedirectToLocalizedUrl = normalizeUrl(localizedUrl.href) !== normalizeUrl(currentUrl.href);
+    return {
+        shouldRedirect: shouldRedirectToLocalizedUrl,
+        locale,
+        redirectUrl: shouldRedirectToLocalizedUrl ? localizedUrl : undefined,
+    };
+}
+/**
+ * Resolves the locale either from the provided input or by using the configured strategies.
+ *
+ * @param {ShouldRedirectInput} input
+ * @param {URL} currentUrl
+ * @returns {Promise<Locale>}
+ */
+async function resolveLocale(input, currentUrl) {
+    const locale = toLocale(input.locale);
+    if (locale) {
+        return locale;
+    }
+    if (input.request) {
+        return extractLocaleFromRequestAsync(input.request, {
+            effectiveRequestUrl: currentUrl,
+        });
+    }
+    if ("url" in input && typeof input.url !== "undefined") {
+        return getLocaleForUrl(currentUrl.href);
+    }
+    return getLocale();
+}
+/**
+ * Resolves the current URL from the provided input or runtime context.
+ *
+ * @param {ShouldRedirectInput} input
+ * @returns {URL}
+ */
+function resolveUrl(input) {
+    if ("effectiveRequestUrl" in input && input.effectiveRequestUrl instanceof URL) {
+        return new URL(input.effectiveRequestUrl.href);
+    }
+    if ("effectiveRequestUrl" in input && typeof input.effectiveRequestUrl === "string") {
+        return new URL(input.effectiveRequestUrl, input.request ? input.request.url : getUrlOrigin());
+    }
+    if (input.request) {
+        return new URL(input.request.url);
+    }
+    if ("url" in input && input.url instanceof URL) {
+        return new URL(input.url.href);
+    }
+    if ("url" in input && typeof input.url === "string") {
+        return new URL(input.url, getUrlOrigin());
+    }
+    if (typeof window !== "undefined" && window?.location?.href) {
+        return new URL(window.location.href);
+    }
+    throw new Error("shouldRedirect() requires either a request, an absolute URL, or must run in a browser environment.");
+}
+/**
+ * Normalize url for comparison by stripping the trailing slash.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function normalizeUrl(url) {
+    const urlObj = new URL(url);
+    urlObj.pathname = urlObj.pathname.replace(/\/$/, "");
+    return urlObj.href;
+}
+
+/**
+ * High-level URL localization function optimized for client-side UI usage.
+ *
+ * This is a convenience wrapper around `localizeUrl()` that provides features
+ * needed in UI:
+ *
+ * - Accepts relative paths (e.g., "/about")
+ * - Returns relative paths when possible
+ * - Automatically detects current locale if not specified
+ * - Handles string input/output instead of URL objects
+ *
+ * @see https://paraglidejs.com/i18n-routing
+ *
+ * @example
+ * ```typescript
+ * // In a React/Vue/Svelte component
+ * const NavLink = ({ href }) => {
+ *   // Automatically uses current locale, keeps path relative
+ *   return <a href={localizeHref(href)}>...</a>;
+ * };
+ *
+ * // Examples:
+ * localizeHref("/about")
+ * // => "/de/about" (if current locale is "de")
+ * localizeHref("/store", { locale: "fr" })
+ * // => "/fr/store" (explicit locale)
+ *
+ * // Cross-origin links remain absolute
+ * localizeHref("https://other-site.com/about")
+ * // => "https://other-site.com/de/about"
+ * ```
+ *
+ * For server-side URL localization (e.g., in middleware), use `localizeUrl()`
+ * which provides more precise control over URL handling.
+ *
+ * @param {string} href - The href to localize (can be relative or absolute)
+ * @param {object} [options] - Options for localization
+ * @param {Locale} [options.locale] - Target locale. If not provided, uses `getLocale()`
+ * @returns {string} The localized href, relative if input was relative
+ */
+export function localizeHref(href, options) {
+    const currentLocale = getLocale();
+    const locale = options?.locale ?? currentLocale;
+    const url = new URL(href, getUrlOrigin());
+    const localized = localizeUrl(url, { locale });
+    // if the origin is identical and the href is relative,
+    // return the relative path
+    if (href.startsWith("/") && url.origin === localized.origin) {
+        // check for cross origin localization in which case an absolute URL must be returned.
+        if (locale !== currentLocale) {
+            const localizedCurrentLocale = localizeUrl(url, {
+                locale: currentLocale,
+            });
+            if (localizedCurrentLocale.origin !== localized.origin) {
+                return localized.href;
+            }
+        }
+        return localized.pathname + localized.search + localized.hash;
+    }
+    return localized.href;
+}
+/**
+ * High-level URL de-localization function optimized for client-side UI usage.
+ *
+ * This is a convenience wrapper around `deLocalizeUrl()` that provides features
+ * needed in the UI:
+ *
+ * - Accepts relative paths (e.g., "/de/about")
+ * - Returns relative paths when possible
+ * - Handles string input/output instead of URL objects
+ *
+ * @see https://paraglidejs.com/i18n-routing
+ *
+ * @example
+ * ```typescript
+ * // In a React/Vue/Svelte component
+ * const LocaleSwitcher = ({ href }) => {
+ *   // Remove locale prefix before switching
+ *   const baseHref = deLocalizeHref(href);
+ *   return locales.map(locale =>
+ *     <a href={localizeHref(baseHref, { locale })}>
+ *       Switch to {locale}
+ *     </a>
+ *   );
+ * };
+ *
+ * // Examples:
+ * deLocalizeHref("/de/about")  // => "/about"
+ * deLocalizeHref("/fr/store")  // => "/store"
+ *
+ * // Cross-origin links remain absolute
+ * deLocalizeHref("https://example.com/de/about")
+ * // => "https://example.com/about"
+ * ```
+ *
+ * For server-side URL de-localization (e.g., in middleware), use `deLocalizeUrl()`
+ * which provides more precise control over URL handling.
+ *
+ * @param {string} href - The href to de-localize (can be relative or absolute)
+ * @returns {string} The de-localized href, relative if input was relative
+ */
+export function deLocalizeHref(href) {
+    const url = new URL(href, getUrlOrigin());
+    const deLocalized = deLocalizeUrl(url);
+    // If the origin is identical and the href is relative,
+    // return the relative path instead of the full URL.
+    if (href.startsWith("/") && url.origin === deLocalized.origin) {
+        return deLocalized.pathname + deLocalized.search + deLocalized.hash;
+    }
+    return deLocalized.href;
+}
+
+/**
+ * @param {string} safeModuleId
+ * @param {Locale} locale
+ */
+export function trackMessageCall(safeModuleId, locale) {
+    if (isServer === false)
+        return;
+    const store = serverAsyncLocalStorage?.getStore();
+    if (store) {
+        store.messageCalls?.add(`${safeModuleId}:${locale}`);
+    }
+}
+
+/**
+ * Generates localized URL variants for all provided URLs based on your configured locales and URL patterns.
+ *
+ * This function is essential for Static Site Generation (SSG) where you need to tell your framework
+ * which pages to pre-render at build time. It's also useful for generating sitemaps and
+ * `<link rel="alternate" hreflang>` tags for SEO.
+ *
+ * The function respects your `urlPatterns` configuration - if you have translated pathnames
+ * (e.g., `/about` → `/ueber-uns` for German), it will generate the correct localized paths.
+ *
+ * @see https://paraglidejs.com/static-site-generation
+ *
+ * @example
+ * // Basic usage - generate all locale variants for a list of paths
+ * const localizedUrls = generateStaticLocalizedUrls([
+ *   "/",
+ *   "/about",
+ *   "/blog/post-1",
+ * ]);
+ * // Returns URL objects for each locale:
+ * // ["/en/", "/de/", "/en/about", "/de/about", "/en/blog/post-1", "/de/blog/post-1"]
+ *
+ * @example
+ * // Use with framework SSG APIs
+ * // SvelteKit
+ * export function entries() {
+ *   const paths = ["/", "/about", "/contact"];
+ *   return generateStaticLocalizedUrls(paths).map(url => ({
+ *     locale: extractLocaleFromUrl(url)
+ *   }));
+ * }
+ *
+ * @example
+ * // Sitemap generation
+ * const allPages = ["/", "/about", "/blog"];
+ * const sitemapUrls = generateStaticLocalizedUrls(allPages);
+ *
+ * @param {(string | URL)[]} urls - List of canonical URLs or paths to generate localized versions for.
+ *   Can be absolute URLs (`https://example.com/about`) or paths (`/about`).
+ *   Paths are resolved against `http://localhost` internally.
+ * @returns {URL[]} Array of URL objects representing all localized variants.
+ *   The order follows each input URL with all its locale variants before moving to the next URL.
+ */
+export function generateStaticLocalizedUrls(urls) {
+    /** @type {Set<URL>} */
+    const localizedUrls = new Set();
+    // For default URL pattern, we can optimize the generation
+    if (TREE_SHAKE_DEFAULT_URL_PATTERN_USED) {
+        for (const urlInput of urls) {
+            const url = urlInput instanceof URL
+                ? urlInput
+                : new URL(urlInput, "http://localhost");
+            // Base locale doesn't get a prefix
+            localizedUrls.add(url);
+            // Other locales get their code as prefix
+            for (const locale of locales) {
+                if (locale !== baseLocale) {
+                    const localizedPath = `/${locale}${url.pathname}${url.search}${url.hash}`;
+                    const localizedUrl = new URL(localizedPath, url.origin);
+                    localizedUrls.add(localizedUrl);
+                }
+            }
+        }
+        return Array.from(localizedUrls);
+    }
+    // For custom URL patterns, we need to use localizeUrl for each URL and locale
+    for (const urlInput of urls) {
+        const url = urlInput instanceof URL
+            ? urlInput
+            : new URL(urlInput, "http://localhost");
+        // Try each URL pattern to find one that matches
+        let patternFound = false;
+        for (const pattern of urlPatterns) {
+            try {
+                // Try to match the unlocalized pattern
+                const unlocalizedMatch = new URLPattern(pattern.pattern, url.href).exec(url.href);
+                if (!unlocalizedMatch)
+                    continue;
+                patternFound = true;
+                // Track unique localized URLs to avoid duplicates when patterns are the same
+                const seenUrls = new Set();
+                // Generate localized URL for each locale
+                for (const [locale] of pattern.localized) {
+                    try {
+                        const localizedUrl = localizeUrl(url, { locale });
+                        const urlString = localizedUrl.href;
+                        // Only add if we haven't seen this exact URL before
+                        if (!seenUrls.has(urlString)) {
+                            seenUrls.add(urlString);
+                            localizedUrls.add(localizedUrl);
+                        }
+                    }
+                    catch {
+                        // Skip if localization fails for this locale
+                        continue;
+                    }
+                }
+                break;
+            }
+            catch {
+                // Skip if pattern matching fails
+                continue;
+            }
+        }
+        // If no pattern matched, use the URL as is
+        if (!patternFound) {
+            localizedUrls.add(url);
+        }
+    }
+    return Array.from(localizedUrls);
+}
+
+/**
+ * @typedef {"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage"} BuiltInStrategy
+ */
+/**
+ * @typedef {`custom_${string}`} CustomStrategy
+ */
+/**
+ * @typedef {BuiltInStrategy | CustomStrategy} Strategy
+ */
+/**
+ * @typedef {Array<Strategy>} Strategies
+ */
+/**
+ * @typedef {{ getLocale: (request?: Request) => Promise<string | undefined> | (string | undefined) }} CustomServerStrategyHandler
+ */
+/**
+ * @typedef {{ getLocale: () => Promise<string|undefined> | (string | undefined), setLocale: (locale: string) => Promise<void> | void }} CustomClientStrategyHandler
+ */
+/** @type {Map<string, CustomServerStrategyHandler>} */
+export const customServerStrategies = new Map();
+/** @type {Map<string, CustomClientStrategyHandler>} */
+export const customClientStrategies = new Map();
+/**
+ * Checks if the given strategy is a custom strategy.
+ *
+ * @param {unknown} strategy The name of the custom strategy to validate.
+ * Must be a string that starts with "custom-" followed by alphanumeric characters, hyphens, or underscores.
+ * @returns {boolean} Returns true if it is a custom strategy, false otherwise.
+ */
+export function isCustomStrategy(strategy) {
+    return (typeof strategy === "string" && /^custom-[A-Za-z0-9_-]+$/.test(strategy));
+}
+/**
+ * Defines a custom strategy that is executed on the server.
+ *
+ * @see https://paraglidejs.com/strategy#write-your-own-strategy
+ *
+ * @param {string} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
+ * @param {CustomServerStrategyHandler} handler The handler for the custom strategy, which should implement
+ * the method getLocale.
+ * @returns {void}
+ */
+export function defineCustomServerStrategy(strategy, handler) {
+    if (!isCustomStrategy(strategy)) {
+        throw new Error(`Invalid custom strategy: "${strategy}". Must be a custom strategy following the pattern custom-name.`);
+    }
+    customServerStrategies.set(strategy, handler);
+}
+/**
+ * Defines a custom strategy that is executed on the client.
+ *
+ * @see https://paraglidejs.com/strategy#write-your-own-strategy
+ *
+ * @param {string} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
+ * @param {CustomClientStrategyHandler} handler The handler for the custom strategy, which should implement the
+ * methods getLocale and setLocale.
+ * @returns {void}
+ */
+export function defineCustomClientStrategy(strategy, handler) {
+    if (!isCustomStrategy(strategy)) {
+        throw new Error(`Invalid custom strategy: "${strategy}". Must be a custom strategy following the pattern custom-name.`);
+    }
+    customClientStrategies.set(strategy, handler);
+}
+
+// ------ TYPES ------
+export {};
+/**
+ * A locale that is available in the project.
+ *
+ * @example
+ *   setLocale(request.locale as Locale)
+ *
+ * @typedef {typeof locales[number]} Locale
+ */
+/**
+ * A branded type representing a localized string.
+ *
+ * Message functions return this type instead of \`string\`, enabling TypeScript
+ * to distinguish translated strings from regular strings at compile time.
+ * This allows you to enforce that only properly localized content is used
+ * in your UI components.
+ *
+ * Since \`LocalizedString\` is a branded subtype of \`string\`, it remains fully
+ * backward compatible—you can pass it anywhere a \`string\` is expected.
+ *
+ * @example
+ *   // Enforce localized strings in your components
+ *   function PageTitle(props: { title: LocalizedString }) {
+ *     return <h1>{props.title}</h1>
+ *   }
+ *
+ *   // ✅ Correct: using a message function
+ *   <PageTitle title={m.welcome_title()} />
+ *
+ *   // ❌ Type error: raw strings are not LocalizedString
+ *   <PageTitle title="Welcome" />
+ *
+ * @example
+ *   // LocalizedString is assignable to string (backward compatible)
+ *   const localized: LocalizedString = m.greeting()
+ *   const str: string = localized  // ✅ works fine
+ *
+ *   // But string is not assignable to LocalizedString
+ *   const raw: LocalizedString = "Hello"  // ❌ Type error
+ *
+ * @example
+ *   // Catches accidental string concatenation
+ *   function showMessage(msg: LocalizedString) { ... }
+ *
+ *   showMessage(m.hello())                    // ✅
+ *   showMessage("Hello " + userName)          // ❌ Type error
+ *   showMessage(m.hello_user({ name: userName }))  // ✅ use params instead
+ *
+ * @typedef {string & { readonly __brand: 'LocalizedString' }} LocalizedString
+ */
+/**
+ * A single markup option passed to a tag instance.
+ *
+ * @typedef {{
+ *   name: string;
+ *   value: unknown;
+ * }} MessageMarkupOption
+ */
+/**
+ * A single static markup attribute attached to a tag instance.
+ *
+ * @typedef {{
+ *   name: string;
+ *   value: string | true;
+ * }} MessageMarkupAttribute
+ */
+/**
+ * Record of markup options for a tag instance.
+ *
+ * @typedef {Record<string, unknown>} MessageMarkupOptions
+ */
+/**
+ * Record of markup attributes for a tag instance.
+ *
+ * @typedef {Record<string, string | true>} MessageMarkupAttributes
+ */
+/**
+ * Type-level schema for a single markup tag.
+ *
+ * @typedef {{
+ *   options: MessageMarkupOptions;
+ *   attributes: MessageMarkupAttributes;
+ *   children: boolean;
+ * }} MessageMarkupTag
+ */
+/**
+ * Type-level schema for all markup tags in a message.
+ *
+ * @typedef {Record<string, MessageMarkupTag>} MessageMarkupSchema
+ */
+/**
+ * Type-only metadata attached to compiled message functions.
+ *
+ * @template Inputs
+ * @template Options
+ * @template {MessageMarkupSchema} [Markup = MessageMarkupSchema]
+ * @typedef {{
+ *   readonly __paraglide?: {
+ *     inputs: Inputs;
+ *     options: Options;
+ *     markup: Markup;
+ *   };
+ * }} MessageMetadata
+ */
+/**
+ * A compiled, framework-neutral message part.
+ *
+ * @typedef {{
+ *   type: "text";
+ *   value: string;
+ * } | {
+ *   type: "markup-start";
+ *   name: string;
+ *   options: MessageMarkupOptions;
+ *   attributes: MessageMarkupAttributes;
+ * } | {
+ *   type: "markup-end";
+ *   name: string;
+ *   options: MessageMarkupOptions;
+ *   attributes: MessageMarkupAttributes;
+ * } | {
+ *   type: "markup-standalone";
+ *   name: string;
+ *   options: MessageMarkupOptions;
+ *   attributes: MessageMarkupAttributes;
+ * }} MessagePart
+ */
+/**
+ * A message function is a message for a specific locale.
+ *
+ * @example
+ *   m.hello({ name: 'world' })
+ *
+ * @typedef {(inputs?: Record<string, never>) => LocalizedString} MessageFunction
+ */
+/**
+ * A message bundle function that selects the message to be returned.
+ *
+ * Uses `getLocale()` under the hood to determine the locale with an option.
+ *
+ * @template {string} T
+ *
+ * @example
+ *   *   m.hello({ name: 'world' }, { locale: "en" })
+ *
+ * @typedef {(params: Record<string, never>, options: { locale: T }) => LocalizedString} MessageBundleFunction
+ */