Dokumentacja wtyczki intlayer dla Elysia

Wtyczka intlayer dla Elysia wykrywa locale użytkownika i wstrzykuje obiekt intlayer do kontekstu route. Umożliwia również użycie globalnych funkcji tłumaczeniowych w kontekście żądania.

Użycie

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

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

Te same helpery są dostępne jako samodzielne eksporty, więc możesz je wywołać bez destrukturyzacji kontekstu route:

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

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

Opis

Wtyczka wykonuje następujące zadania:

1. Wykrywanie locale: Odczytuje locale ustawione jawnie przez klienta ze storage (cookie, header), a następnie wraca do locale wynegocjowanego z nagłówka Accept-Language.
2. Wstrzyknięcie do kontekstu: Dodaje właściwość intlayer do kontekstu route Elysia, zawierającą:
   • locale: Locale używane dla tego żądania, przy czym locale_storage ma pierwszeństwo przed locale_detected.
   • locale_storage: Locale zażądane jawnie przez klienta poprzez cookie lub header.
   • locale_detected: Locale wynegocjowane z nagłówków żądania.
   • defaultLocale: Locale skonfigurowane jako fallback w intlayer.config.ts.
   • t: Funkcja tłumaczenia.
   • getIntlayer: Funkcja pobierająca słowniki po kluczu.
   • getDictionary: Funkcja przetwarzająca obiekty słowników.
3. Zarządzanie kontekstem: Używa AsyncLocalStorage do zarządzania asynchronicznym kontekstem, dzięki czemu globalne funkcje Intlayer (t, getIntlayer, getDictionary) mają dostęp do locale specyficznego dla żądania bez przekazywania obiektu kontekstu.

W przeciwieństwie do wtyczek Intlayer opartych na Node, elysia-intlayer opiera się na AsyncLocalStorage zamiast cls-hooked, ponieważ cls-hooked zależy od async_hooks.createHook, którego Bun nie implementuje.

Kontekst żądania jest zwalniany po zmapowaniu odpowiedzi, więc samodzielne helpery nigdy nie rozwiązują się względem już zakończonego żądania. Wywołane poza żądaniem obsługiwanym przez wtyczkę, wracają do skonfigurowanego domyślnego locale.

Konfiguracja

Wtyczka odczytuje Twój plik intlayer.config.ts. Możesz dostosować cookie i header używane do wykrywania locale:

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;

Więcej informacji o konfiguracji znajdziesz w dokumentacji konfiguracji.