Files
shumai/packages/webui/paraglide/runtime.d.ts
T

759 lines
26 KiB
TypeScript
Generated

/**
* 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: string | URL): typeof strategy;
/**
* Returns whether the given URL is excluded from middleware i18n processing.
*
* @param {string | URL} url
* @returns {boolean}
*/
export function isExcludedByRouteStrategy(url: string | URL): boolean;
/**
* 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: ParaglideAsyncLocalStorage | undefined): void;
/**
* Resolve locale for a given URL using route-aware strategies.
*
* @param {string | URL} url
* @returns {Locale}
*/
export function getLocaleForUrl(url: string | URL): Locale;
/**
* 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?: string): "ltr" | "rtl";
/**
* Coerces a locale-like string to the canonical locale value used by the runtime.
*
* @param {unknown} value
* @returns {Locale | undefined}
*/
export function toLocale(value: unknown): Locale | 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: unknown): locale is 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: unknown): Locale;
/**
* 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(): Locale | undefined;
/**
* 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: Request): Locale | 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(): Locale | undefined;
/**
* 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: URL | string): Locale | undefined;
/**
* 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: string | URL, options?: {
locale?: Locale;
}): URL;
/**
* 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: string | URL): URL;
/**
* 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: any): Record<string, string | null | undefined>;
/**
* @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 function shouldRedirect(input?: ShouldRedirectInput): Promise<ShouldRedirectResult>;
/**
* 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: string, options?: {
locale?: Locale;
}): string;
/**
* 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: string): string;
/**
* @param {string} safeModuleId
* @param {Locale} locale
*/
export function trackMessageCall(safeModuleId: string, locale: Locale): void;
/**
* 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: (string | URL)[]): URL[];
/**
* 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: unknown): boolean;
/**
* 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: string, handler: CustomServerStrategyHandler): void;
/**
* 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: string, handler: CustomClientStrategyHandler): void;
/**
* 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: readonly ["en", "zh"];
/** @type {string} */
export const cookieName: string;
/** @type {number} */
export const cookieMaxAge: number;
/** @type {string} */
export const cookieDomain: string;
/** @type {string} */
export const localStorageKey: string;
/**
* @type {Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>}
*/
export const strategy: Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>;
/**
* 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: Array<{
match: string;
strategy?: Array<"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage" | `custom-${string}`>;
exclude?: boolean;
}>;
/**
* The used URL patterns.
*
* @type {Array<{ pattern: string, localized: Array<[Locale, string]> }>}
*/
export const urlPatterns: Array<{
pattern: string;
localized: Array<[Locale, string]>;
}>;
/**
* @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: ParaglideAsyncLocalStorage | undefined;
export const disableAsyncLocalStorage: false;
export const experimentalMiddlewareLocaleSplitting: false;
export const isServer: boolean;
/** @type {Locale | undefined} */
export const experimentalStaticLocale: Locale | undefined;
export function getLocale(): Locale;
export function overwriteGetLocale(fn: () => Locale): void;
/**
* @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: SetLocaleFn;
export function overwriteSetLocale(fn: SetLocaleFn): void;
/**
* 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: () => string;
export function overwriteGetUrlOrigin(fn: () => string): void;
export function extractLocaleFromRequest(request: Request, options?: ExtractLocaleFromRequestOptions): Locale;
export function extractLocaleFromRequestWithStrategies(request: Request, strategies: typeof strategy, url?: string | URL): Locale;
export function extractLocaleFromRequestAsync(request: Request, options?: {
effectiveRequestUrl?: string | URL;
}): Promise<Locale>;
/**
* @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: Map<string, CustomServerStrategyHandler>;
/** @type {Map<string, CustomClientStrategyHandler>} */
export const customClientStrategies: Map<string, CustomClientStrategyHandler>;
export type ShouldRedirectServerInput = {
request: Request;
/**
* - Effective request URL to use for route matching, locale detection with the URL strategy, and redirect targets.
*/
effectiveRequestUrl?: string | URL;
locale?: Locale;
};
export type ShouldRedirectClientInput = {
request?: undefined;
url?: string | URL;
locale?: Locale;
};
export type ShouldRedirectInput = ShouldRedirectServerInput | ShouldRedirectClientInput;
export type ShouldRedirectResult = {
/**
* - Indicates whether the consumer should perform a redirect.
*/
shouldRedirect: boolean;
/**
* - Locale resolved using the configured strategies.
*/
locale: Locale;
/**
* - Destination URL when a redirect is required.
*/
redirectUrl: URL | undefined;
};
export type ParaglideAsyncLocalStorage = {
getStore(): {
locale?: Locale;
origin?: string;
messageCalls?: Set<string>;
} | undefined;
run: (store: {
locale?: Locale;
origin?: string;
messageCalls?: Set<string>;
}, cb: any) => any;
};
export type SetLocaleFn = (newLocale: Locale, options?: {
reload?: boolean;
}) => void | Promise<void>;
export type ExtractLocaleFromRequestOptions = {
/**
* - Effective request URL to use for route matching and locale detection with the URL strategy.
*/
effectiveRequestUrl?: string | URL;
};
export type BuiltInStrategy = "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage";
export type CustomStrategy = `custom_${string}`;
export type Strategy = BuiltInStrategy | CustomStrategy;
export type Strategies = Array<Strategy>;
export type CustomServerStrategyHandler = {
getLocale: (request?: Request) => Promise<string | undefined> | (string | undefined);
};
export type CustomClientStrategyHandler = {
getLocale: () => Promise<string | undefined> | (string | undefined);
setLocale: (locale: string) => Promise<void> | void;
};
/**
* A locale that is available in the project.
*/
export type Locale = (typeof locales)[number];
/**
* 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.
*/
export type LocalizedString = string & {
readonly __brand: "LocalizedString";
};
/**
* A single markup option passed to a tag instance.
*/
export type MessageMarkupOption = {
name: string;
value: unknown;
};
/**
* A single static markup attribute attached to a tag instance.
*/
export type MessageMarkupAttribute = {
name: string;
value: string | true;
};
/**
* Record of markup options for a tag instance.
*/
export type MessageMarkupOptions = Record<string, unknown>;
/**
* Record of markup attributes for a tag instance.
*/
export type MessageMarkupAttributes = Record<string, string | true>;
/**
* Type-level schema for a single markup tag.
*/
export type MessageMarkupTag = {
options: MessageMarkupOptions;
attributes: MessageMarkupAttributes;
children: boolean;
};
/**
* Type-level schema for all markup tags in a message.
*/
export type MessageMarkupSchema = Record<string, MessageMarkupTag>;
/**
* Type-only metadata attached to compiled message functions.
*/
export type MessageMetadata<Inputs, Options, Markup extends MessageMarkupSchema = Record<string, MessageMarkupTag>> = {
readonly __paraglide?: {
inputs: Inputs;
options: Options;
markup: Markup;
};
};
/**
* A compiled, framework-neutral message part.
*/
export type MessagePart = {
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;
};
/**
* A message function is a message for a specific locale.
*/
export type MessageFunction = (inputs?: Record<string, never>) => LocalizedString;
/**
* A message bundle function that selects the message to be returned.
*
* Uses `getLocale()` under the hood to determine the locale with an option.
*/
export type MessageBundleFunction<T extends string> = (params: Record<string, never>, options: {
locale: T;
}) => LocalizedString;