Paraglide JS

Tool

ExtractLocaleFromRequestOptions

Defined in: runtime/extract-locale-from-request.js:16

Properties

effectiveRequestUrl?

optional effectiveRequestUrl: string | URL

Defined in: runtime/extract-locale-from-request.js:17

Effective request URL to use for route matching and locale detection with the URL strategy.

ShouldRedirectClientInput

Defined in: runtime/should-redirect.js:14

Properties

locale?

optional locale: string

Defined in: runtime/should-redirect.js:17

request?

optional request: undefined

Defined in: runtime/should-redirect.js:15

url?

optional url: string | URL

Defined in: runtime/should-redirect.js:16

ShouldRedirectResult

Defined in: runtime/should-redirect.js:21

Properties

locale

locale: string

Defined in: runtime/should-redirect.js:23

redirectUrl

redirectUrl: undefined | URL

Defined in: runtime/should-redirect.js:24

Destination URL when a redirect is required.

shouldRedirect

shouldRedirect: boolean

Defined in: runtime/should-redirect.js:22

Indicates whether the consumer should perform a redirect.

ShouldRedirectServerInput

Defined in: runtime/should-redirect.js:9

Properties

effectiveRequestUrl?

optional effectiveRequestUrl: string | URL

Defined in: runtime/should-redirect.js:11

Effective request URL to use for route matching, locale detection with the URL strategy, and redirect targets.

locale?

optional locale: string

Defined in: runtime/should-redirect.js:12

request

request: Request

Defined in: runtime/should-redirect.js:10

CustomClientStrategyHandler

CustomClientStrategyHandler<> = object

Defined in: runtime/strategy.js:22

Type Declaration

getLocale()

getLocale: () => Promise<string | undefined> | string | undefined

Returns

Promise<string | undefined> | string | undefined

setLocale()

setLocale: (locale) => Promise<void> | void

CustomServerStrategyHandler

CustomServerStrategyHandler<> = object

Defined in: runtime/strategy.js:18

Type Declaration

getLocale()

getLocale: (request?) => Promise<string | undefined> | string | undefined

Returns

Promise<string | undefined> | string | undefined

Locale

Locale = Locale

Defined in: runtime/ambient.d.ts:9

Locale

Locale<> = string

Defined in: runtime/type-definitions.js:9

ParaglideAsyncLocalStorage

ParaglideAsyncLocalStorage<> = object

Defined in: runtime/variables.js:132

Type Declaration

run()

run: (store, cb) => any

getStore()

getStore(): undefined | { locale?: Locale; messageCalls?: Set<string>; origin?: string; }

Returns

undefined | { locale?: Locale; messageCalls?: Set<string>; origin?: string; }

SetLocaleFn()

SetLocaleFn<> = (newLocale, options?) => void | Promise<void>

Defined in: runtime/set-locale.js:34

ShouldRedirectInput

ShouldRedirectInput<> = ShouldRedirectServerInput | ShouldRedirectClientInput

Defined in: runtime/should-redirect.js:19

baseLocale

const baseLocale: "en" = "en"

Defined in: runtime/variables.js:9

The project's base locale.

Example

if (locale === baseLocale) {
    // do something
  }

cookieMaxAge

const cookieMaxAge: number

Defined in: runtime/variables.js:25

cookieName

const cookieName: string = "<cookie-name>"

Defined in: runtime/variables.js:22

disableAsyncLocalStorage

const disableAsyncLocalStorage: false = false

Defined in: runtime/variables.js:145

experimentalMiddlewareLocaleSplitting

const experimentalMiddlewareLocaleSplitting: false = false

Defined in: runtime/variables.js:147

experimentalStaticLocale

const experimentalStaticLocale: undefined | string = undefined

Defined in: runtime/variables.js:152

isServer

const isServer: boolean

Defined in: runtime/variables.js:149

locales

const locales: readonly string[]

Defined in: runtime/variables.js:19

The project's locales that have been specified in the settings.

Example

if (locales.includes(userSelectedLocale) === false) {
    throw new Error('Locale is not available');
  }

routeStrategies

const routeStrategies: object[] = []

Defined in: runtime/variables.js:49

Route-level strategy overrides.

match uses URLPattern syntax.

Type Declaration

strategy?

optional strategy: (`custom-${string}` | "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage")[]

serverAsyncLocalStorage

serverAsyncLocalStorage: undefined | ParaglideAsyncLocalStorage = undefined

Defined in: runtime/variables.js:143

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.

strategy

const strategy: (`custom-${string}` | "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage")[]

Defined in: runtime/variables.js:36

urlPatterns

const urlPatterns: object[] = []

Defined in: runtime/variables.js:56

The used URL patterns.

Type Declaration

assertIsLocale()

assertIsLocale(input): string

Defined in: runtime/check-locale.js:49

Asserts that the input can be normalized to a locale.

Returns

string

The input normalized to a Locale.

defineCustomClientStrategy()

defineCustomClientStrategy(strategy, handler): void

Defined in: runtime/strategy.js:73

Defines a custom strategy that is executed on the client.

Parameters

strategy

string

The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.

handler

CustomClientStrategyHandler

The handler for the custom strategy, which should implement the methods getLocale and setLocale.

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#write-your-own-strategy

defineCustomServerStrategy()

defineCustomServerStrategy(strategy, handler): void

Defined in: runtime/strategy.js:53

Defines a custom strategy that is executed on the server.

Parameters

strategy

string

The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.

handler

CustomServerStrategyHandler

The handler for the custom strategy, which should implement the method getLocale.

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#write-your-own-strategy

deLocalizeHref()

deLocalizeHref(href): string

Defined in: runtime/localize-href.js:110

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

Parameters

href

string

The href to de-localize (can be relative or absolute)

Returns

string

The de-localized href, relative if input was relative

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing

Example

// 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.

deLocalizeUrl()

deLocalizeUrl(url): URL

Defined in: runtime/localize-url.js:189

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.

Parameters

url

The URL to de-localize. If string, must be absolute.

string | URL

Returns

URL

The de-localized URL, always absolute

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing

Examples

// 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();
});

// 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")

extractLocaleFromCookie()

extractLocaleFromCookie(): undefined | string

Defined in: runtime/extract-locale-from-cookie.js:12

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

undefined | string

extractLocaleFromHeader()

extractLocaleFromHeader(request): undefined | string

Defined in: runtime/extract-locale-from-header.js:15

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.

Parameters

request

Request

The request object to extract the locale from.

Returns

undefined | string

The negotiated preferred language.

Example

const locale = extractLocaleFromHeader(request);

extractLocaleFromNavigator()

extractLocaleFromNavigator(): undefined | string

Defined in: runtime/extract-locale-from-navigator.js:14

Negotiates a preferred language from navigator.languages.

Use the function on the client to extract the locale from the navigator.languages array.

Returns

undefined | string

Example

const locale = extractLocaleFromNavigator();

extractLocaleFromRequest()

extractLocaleFromRequest(request, options?): string

Defined in: runtime/extract-locale-from-request.js:40

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.

Parameters

request

Request

options?

ExtractLocaleFromRequestOptions = {}

Returns

string

Example

const locale = extractLocaleFromRequest(request);

extractLocaleFromRequestAsync()

extractLocaleFromRequestAsync(request, options?): Promise<string>

Defined in: runtime/extract-locale-from-request-async.js:37

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.

Parameters

request

Request

The request object to extract the locale from.

options?

Effective request URL to use for route matching and locale detection with the URL strategy.

effectiveRequestUrl?

string | URL

Returns

Promise<string>

The extracted locale.

See

https://github.com/opral/inlang-paraglide-js/issues/527#issuecomment-2978151022

Examples

// Basic usage
  const locale = await extractLocaleFromRequestAsync(request);

// With custom async server strategy
  defineCustomServerStrategy("custom-database", {
    getLocale: async (request) => {
      const userId = extractUserIdFromRequest(request);
      return await getUserLocaleFromDatabase(userId);
    }
  });

  const locale = await extractLocaleFromRequestAsync(request);

extractLocaleFromUrl()

extractLocaleFromUrl(url): undefined | string

Defined in: runtime/extract-locale-from-url.js:29

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.

Parameters

url

The full URL from which to extract the locale.

string | URL

Returns

undefined | string

The extracted locale, or undefined if no locale is found.

generateStaticLocalizedUrls()

generateStaticLocalizedUrls(urls): URL[]

Defined in: runtime/generate-static-localized-urls.js:52

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.

Parameters

urls

(string | URL)[]

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.

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/static-site-generation

Examples

// 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"]

// Use with framework SSG APIs
// SvelteKit
export function entries() {
  const paths = ["/", "/about", "/contact"];
  return generateStaticLocalizedUrls(paths).map(url => ({
    locale: extractLocaleFromUrl(url)
  }));
}

// Sitemap generation
const allPages = ["/", "/about", "/blog"];
const sitemapUrls = generateStaticLocalizedUrls(allPages);

getLocale()

getLocale(): string

Defined in: runtime/get-locale.js:53

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().

Returns

string

The current locale.

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy - Configure locale detection strategies

Example

if (getLocale() === 'de') {
    console.log('Germany 🇩🇪');
  } else if (getLocale() === 'nl') {
    console.log('Netherlands 🇳🇱');
  }

getStrategyForUrl()

getStrategyForUrl(url): (`custom-${string}` | "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage")[]

Defined in: runtime/variables.js:101

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.

Parameters

url

string | URL

Returns

(`custom-${string}` | "cookie" | "baseLocale" | "globalVariable" | "url" | "preferredLanguage" | "localStorage")[]

getTextDirection()

getTextDirection(locale?): "ltr" | "rtl"

Defined in: runtime/get-text-direction.js:31

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().

Parameters

locale?

string = ...

Target locale. If not provided, uses getLocale()

Returns

"ltr" | "rtl"

Example

getTextDirection(); // "ltr" or "rtl" for current locale
  getTextDirection("ar"); // "rtl"
  getTextDirection("en"); // "ltr"

getUrlOrigin()

getUrlOrigin(): string

Defined in: runtime/get-url-origin.js:12

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().

Returns

string

isExcludedByRouteStrategy()

isExcludedByRouteStrategy(url): boolean

Defined in: runtime/variables.js:119

Returns whether the given URL is excluded from middleware i18n processing.

Parameters

url

string | URL

Returns

boolean

isLocale()

isLocale(locale): locale is string

Defined in: runtime/check-locale.js:38

Check if something is an available locale with the canonical project casing.

Parameters

locale

unknown

Returns

locale is string

Example

if (isLocale(params.locale)) {
    setLocale(params.locale);
  } else {
    setLocale('en');
  }

Use `toLocale()` when you want case-insensitive matching and canonicalization.

localizeHref()

localizeHref(href, options?): string

Defined in: runtime/localize-href.js:45

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

Parameters

href

string

The href to localize (can be relative or absolute)

options?

Options for localization

locale?

string

Target locale. If not provided, uses getLocale()

Returns

string

The localized href, relative if input was relative

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing

Example

// 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.

localizeUrl()

localizeUrl(url, options?): URL

Defined in: runtime/localize-url.js:55

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.

Parameters

url

The URL to localize. If string, must be absolute.

string | URL

options?

Options for localization

locale?

string

Target locale. If not provided, uses getLocale()

Returns

URL

The localized URL, always absolute

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing

Examples

// 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();
});

// 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")

overwriteGetLocale()

overwriteGetLocale(fn): void

Defined in: runtime/get-locale.js:194

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.

Parameters

fn

() => string

The new implementation for getLocale().

Returns

void

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy

Example

overwriteGetLocale(() => {
    return Cookies.get('locale') ?? baseLocale
  });

overwriteGetUrlOrigin()

overwriteGetUrlOrigin(fn): void

Defined in: runtime/get-url-origin.js:29

Overwrite the getUrlOrigin function.

Use this function in server environments to define how the URL origin is resolved.

Parameters

fn

() => string

The new implementation for getUrlOrigin().

Returns

void

overwriteServerAsyncLocalStorage()

overwriteServerAsyncLocalStorage(value): void

Defined in: runtime/variables.js:164

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.

Parameters

value

undefined | ParaglideAsyncLocalStorage

Returns

void

overwriteSetLocale()

overwriteSetLocale(fn): void

Defined in: runtime/set-locale.js:181

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.

Parameters

fn

SetLocaleFn

Returns

void

Example

overwriteSetLocale((newLocale) => {
    // set the locale in a cookie
    return Cookies.set('locale', newLocale)
  });

setLocale()

setLocale(newLocale, options?): void | Promise<void>

Defined in: runtime/set-locale.js:58

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.

Parameters

newLocale

string

options?

reload?

boolean

Returns

void | Promise<void>

See

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy

Examples

setLocale('en');

setLocale('en', { reload: false });

shouldRedirect()

shouldRedirect(input?): Promise<ShouldRedirectResult>

Defined in: runtime/should-redirect.js:80

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.

// 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 });
  }
}

// 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);
}

// 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);
  }
}

toLocale()

toLocale(value): undefined | string

Defined in: runtime/check-locale.js:9

Coerces a locale-like string to the canonical locale value used by the runtime.

trackMessageCall(safeModuleId, locale): void

Defined in: runtime/track-message-call.js:7

On this page

Repository

opral/paraglide-js 381 stars 551 closed / 33 open issues 56 contributors

Author

inlang

License

MIT

Pricing

free

paraglide jslibrariesappswebsitedeveloperparaglidei18nlibrarylocalizationsdksdk-jssveltereactnextjsremixvueastrojavascriptsolidtypescriptreact routerinlang