API Reference

                  
                    setRequestLocale(url: URL, getConfig?: GetRequestConfigFn): Promise<boolean>
                  
                

Extracts and validates the locale from the first URL pathname segment, then calls your getConfig function to load messages. Must be awaited before any other call. For SSR, prefer createIntlMiddleware() or runWithLocale() so the complete render stays request-isolated.

                  
                    runWithLocale<R>(url: URL, fn: () => R | Promise<R>, getConfig?: GetRequestConfigFn): Promise<R>
                  
                

Runs a function inside an isolated per-request context using Node.js AsyncLocalStorage. SSR runtimes without safe request-local storage fail explicitly instead of sharing global state.

                  
                    getLocale(): string
                  
                

Returns the current locale string set by setRequestLocale. Throws if called before setting the locale.

                  
                    getTranslations<T>(namespace?: string)
                  
                

Returns a typed t(key, values?) function scoped to the given namespace. The optional values object replaces {curlyOpen}varName{curlyClose} placeholders. Also exposes parser-sanitized t.markup(key, tags | {curlyOpen} values?, tags {curlyClose}) for HTML interpolation and t.raw(key) for accessing raw values without coercion.

                  
                    defineRequestConfig(fn: GetRequestConfigFn): GetRequestConfigFn
                  
                

Registers and returns a message loader. Import the module that declares it before initializing the language. See Custom message loading for complete files.

                  
                    getLocales(): string[]
                  
                

Returns the array of locales configured via the integration options or createIntlMiddleware. Returns an empty array if not set.

                  
                    isValidLocale(locale: string): boolean
                  
                

Checks that a locale has valid BCP-47-style syntax and, when a locales list is configured, that it is included in that list.

                  
                    getMessages(): Record<string, unknown>
                  
                

Returns the full messages object for the current request. Throws if called before setRequestLocale.

                  
                    createIntlMiddleware(options: { locales: string[]; defaultLocale?: string; routes?: RoutesMap })
                  
                

Creates Astro middleware that validates and loads the request locale, then keeps the complete render or rewrite inside a Node.js AsyncLocalStorage context. It also sets locales, defaultLocale, and routes in the intl store. Import from astro-intl/middleware.

                  
                    path(routeKey: string, options?: { locale?: string; params?: Record<string, string>; encode?: boolean }): string
                  
                

Generates a localized URL for a named route. Uses the current locale if none is specified, rejects invalid locale segments, and substitutes [param] placeholders with the provided params. Import from astro-intl/routing.

                  
                    switchLocalePath(currentPath: string | URL, nextLocale: string): string
                  
                

Converts the current URL to its equivalent in another validated locale. Matches the path against route templates, extracts dynamic params, and rebuilds the URL using the target locale's template. Preserves query strings and hashes. Import from astro-intl/routing.

Type returned by your getRequestConfig function. Contains locale: string and messages: Record.

Configuration type for the integration options. Contains defaultLocale: string, locales: string[], routes?: RoutesMap, and fallbackRoutes?: FallbackRouteInfo[].

Union type for interpolation values: string | number | boolean | null | undefined. Used as the value type in the values object passed to t() and t.markup().

Utility type that generates all valid dot-notation paths for a given messages object. Used internally to provide autocomplete for translation keys.

Type for the routes configuration object. Maps route keys to an object of locale → URL template pairs. Example: { about: { en: "/about", es: "/sobre-nosotros" } }.

                  
                    createGetTranslations<UI, DefaultLocale>(ui: UI, defaultLocale: DefaultLocale)
                  
                

Creates a standalone translation function for React without relying on the global store. Returns getTranslations(lang, namespace) with t.rich() support returning ReactNode[]. Import from astro-intl/react.

                  
                    createGetTranslations<UI, DefaultLocale>(ui: UI, defaultLocale: DefaultLocale)
                  
                

Creates a standalone translation function for Svelte without relying on the global store. Returns getTranslations(lang, namespace) with t.rich() support returning RichSegment[]. Import from astro-intl/svelte.

                  
                    renderRichText(segments: RichSegment[], options?: { tags?: Record<string, string>; components?: Record<string, (chunks: string) => string> }): string
                  
                

Converts an array of RichSegment[] into a sanitized HTML string. Text and chunks are escaped, unsafe native tag mappings are rejected, and component callbacks are treated as trusted application code before final sanitization. Import from astro-intl/svelte.

                  
                    getFallbackRoutes(): FallbackRouteInfo[]
                  
                

Returns the i18n fallback routes collected from Astro 6.1's astro:routes:resolved hook. Returns an empty array on Astro < 6.1 or when no fallback routes are configured. Each entry contains the route pattern, optional pathname, and the locale.

Type for fallback route entries. Contains pattern: string (the route pattern), pathname?: string (the static pathname if available), and locale: string (the locale this fallback serves).

Returns the raw translation value without string coercion. Use this to access arrays, objects, and numbers in their native JavaScript type instead of getting [object Object].

Exported type shaped as {curlyOpen} dir: string {curlyClose}. The integration option messagesDir accepts a string directly, not this object. See Configuration options for its limitations.

                  
                    <AutoRedirect locales={string[]} defaultLocale={string} />
                  
                

Astro component that validates its locale props, detects the user's browser language, and redirects to the appropriate encoded localized route. defaultLocale must be included in locales. Import from astro-intl/components.

Only in the browser, getLocale() can read the language from window.location.pathname when there is no context. This does not load messages or replace initialization during a static build or server rendering.