intlayer Elysia Plugin Documentation

The intlayer plugin for Elysia detects the user's locale and injects an intlayer object into the route context. It also enables the use of global translation functions within the request context.

Usage

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
  intlayer.t({
    en: "Hello",
    fr: "Bonjour",
  })
);

The same helpers are available as standalone exports, so you can call them without destructuring the route context:

import { Elysia } from "elysia";
import { intlayer, t } from "elysia-intlayer";

const app = new Elysia().use(intlayer()).get("/", () =>
  t({
    en: "Hello",
    fr: "Bonjour",
  })
);

Description

The plugin performs the following tasks:

1. Locale Detection: It reads the locale explicitly set by the client from storage (cookie, header), then falls back to the locale negotiated from the Accept-Language header.
2. Context Injection: It adds an intlayer property to the Elysia route context, containing:
   • locale: The locale to use for this request, locale_storage taking precedence over locale_detected.
   • locale_storage: The locale explicitly requested by the client through a cookie or a header.
   • locale_detected: The locale negotiated from the request headers.
   • defaultLocale: The locale configured as fallback in intlayer.config.ts.
   • t: A translation function.
   • getIntlayer: A function to retrieve dictionaries by key.
   • getDictionary: A function to process dictionary objects.
3. Context Management: It uses AsyncLocalStorage to manage an asynchronous context, allowing the global Intlayer functions (t, getIntlayer, getDictionary) to access the request-specific locale without passing the context object around.

Unlike the Node-based Intlayer plugins, elysia-intlayer relies on AsyncLocalStorage instead of cls-hooked, because cls-hooked depends on async_hooks.createHook, which Bun does not implement.

The request context is released once the response is mapped, so the standalone helpers never resolve against an already terminated request. When called outside of a request handled by the plugin, they fall back to the configured default locale.

Configuration

The plugin reads your intlayer.config.ts file. You can customize the cookie and header used for locale detection:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

For more information on configuration, visit the configuration documentation.