mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 19:17:38 +00:00
1826 lines
62 KiB
JavaScript
Generated
1826 lines
62 KiB
JavaScript
Generated
/* 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","zh"]);
|
|
/** @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": [
|
|
[
|
|
"zh",
|
|
":protocol://:domain(.*)::port?/zh/: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;
|
|
}
|
|
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") {
|
|
locale = request.headers
|
|
.get("cookie")
|
|
?.split("; ")
|
|
.find((c) => c.startsWith(cookieName + "="))
|
|
?.split("=")[1];
|
|
}
|
|
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);
|
|
}
|
|
|
|
/**
|
|
* 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" || !document.cookie) {
|
|
return;
|
|
}
|
|
const match = document.cookie.match(new RegExp(`(^| )${cookieName}=([^;]+)`));
|
|
const locale = match?.[2];
|
|
return toLocale(locale);
|
|
}
|
|
|
|
/**
|
|
* 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
|
|
*/
|