Paraglide JS

Paraglide JS uses AsyncLocalStorage to manage locale state per request.

• Vercel Edge / Cloudflare Workers: Keep AsyncLocalStorage enabled. These runtimes support it, and it is the recommended setup.
• Fallback: If you are using a runtime that does not provide AsyncLocalStorage or node:async_hooks but still guarantees per-request isolation, you may use the disableAsyncLocalStorage fallback.

Warning: Only use the fallback if your runtime guarantees per-request isolation. In a multi-request server environment without isolation, using this fallback could leak locale state between concurrent requests.

The strategy option defines the precedence for detecting the user's locale. The order in the array determines which method is tried first.

Supported strategies include:

• url (via URL patterns)
• cookie (using cookieName and cookieDomain)
• localStorage (using localStorageKey)
• globalVariable (fallback)
• baseLocale (final fallback)
• Custom strategies using the pattern custom-[A-Za-z0-9]+.

Default: ["cookie", "globalVariable", "baseLocale"] (optimized for browser/server compatibility).

Example of custom precedence:

strategy: ['url', 'cookie', 'baseLocale']

// Example strategy configuration
await compile({
  project: "./project.inlang",
  outdir: "./src/paraglide",
  strategy: ['url', 'cookie', 'baseLocale']
});

You cannot use message-format interpolation (e.g., {name}) inside a JSON blob stored in a translation key. If your array items or object values require dynamic data, you should use separate message keys for each item and construct the array manually in your code.

// messages/en.json
{
  "step_0": "Welcome, {name}!",
  "step_1": "You have {count} items in your cart",
  "step_2": "Proceed to checkout"
}

const steps = [
  m.step_0({ name: "Alex" }),
  m.step_1({ count: 3 }),
  m.step_2(),
];

For successful client-side hydration, the server and the client must agree on the locale source.

Warning: Do not use localStorage as a primary locale source for SSR. localStorage is unavailable during the initial server request. If you need to persist a user's locale so it affects the first response, use a server-visible strategy like cookie.

Common causes of hydration mismatches:

• Different strategy order on server vs client.
• Server reads from URL while client reads from localStorage.
• Serving cached HTML that contains a stale locale.

Paraglide JS is a compiler-based i18n library that typically ships 3-10x smaller bundles than runtime-based libraries like i18next.

Key advantages include:

• Tree-shaking: Paraglide only ships the messages you actually use on a page. Unused messages are removed at build time, making the bundle size immune to the total number of messages in your project.
• Compiled Format: Messages are compiled into functions rather than being shipped as a large JSON dictionary.
• No Manual Namespacing Required: Unlike runtime libraries that require developers to manually split messages into namespaces to keep bundles small, Paraglide's tree-shaking makes manual namespacing redundant.

By default, Paraglide compiles messages into functions that contain all locales. For applications with a very large number of locales, you may want to use Lazy Locale Loading, which fetches only the current locale's messages on-demand.

When to use Lazy Loading

• Under ~20 locales: Tree-shaking unused messages is typically more efficient than the overhead of lazy loading. Paraglide's standard compiler approach is recommended.
• Over ~20 locales: Lazy loading may become beneficial depending on your application's specific message usage patterns.

Note: There is no hard limit on the number of locales you can use in Paraglide. Lazy loading is an optimization, not a requirement. An experimental locale splitting option is available for apps that require this behavior.

Paraglide supports several declaration formatters for locale-aware output:

• plural: Uses Intl.PluralRules for plural and ordinal categories.
• number: Uses Intl.NumberFormat for numbers, currency, and compact notation.
• datetime: Uses Intl.DateTimeFormat for dates and times.
• relativetime: Uses Intl.RelativeTimeFormat for relative values (e.g., "yesterday").

Message syntax is plugin-based. You can use the default inlang format or the ICU MessageFormat via the ICU plugin (e.g., {count, plural, one {# item} other {# items}}).

// Pluralization example
m.items_in_cart({ count: 1 }); // "1 item in cart"
m.items_in_cart({ count: 5 }); // "5 items in cart"

The outputStructure option determines how the generated files are organized in the outdir.

• message-modules (Default): Each message has its own module containing all language versions. This is optimized for production because it enables better tree-shaking for bundlers.
• locale-modules: Each locale has its own module containing all messages. This is recommended for development because it results in fewer files, which speeds up bundlers by reducing HTTP requests in dev mode.

Note: locale-modules can lead to larger bundle sizes in production because bundlers often struggle to tree-shake this structure effectively.

// Recommended for development
await compile({
  project: "./project.inlang",
  outdir: "./src/paraglide",
  outputStructure: "locale-modules"
});

Paraglide JS is composed of four distinct parts that work together to manage translations and locale state: