@turnipxenon/pineapple 5.3.15 → 5.3.17

package/dist/external/paraglide/runtime.js

@@ -20,7 +20,7 @@ export const baseLocale = "en";
  *     throw new Error('Locale is not available');
  *   }
  */
-export const locales = /** @type {const} */ (["en", "fr", "tl"]);
+export const locales = /** @type {const} */ (["en","fr","tl"]);
 /** @type {string} */
 export const cookieName = "PARAGLIDE_LOCALE";
 /** @type {number} */
@@ -33,14 +33,26 @@ export const localStorageKey = "PARAGLIDE_LOCALE";
  * @type {Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>}
  */
 export const strategy = [
-  "url",
   "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]> }> }
+ * @type {Array<{ pattern: string, localized: Array<[Locale, string]> }>}
  */
 export const urlPatterns = [
   {
@@ -81,9 +93,22 @@ export const urlPatterns = [
  * @type {ParaglideAsyncLocalStorage | undefined}
  */
 export let serverAsyncLocalStorage = undefined;
+/**
+ * Returns the current server-side async local storage instance.
+ *
+ * Accessing the mutable value through a function keeps it observable when
+ * module interceptors wrap exported bindings and snapshot their initial value.
+ *
+ * @returns {ParaglideAsyncLocalStorage | undefined}
+ */
+export function getServerAsyncLocalStorage() {
+    return serverAsyncLocalStorage;
+}
 export const disableAsyncLocalStorage = false;
 export const experimentalMiddlewareLocaleSplitting = false;
-export const isServer = import.meta.env?.SSR ?? typeof window === 'undefined';
+export const isServer = typeof window === 'undefined';
+/** @type {Locale | undefined} */
+export const experimentalStaticLocale = undefined;
 /**
  * Sets the server side async local storage.
  *
@@ -98,28 +123,37 @@ export function overwriteServerAsyncLocalStorage(value) {
     serverAsyncLocalStorage = value;
 }
 const TREE_SHAKE_COOKIE_STRATEGY_USED = true;
-const TREE_SHAKE_URL_STRATEGY_USED = true;
-const TREE_SHAKE_GLOBAL_VARIABLE_STRATEGY_USED = false;
+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;
 
-globalThis.__paraglide = {}
+/** @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()\`.
+ * by `overwriteGetLocale()` and `defineSetLocale()`.
  *
- * @type {Locale|undefined}
+ * @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 🇩🇪');
@@ -127,11 +161,12 @@ let localeInitiallySet = false;
  *     console.log('Netherlands 🇳🇱');
  *   }
  *
- * @type {() => Locale}
+ * @returns {Locale} The current locale.
  */
 export let getLocale = () => {
-    /** @type {string | undefined} */
-    let locale;
+    if (experimentalStaticLocale !== undefined) {
+        return experimentalStaticLocale;
+    }
     // if running in a server-side rendering context
     // retrieve the locale from the async local storage
     if (serverAsyncLocalStorage) {
@@ -140,7 +175,48 @@ export let getLocale = () => {
             return locale;
         }
     }
-    for (const strat of strategy) {
+    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();
         }
@@ -150,8 +226,8 @@ export let getLocale = () => {
         else if (TREE_SHAKE_URL_STRATEGY_USED &&
             strat === "url" &&
             !isServer &&
-            typeof window !== "undefined") {
-            locale = extractLocaleFromUrl(window.location.href);
+            typeof urlForUrlStrategy === "string") {
+            locale = extractLocaleFromUrl(urlForUrlStrategy);
         }
         else if (TREE_SHAKE_GLOBAL_VARIABLE_STRATEGY_USED &&
             strat === "globalVariable" &&
@@ -177,47 +253,86 @@ export let getLocale = () => {
                     // Can't await in sync function, skip async strategies
                     continue;
                 }
-                locale = result;
+                if (result !== undefined) {
+                    return assertIsLocale(result);
+                }
             }
         }
-        // check if match, else continue loop
-        if (locale !== undefined) {
-            const asserted = assertIsLocale(locale);
-            if (!localeInitiallySet) {
-                _locale = asserted;
-                // https://github.com/opral/inlang-paraglide-js/issues/455
-                localeInitiallySet = true;
-                setLocale(asserted, { reload: false });
-            }
-            return asserted;
+        const matchedLocale = toLocale(locale);
+        if (matchedLocale) {
+            return matchedLocale;
         }
     }
-    throw new Error("No locale found. Read the docs https://inlang.com/m/gerre34r/library-inlang-paraglideJs/errors#no-locale-found");
-};
+    return undefined;
+}
 /**
- * Overwrite the \`getLocale()\` function.
+ * Overwrite the `getLocale()` function.
  *
- * Use this function to overwrite how the locale is resolved. For example,
- * you can resolve the locale from the browser's preferred language,
- * a cookie, env variable, or a user's preference.
+ * 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(() => {
- *     // resolve the locale from a cookie. fallback to the base locale.
  *     return Cookies.get('locale') ?? baseLocale
- *   }
+ *   });
  *
- * @type {(fn: () => Locale) => void}
+ * @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
- * @return {undefined}
  */
 const navigateOrReload = (newLocation) => {
     if (newLocation) {
@@ -235,13 +350,18 @@ const navigateOrReload = (newLocation) => {
 /**
  * Set the locale.
  *
- * Set locale reloads the site by default on the client. Reloading
- * can be disabled by passing \`reload: false\` as an option. If
- * reloading is disabled, you need to ensure that the UI is updated
- * to reflect the new locale.
+ * Updates the locale using your configured strategies (cookie, localStorage, URL, etc.).
+ * By default, this navigates the client to the localized URL or reloads the current
+ * document to reflect the new locale. `reload: false` is a narrow browser-only escape
+ * hatch for a fully client-rendered, non-URL-routed surface that owns its reactive
+ * updates and document state. It does not re-render the UI or update the document.
+ * Do not use it for normal locale pickers, URL-routed pages, or switching an SSR,
+ * SSG, or hydrated document. It is incompatible with per-locale builds.
  *
- * If any custom strategy's \`setLocale\` function is async, then this
- * function will become async as well.
+ * 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');
@@ -256,6 +376,12 @@ export let setLocale = (newLocale, options) => {
         reload: true,
         ...options,
     };
+    if (experimentalStaticLocale !== undefined &&
+        newLocale !== experimentalStaticLocale &&
+        optionsWithDefaults.reload === false) {
+        console.warn(`Paraglide: setLocale(${JSON.stringify(newLocale)}, { reload: false }) cannot switch away from the statically built locale ${JSON.stringify(experimentalStaticLocale)}. A document navigation is required; reload has been forced to true.`);
+        optionsWithDefaults.reload = true;
+    }
     // locale is already set
     // https://github.com/opral/inlang-paraglide-js/issues/430
     /** @type {Locale | undefined} */
@@ -266,11 +392,15 @@ export let setLocale = (newLocale, options) => {
     catch {
         // do nothing, no locale has been set yet.
     }
-    /** @type {Array<Promise<any>>} */
+    /** @type {Array<Promise<void>>} */
     const customSetLocalePromises = [];
     /** @type {string | undefined} */
     let newLocation = undefined;
-    for (const strat of strategy) {
+    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
@@ -288,6 +418,7 @@ export let setLocale = (newLocale, options) => {
             document.cookie = cookieDomain
                 ? `${cookieString}; domain=${cookieDomain}`
                 : cookieString;
+            clearLocaleCookieCache();
         }
         else if (strat === "baseLocale") {
             // nothing to be set here. baseLocale is only a fallback
@@ -347,7 +478,7 @@ export let setLocale = (newLocale, options) => {
     return;
 };
 /**
- * Overwrite the \`setLocale()\` function.
+ * 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.
@@ -361,13 +492,13 @@ export let setLocale = (newLocale, options) => {
  * @param {SetLocaleFn} fn
  */
 export const overwriteSetLocale = (fn) => {
-    setLocale = /** @type {SetLocaleFn} */ (fn);
+    setLocale = fn;
 };
 
 /**
  * The origin of the current URL.
  *
- * Defaults to "http://y.com" in non-browser environments. If this
+ * Defaults to "http://example.com" in non-browser environments. If this
  * behavior is not desired, the implementation can be overwritten
  * by `overwriteGetUrlOrigin()`.
  *
@@ -388,14 +519,32 @@ export let getUrlOrigin = () => {
  * Use this function in server environments to
  * define how the URL origin is resolved.
  *
- * @type {(fn: () => string) => void}
+ * @param {() => string} fn - The new implementation for `getUrlOrigin()`.
  */
 export let overwriteGetUrlOrigin = (fn) => {
     getUrlOrigin = fn;
 };
 
 /**
- * Check if something is an available locale.
+ * 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)) {
@@ -404,27 +553,32 @@ export let overwriteGetUrlOrigin = (fn) => {
  *     setLocale('en');
  *   }
  *
- * @param {any} locale
+ * Use `toLocale()` when you want case-insensitive matching and canonicalization.
+ *
+ * @param {unknown} locale
  * @returns {locale is Locale}
  */
 export function isLocale(locale) {
-    return !locale ? false : locales.includes(locale);
+    return !!locale && locales.some((item) => item === locale);
 }
-
 /**
- * Asserts that the input is a locale.
+ * Asserts that the input can be normalized to a locale.
  *
- * @param {any} input - The input to check.
- * @returns {Locale} The input if it is 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) {
-    if (isLocale(input) === false) {
-        throw new Error(`Invalid locale: ${input}. Expected one of: ${locales.join(", ")}`);
-    }
-    return 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.
  *
@@ -441,21 +595,38 @@ export function assertIsLocale(input) {
  * @example
  *   const locale = extractLocaleFromRequest(request);
  *
- * @type {(request: Request) => Locale}
+ * @param {Request} request
+ * @param {ExtractLocaleFromRequestOptions} [options]
+ * @returns {Locale}
  */
-export const extractLocaleFromRequest = (request) => {
+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 strategy) {
+    for (const strat of strategies) {
         if (TREE_SHAKE_COOKIE_STRATEGY_USED && strat === "cookie") {
+            const cookiePrefix = cookieName + "=";
             locale = request.headers
                 .get("cookie")
-                ?.split("; ")
-                .find((c) => c.startsWith(cookieName + "="))
-                ?.split("=")[1];
+                ?.split(";")
+                .map((c) => c.trim())
+                .find((c) => c.startsWith(cookiePrefix))
+                ?.slice(cookiePrefix.length);
         }
         else if (TREE_SHAKE_URL_STRATEGY_USED && strat === "url") {
-            locale = extractLocaleFromUrl(request.url);
+            locale = extractLocaleFromUrl(effectiveRequestUrl);
         }
         else if (TREE_SHAKE_PREFERRED_LANGUAGE_STRATEGY_USED &&
             strat === "preferredLanguage") {
@@ -475,17 +646,24 @@ export const extractLocaleFromRequest = (request) => {
             // Use extractLocaleFromRequestAsync for custom server strategies
             continue;
         }
-        if (locale !== undefined) {
-            if (!isLocale(locale)) {
-                locale = undefined;
-            }
-            else {
-                return assertIsLocale(locale);
-            }
+        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://inlang.com/m/gerre34r/library-inlang-paraglideJs/errors#no-locale-found");
+    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.
@@ -514,11 +692,15 @@ export const extractLocaleFromRequest = (request) => {
  *
  *   const locale = await extractLocaleFromRequestAsync(request);
  *
- * @type {(request: Request) => Promise<Locale>}
+ * @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) => {
+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)) {
@@ -528,34 +710,66 @@ export const extractLocaleFromRequestAsync = async (request) => {
                 locale = await handler.getLocale(request);
             }
             // If we got a valid locale from this custom strategy, use it
-            if (locale !== undefined && isLocale(locale)) {
-                return assertIsLocale(locale);
+            const matchedLocale = toLocale(locale);
+            if (matchedLocale) {
+                return matchedLocale;
             }
         }
     }
     // If no custom strategy provided a valid locale, fall back to sync version
-    locale = extractLocaleFromRequest(request);
-    return assertIsLocale(locale);
+    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 {string | undefined}
+ * @returns {Locale | undefined}
  */
 export function extractLocaleFromCookie() {
-    if (typeof document === "undefined" || !document.cookie) {
+    if (typeof document === "undefined") {
         return;
     }
-    const match = document.cookie.match(new RegExp(`(^| )${cookieName}=([^;]+)`));
-    const locale = match?.[2];
-    if (isLocale(locale)) {
-        return locale;
+    if (cachedLocaleFromCookie !== noCachedLocale) {
+        return cachedLocaleFromCookie;
     }
-    return undefined;
+    const match = document.cookie.match(localeCookiePattern);
+    const locale = match?.[1];
+    cachedLocaleFromCookie = toLocale(locale);
+    scheduleLocaleCookieCacheClear();
+    return cachedLocaleFromCookie;
 }
 
 /**
@@ -567,9 +781,8 @@ export function extractLocaleFromCookie() {
  * @example
  *   const locale = extractLocaleFromHeader(request);
  *
- * @type {(request: Request) => Locale}
  * @param {Request} request - The request object to extract the locale from.
- * @returns {string|undefined} The negotiated preferred language.
+ * @returns {Locale | undefined} The negotiated preferred language.
  */
 export function extractLocaleFromHeader(request) {
     const acceptLanguageHeader = request.headers.get("accept-language");
@@ -580,20 +793,22 @@ export function extractLocaleFromHeader(request) {
             .map((lang) => {
             const [tag, q = "1"] = lang.trim().split(";q=");
             // Get both the full tag and base language code
-            const baseTag = tag?.split("-")[0]?.toLowerCase();
+            const baseTag = tag?.split("-")[0];
             return {
-                fullTag: tag?.toLowerCase(),
+                fullTag: tag,
                 baseTag,
                 q: Number(q),
             };
         })
             .sort((a, b) => b.q - a.q);
         for (const lang of languages) {
-            if (isLocale(lang.fullTag)) {
-                return lang.fullTag;
+            const fullLocale = toLocale(lang.fullTag);
+            if (fullLocale) {
+                return fullLocale;
             }
-            else if (isLocale(lang.baseTag)) {
-                return lang.baseTag;
+            const baseLocale = toLocale(lang.baseTag);
+            if (baseLocale) {
+                return baseLocale;
             }
         }
         return undefined;
@@ -610,23 +825,24 @@ export function extractLocaleFromHeader(request) {
  * @example
  *   const locale = extractLocaleFromNavigator();
  *
- * @type {() => Locale | undefined}
- * @returns {string | undefined}
+ * @returns {Locale | undefined}
  */
 export function extractLocaleFromNavigator() {
     if (!navigator?.languages?.length) {
         return undefined;
     }
     const languages = navigator.languages.map((lang) => ({
-        fullTag: lang.toLowerCase(),
-        baseTag: lang.split("-")[0]?.toLowerCase(),
+        fullTag: lang,
+        baseTag: lang.split("-")[0],
     }));
     for (const lang of languages) {
-        if (isLocale(lang.fullTag)) {
-            return lang.fullTag;
+        const fullLocale = toLocale(lang.fullTag);
+        if (fullLocale) {
+            return fullLocale;
         }
-        else if (isLocale(lang.baseTag)) {
-            return lang.baseTag;
+        const baseLocale = toLocale(lang.baseTag);
+        if (baseLocale) {
+            return baseLocale;
         }
     }
     return undefined;
@@ -645,6 +861,10 @@ 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.
  */
@@ -653,6 +873,7 @@ export function extractLocaleFromUrl(url) {
     if (cachedUrl === urlString) {
         return cachedLocale;
     }
+    /** @type {Locale | undefined} */
     let result;
     if (TREE_SHAKE_DEFAULT_URL_PATTERN_USED) {
         result = defaultUrlPatternExtractLocale(url);
@@ -663,11 +884,7 @@ export function extractLocaleFromUrl(url) {
         for (const element of urlPatterns) {
             for (const [locale, localizedPattern] of element.localized) {
                 const match = new URLPattern(localizedPattern, urlObj.href).exec(urlObj.href);
-                if (!match) {
-                    continue;
-                }
-                // Check if the locale is valid
-                if (assertIsLocale(locale)) {
+                if (match) {
                     result = locale;
                     break;
                 }
@@ -683,20 +900,13 @@ export function extractLocaleFromUrl(url) {
 /**
  * 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.
+ * @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 urlObj = new URL(url, "http://example.com");
     const pathSegments = urlObj.pathname.split("/").filter(Boolean);
-    if (pathSegments.length > 0) {
-        const potentialLocale = pathSegments[0];
-        if (isLocale(potentialLocale)) {
-            return potentialLocale;
-        }
-    }
-    // everything else has to be the base locale
-    return baseLocale;
+    return toLocale(pathSegments[0]) || baseLocale;
 }
 
 /**
@@ -709,6 +919,8 @@ function defaultUrlPatternExtractLocale(url) {
  * 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
@@ -737,15 +949,17 @@ function defaultUrlPatternExtractLocale(url) {
  * ```
  *
  * @param {string | URL} url - The URL to localize. If string, must be absolute.
- * @param {Object} [options] - Options for localization
- * @param {string} [options.locale] - Target locale. If not provided, uses getLocale()
+ * @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, options);
+        return localizeUrlDefaultPattern(url, targetLocale);
     }
-    const targetLocale = options?.locale ?? getLocale();
     const urlObj = typeof url === "string" ? new URL(url) : url;
     // Iterate over URL patterns
     for (const element of urlPatterns) {
@@ -778,13 +992,11 @@ export function localizeUrl(url, options) {
  * https://github.com/opral/inlang-paraglide-js/issues/381
  *
  * @param {string | URL} url
- * @param {Object} [options]
- * @param {string} [options.locale]
+ * @param {Locale} locale
  * @returns {URL}
  */
-function localizeUrlDefaultPattern(url, options) {
+function localizeUrlDefaultPattern(url, locale) {
     const urlObj = typeof url === "string" ? new URL(url, getUrlOrigin()) : new URL(url);
-    const locale = options?.locale ?? getLocale();
     const currentLocale = extractLocaleFromUrl(urlObj);
     // If current locale matches target locale, no change needed
     if (currentLocale === locale) {
@@ -792,7 +1004,7 @@ function localizeUrlDefaultPattern(url, options) {
     }
     const pathSegments = urlObj.pathname.split("/").filter(Boolean);
     // If current path starts with a locale, remove it
-    if (pathSegments.length > 0 && isLocale(pathSegments[0])) {
+    if (pathSegments.length > 0 && toLocale(pathSegments[0])) {
         pathSegments.shift();
     }
     // For base locale, don't add prefix
@@ -815,6 +1027,8 @@ function localizeUrlDefaultPattern(url, options) {
  * 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
@@ -878,7 +1092,7 @@ 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 && isLocale(pathSegments[0])) {
+    if (pathSegments.length > 0 && toLocale(pathSegments[0])) {
         urlObj.pathname = "/" + pathSegments.slice(1).join("/");
     }
     return urlObj;
@@ -991,7 +1205,8 @@ function fillPattern(pattern, values, origin) {
  * Aggregates named groups from various parts of the URLPattern match result.
  *
  *
- * @type {(match: any) => Record<string, string | null | undefined>}
+ * @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 {
@@ -1006,22 +1221,92 @@ export function aggregateGroups(match) {
     };
 }
 
+/** @type {string | undefined} */
+let cachedRouteStrategyUrl;
+/** @type {{ match: string; strategy?: typeof strategy; exclude?: boolean } | undefined} */
+let cachedRouteStrategy;
+/**
+ * Match route policy against both the public URL and its canonical URL.
+ *
+ * The function is deliberately separate from variables.js: configuration is
+ * inert data, while canonicalization and route selection form a routing layer.
+ *
+ * @param {string | URL} url
+ * @returns {{ match: string; strategy?: typeof strategy; exclude?: boolean } | undefined}
+ */
+export function findMatchingRouteStrategy(url) {
+    if (routeStrategies.length === 0) {
+        return undefined;
+    }
+    const urlString = typeof url === "string" ? url : url.href;
+    if (cachedRouteStrategyUrl === urlString) {
+        return cachedRouteStrategy;
+    }
+    const publicUrl = new URL(urlString, "http://example.com");
+    const canonicalUrl = deLocalizeUrl(publicUrl);
+    const candidateUrls = canonicalUrl.href === publicUrl.href
+        ? [publicUrl]
+        : [publicUrl, canonicalUrl];
+    let match;
+    for (const candidateUrl of candidateUrls) {
+        for (const routeStrategy of routeStrategies) {
+            const pattern = new URLPattern(routeStrategy.match, candidateUrl.href);
+            if (pattern.exec(candidateUrl.href)) {
+                match = routeStrategy;
+                break;
+            }
+        }
+        if (match)
+            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 {object} ShouldRedirectServerInput
  * @property {Request} request
- * @property {string | URL} [url]
- * @property {ReturnType<typeof assertIsLocale>} [locale]
+ * @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 {ReturnType<typeof assertIsLocale>} [locale]
+ * @property {Locale} [locale]
  *
  * @typedef {ShouldRedirectServerInput | ShouldRedirectClientInput} ShouldRedirectInput
  *
  * @typedef {object} ShouldRedirectResult
  * @property {boolean} shouldRedirect - Indicates whether the consumer should perform a redirect.
- * @property {ReturnType<typeof assertIsLocale>} locale - Locale resolved using the configured strategies.
+ * @property {Locale} locale - Locale resolved using the configured strategies.
  * @property {URL | undefined} redirectUrl - Destination URL when a redirect is required.
  */
 /**
@@ -1033,6 +1318,8 @@ export function aggregateGroups(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 }) {
@@ -1055,15 +1342,33 @@ export function aggregateGroups(match) {
  *   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 locale = /** @type {ReturnType<typeof assertIsLocale>} */ (await resolveLocale(input));
-    if (!strategy.includes("url")) {
+    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 currentUrl = resolveUrl(input);
     const localizedUrl = localizeUrl(currentUrl.href, { locale });
     const shouldRedirectToLocalizedUrl = normalizeUrl(localizedUrl.href) !== normalizeUrl(currentUrl.href);
     return {
@@ -1076,14 +1381,21 @@ export async function shouldRedirect(input = {}) {
  * Resolves the locale either from the provided input or by using the configured strategies.
  *
  * @param {ShouldRedirectInput} input
- * @returns {Promise<ReturnType<typeof assertIsLocale>>}
+ * @param {URL} currentUrl
+ * @returns {Promise<Locale>}
  */
-async function resolveLocale(input) {
-    if (input.locale) {
-        return assertIsLocale(input.locale);
+async function resolveLocale(input, currentUrl) {
+    const locale = toLocale(input.locale);
+    if (locale) {
+        return locale;
     }
     if (input.request) {
-        return extractLocaleFromRequestAsync(input.request);
+        return extractLocaleFromRequestAsync(input.request, {
+            effectiveRequestUrl: currentUrl,
+        });
+    }
+    if ("url" in input && typeof input.url !== "undefined") {
+        return getLocaleForUrl(currentUrl.href);
     }
     return getLocale();
 }
@@ -1094,13 +1406,21 @@ async function resolveLocale(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 (input.url instanceof URL) {
+    if ("url" in input && input.url instanceof URL) {
         return new URL(input.url.href);
     }
-    if (typeof input.url === "string") {
+    if ("url" in input && typeof input.url === "string") {
         return new URL(input.url, getUrlOrigin());
     }
     if (typeof window !== "undefined" && window?.location?.href) {
@@ -1131,6 +1451,8 @@ function normalizeUrl(url) {
  * - 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
@@ -1154,8 +1476,8 @@ function normalizeUrl(url) {
  * 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 {string} [options.locale] - Target locale. If not provided, uses `getLocale()`
+ * @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) {
@@ -1189,6 +1511,8 @@ export function localizeHref(href, options) {
  * - 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
@@ -1216,7 +1540,6 @@ export function localizeHref(href, options) {
  *
  * @param {string} href - The href to de-localize (can be relative or absolute)
  * @returns {string} The de-localized href, relative if input was relative
- * @see deLocalizeUrl - For low-level URL de-localization in server contexts
  */
 export function deLocalizeHref(href) {
     const url = new URL(href, getUrlOrigin());
@@ -1243,28 +1566,50 @@ export function trackMessageCall(safeModuleId, locale) {
 }
 
 /**
- * Generates a list of localized URLs for all provided URLs.
+ * 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.
  *
- * This is useful for SSG (Static Site Generation) and sitemap generation.
- * NextJS and other frameworks use this function for SSG.
+ * @see https://paraglidejs.com/static-site-generation
  *
  * @example
- * ```typescript
- * const urls = generateStaticLocalizedUrls([
- *   "https://example.com/about",
- *   "https://example.com/blog",
+ * // Basic usage - generate all locale variants for a list of paths
+ * const localizedUrls = generateStaticLocalizedUrls([
+ *   "/",
+ *   "/about",
+ *   "/blog/post-1",
  * ]);
- * urls[0].href // => "https://example.com/about"
- * urls[1].href // => "https://example.com/blog"
- * urls[2].href // => "https://example.com/de/about"
- * urls[3].href // => "https://example.com/de/blog"
- * ...
- * ```
+ * // 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)
+ *   }));
+ * }
  *
- * @param {(string | URL)[]} urls - List of URLs to generate localized versions for. Can be absolute URLs or paths.
- * @returns {URL[]} List of localized URLs as URL objects
+ * @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) {
@@ -1357,7 +1702,7 @@ export const customClientStrategies = new Map();
 /**
  * Checks if the given strategy is a custom strategy.
  *
- * @param {any} strategy The name of the custom strategy to validate.
+ * @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.
  */
@@ -1367,7 +1712,9 @@ export function isCustomStrategy(strategy) {
 /**
  * Defines a custom strategy that is executed on the server.
  *
- * @param {any} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
+ * @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}
@@ -1381,7 +1728,9 @@ export function defineCustomServerStrategy(strategy, handler) {
 /**
  * Defines a custom strategy that is executed on the client.
  *
- * @param {any} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
+ * @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}
@@ -1394,13 +1743,150 @@ export function defineCustomClientStrategy(strategy, handler) {
 }
 
 // ------ TYPES ------
-
+export {};
 /**
  * A locale that is available in the project.
  *
  * @example
  *   setLocale(request.locale as Locale)
  *
- * @typedef {(typeof locales)[number]} 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
  */
-