Documentação do Plugin intlayer para Elysia

O plugin intlayer para Elysia deteta o locale do utilizador e injeta um objeto intlayer no contexto da rota. Também permite o uso de funções de tradução globais dentro do contexto da request.

Uso

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

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

O plugin registra seu contexto por meio de um derive global, que o Elysia tipa como Partial<{ intlayer: IntlayerContext }>. Em tempo de execução o valor está sempre presente para as rotas registradas após .use(intlayer()), portanto use a non-null assertion (intlayer!.t), ou optional chaining, para satisfazer o TypeScript no modo strict.

Os mesmos helpers estão disponíveis como exports autónomos, para que possa chamá-los sem desestruturar o contexto da rota:

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

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

Descrição

O plugin realiza as seguintes tarefas:

1. Detecção de locale: Lê o locale definido explicitamente pelo cliente a partir do storage (cookie, header) e, em seguida, recorre ao locale negociado a partir do header Accept-Language.
2. Injeção no contexto: Adiciona uma propriedade intlayer ao contexto de rota do Elysia (veja a tabela Contexto da rota abaixo).
3. Preparação dos dicionários: Chama prepareIntlayer quando o plugin é criado, de modo que os dicionários são construídos na inicialização da aplicação.

Contexto da rota

Quando os helpers autónomos são chamados fora de uma request tratada pelo plugin, recorrem ao locale por omissão configurado.

Ordem de resolução da locale

Por padrão, o plugin resolve a locale nesta ordem:

1. O cookie INTLAYER_LOCALE.
2. O header x-intlayer-locale.
3. A negociação do header Accept-Language.
4. A defaultLocale configurada.

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

# O cookie tem precedência sobre `Accept-Language`
curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
# Hola

# O header tem precedência sobre `Accept-Language`
curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
# Hola

Configuração

O plugin lê o seu ficheiro intlayer.config.ts. Pode personalizar o cookie e o header usados para a deteção do 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 mais informações sobre a configuração, visite a documentação de configuração.

Documentação relacionada