Translate your Elysia backend website using Intlayer | Internationalization (i18n)

elysia-intlayer is a powerful internationalization (i18n) plugin for Elysia applications, designed to make your backend services globally accessible by providing localized responses based on the client's preferences.

See package implementation on GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

Practical Use Cases

• Displaying Backend Errors in User's Language: When an error occurs, displaying messages in the user's native language improves understanding and reduces frustration. This is especially useful for dynamic error messages that might be shown in front-end components like toasts or modals.
• Retrieving Multilingual Content: For applications pulling content from a database, internationalization ensures that you can serve this content in multiple languages. This is crucial for platforms like e-commerce sites or content management systems that need to display product descriptions, articles, and other content in the language preferred by the user.
• Sending Multilingual Emails: Whether it's transactional emails, marketing campaigns, or notifications, sending emails in the recipient's language can significantly increase engagement and effectiveness.
• Multilingual Push Notifications: For mobile applications, sending push notifications in a user's preferred language can enhance interaction and retention. This personal touch can make notifications feel more relevant and actionable.
• Other Communications: Any form of communication from the backend, such as SMS messages, system alerts, or user interface updates, benefits from being in the user's language, ensuring clarity and enhancing the overall user experience.

By internationalizing the backend, your application not only respects cultural differences but also aligns better with global market needs, making it a key step in scaling your services worldwide.

Getting Started

See Application Template on GitHub.

Installation

To begin using elysia-intlayer, install the package using your package manager:

npx intlayer init --interactive

the --interactive flag is optional. Use intlayer-cli init if you're an AI agent.

This command will detect your environment and install the required packages. For example:

npm install intlayer elysia-intlayer

Elysia targets the Bun runtime. elysia-intlayer relies on AsyncLocalStorage (instead of the cls-hooked library used by the Node-based Intlayer plugins) precisely because Bun does not implement async_hooks.createHook.

Setup

Configure the internationalization settings by creating an intlayer.config.ts in your project root:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    /**
     * Default locale used as a fallback if the requested locale is not found.
     */
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Declare Your Content

Create and manage your content declarations to store translations:

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    }),
  },
} satisfies Dictionary;

export default indexContent;

Your content declarations can be defined anywhere in your application as soon as they are included into the contentDir directory (by default, ./src). And match the content declaration file extension (by default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

For more details, refer to the content declaration documentation.

Elysia Application Setup

Register the plugin with .use(intlayer()). It injects an intlayer object into every route context, exposing the negotiated locale and the translation helpers:

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

const app = new Elysia()
  // Load the internationalization plugin
  .use(intlayer())
  // Routes
  .get("/", ({ intlayer }) => ({
    // Locale used for this request, `Accept-Language` negotiated or read from storage
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    content: intlayer!.getIntlayer("index").exampleOfContent,
  }))
  .listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

The plugin registers its context through a global derive, which Elysia types as Partial<{ intlayer: IntlayerContext }>. The value is always present at runtime for routes registered after .use(intlayer()), so use the non-null assertion (intlayer!.locale) — or optional chaining — to satisfy TypeScript in strict mode.

The route context exposes:

The same helpers are also exported standalone. They resolve the current request through AsyncLocalStorage, so you can call them without destructuring the context:

import { Elysia } from "elysia";
import { intlayer, t, getDictionary, getIntlayer } from "elysia-intlayer";
import dictionaryExample from "./index.content";

const app = new Elysia()
  .use(intlayer())
  .get("/t_example", () =>
    t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    })
  )
  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
  .get(
    "/getDictionary_example",
    () => getDictionary(dictionaryExample).exampleOfContent
  )
  .listen(3000);

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

Run Your Application

Add the Intlayer scripts to your package.json. intlayer build compiles your content declarations into the .intlayer directory and generates the TypeScript types:

{
  "scripts": {
    "dev": "intlayer build && bun run --watch src/index.ts",
    "build": "intlayer build",
    "start": "bun run src/index.ts",
    "i18n:fill": "intlayer fill",
    "i18n:test": "intlayer test"
  }
}

Then start the server:

bun run dev

Test the locale negotiation with Accept-Language:

curl -H "Accept-Language: fr" http://localhost:3000/
# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}

curl -H "Accept-Language: es" http://localhost:3000/
# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}

intlayer build is not strictly required before bun run src/index.ts: the plugin also prepares the dictionaries when the Elysia app boots. Running it upfront keeps the generated types in sync for your editor and avoids the build cost on the first request.

Compatibility

elysia-intlayer is fully compatible with:

• react-intlayer for React applications
• next-intlayer for Next.js applications
• vite-intlayer for Vite applications

It also works seamlessly with any internationalization solution across various environments, including browsers and API requests.

By default, the plugin resolves the locale in this order:

1. The INTLAYER_LOCALE cookie.
2. The x-intlayer-locale header.
3. The Accept-Language header negotiation.

You can customize the cookie and header used for locale detection:

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

const config: IntlayerConfig = {
  // ... Other configuration options
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

For more information on configuration and advanced topics, visit our documentation.

Configure TypeScript

elysia-intlayer leverages the robust capabilities of TypeScript to enhance the internationalization process. TypeScript's static typing ensures that every translation key is accounted for, reducing the risk of missing translations and improving maintainability.

Ensure the autogenerated types (by default at ./types/intlayer.d.ts) are included in your tsconfig.json file.

{
  // ... Your existing TypeScript configurations
  "include": [
    // ... Your existing TypeScript configurations
    ".intlayer/**/*.ts", // Include the auto-generated types
  ],
}

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# Ignore the files generated by Intlayer
.intlayer