/** * 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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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?: "en" | "en-US" | "af" | "ar" | "en-GB" | "en-ZA" | "es" | "es-US" | "fr" | "fr-CA" | "fr-FR" | undefined; }): 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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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} An object containing all named groups from the match. */ export function aggregateGroups(match: any): Record; /** * @typedef {object} ShouldRedirectServerInput * @property {Request} request * @property {string | URL} [url] * @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://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing#client-side-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); * } * * @param {ShouldRedirectInput} [input] * @returns {Promise} */ export function shouldRedirect(input?: ShouldRedirectInput): Promise; /** * 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://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing * * @example * ```typescript * // In a React/Vue/Svelte component * const NavLink = ({ href }) => { * // Automatically uses current locale, keeps path relative * return ...; * }; * * // 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?: "en" | "en-US" | "af" | "ar" | "en-GB" | "en-ZA" | "es" | "es-US" | "fr" | "fr-CA" | "fr-FR" | undefined; }): 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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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 => * * Switch to {locale} * * ); * }; * * // 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 * `` 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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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 ["af", "ar", "en", "en-GB", "en-US", "en-ZA", "es", "es-US", "fr", "fr-CA", "fr-FR"]; /** @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 * } | undefined, * run: (store: { locale?: Locale, origin?: string, messageCalls?: Set}, * 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} 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://inlang.com/m/gerre34r/library-inlang-paraglideJs/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): Locale; export function extractLocaleFromRequestWithStrategies(request: Request, strategies: typeof strategy): Locale; export function extractLocaleFromRequestAsync(request: Request): Promise; /** * @typedef {"cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage"} BuiltInStrategy */ /** * @typedef {`custom_${string}`} CustomStrategy */ /** * @typedef {BuiltInStrategy | CustomStrategy} Strategy */ /** * @typedef {Array} Strategies */ /** * @typedef {{ getLocale: (request?: Request) => Promise | (string | undefined) }} CustomServerStrategyHandler */ /** * @typedef {{ getLocale: () => Promise | (string | undefined), setLocale: (locale: string) => Promise | void }} CustomClientStrategyHandler */ /** @type {Map} */ export const customServerStrategies: Map; /** @type {Map} */ export const customClientStrategies: Map; export type ShouldRedirectServerInput = { request: Request; url?: string | URL | undefined; locale?: "en" | "en-US" | "af" | "ar" | "en-GB" | "en-ZA" | "es" | "es-US" | "fr" | "fr-CA" | "fr-FR" | undefined; }; export type ShouldRedirectClientInput = { request?: undefined; url?: string | URL | undefined; locale?: "en" | "en-US" | "af" | "ar" | "en-GB" | "en-ZA" | "es" | "es-US" | "fr" | "fr-CA" | "fr-FR" | undefined; }; 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; } | undefined; run: (store: { locale?: Locale; origin?: string; messageCalls?: Set; }, cb: any) => any; }; export type SetLocaleFn = (newLocale: Locale, options?: { reload?: boolean; }) => void | Promise; export type BuiltInStrategy = "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage"; export type CustomStrategy = `custom_${string}`; export type Strategy = BuiltInStrategy | CustomStrategy; export type Strategies = Array; export type CustomServerStrategyHandler = { getLocale: (request?: Request) => Promise | (string | undefined); }; export type CustomClientStrategyHandler = { getLocale: () => Promise | (string | undefined); setLocale: (locale: string) => Promise | 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; /** * Record of markup attributes for a tag instance. */ export type MessageMarkupAttributes = Record; /** * 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; /** * Type-only metadata attached to compiled message functions. */ export type MessageMetadata = { 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) => 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 = (params: Record, options: { locale: T; }) => LocalizedString;