Documentación del Plugin intlayer para Elysia

El plugin intlayer para Elysia detecta el locale del usuario e inyecta un objeto intlayer en el contexto de la ruta. También permite el uso de funciones globales de traducción dentro del contexto de la request.

Uso

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

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

El plugin registra su contexto mediante un derive global, que Elysia tipa como Partial<{ intlayer: IntlayerContext }>. El valor siempre está presente en tiempo de ejecución para las rutas registradas después de .use(intlayer()), así que usa la aserción non-null (intlayer!.t), u optional chaining, para satisfacer a TypeScript en modo strict.

Los mismos helpers están disponibles como exports independientes, por lo que puedes llamarlos sin desestructurar el contexto de la ruta:

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

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

Descripción

El plugin realiza las siguientes tareas:

1. Detección de locale: Lee el locale establecido explícitamente por el cliente desde el storage (cookie, header), y luego recurre al locale negociado a partir del header Accept-Language.
2. Inyección en el contexto: Añade una propiedad intlayer al contexto de ruta de Elysia (ver la tabla Contexto de la ruta más abajo).
3. Preparación de los diccionarios: Llama a prepareIntlayer cuando se crea el plugin, de modo que los diccionarios se construyen al arrancar la aplicación.

Contexto de la ruta

Cuando los helpers independientes se llaman fuera de una request gestionada por el plugin, recurren al locale por defecto configurado.

Orden de resolución de la locale

Por defecto, el plugin resuelve la locale en este orden:

1. La cookie INTLAYER_LOCALE.
2. El header x-intlayer-locale.
3. La negociación del header Accept-Language.
4. La defaultLocale configurada.

# Negociada desde `Accept-Language`
curl -H "Accept-Language: fr" http://localhost:3000/
# Bonjour

# La cookie tiene prioridad sobre `Accept-Language`
curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
# Hola

# El header tiene prioridad sobre `Accept-Language`
curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
# Hola

Configuración

El plugin lee tu archivo intlayer.config.ts. Puedes personalizar la cookie y el header usados para la detección del locale:

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

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

export default config;

Para más información sobre la configuración, visita la documentación de configuración.

Documentación relacionada