Traduza seu site backend Elysia usando Intlayer | Internacionalização (i18n)

elysia-intlayer é um poderoso plugin de internacionalização (i18n) para aplicações Elysia, projetado para tornar seus serviços de backend globalmente acessíveis, fornecendo respostas localizadas com base nas preferências do cliente.

Veja a implementação do pacote no GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

Casos de Uso Práticos

• Exibir Erros do Backend no Idioma do Usuário: Quando um erro ocorre, exibir mensagens no idioma nativo do usuário melhora a compreensão e reduz a frustração. Isso é especialmente útil para mensagens de erro dinâmicas que podem ser exibidas em componentes front-end como toasts ou modals.
• Recuperar Conteúdo Multilíngue: Para aplicações que obtêm conteúdo de um banco de dados, a internacionalização garante que você possa servir esse conteúdo em múltiplos idiomas. Isso é crucial para plataformas como sites de e-commerce ou sistemas de gerenciamento de conteúdo que precisam exibir descrições de produtos, artigos e outros conteúdos no idioma preferido pelo usuário.
• Enviar Emails Multilíngues: Seja em emails transacionais, campanhas de marketing ou notificações, enviar emails no idioma do destinatário pode aumentar significativamente o engajamento e a eficácia.
• Notificações Push Multilíngues: Para aplicações móveis, enviar notificações push no idioma preferido do usuário pode melhorar a interação e retenção. Esse toque pessoal pode tornar as notificações mais relevantes e acionáveis.
• Outras Comunicações: Qualquer forma de comunicação do backend, como mensagens SMS, alertas do sistema ou atualizações da interface do usuário, se beneficia de estar no idioma do usuário, garantindo clareza e melhorando a experiência geral do usuário.

Ao internacionalizar o backend, sua aplicação não apenas respeita diferenças culturais, mas também se alinha melhor com as necessidades do mercado global, tornando-se um passo fundamental para escalar seus serviços mundialmente.

Começar

Veja Modelo de Aplicação no GitHub.

Instalação

Para começar a usar elysia-intlayer, instale o pacote usando npm:

npx intlayer init --interactive

a flag --interactive é opcional. Use intlayer-cli init se você for um agente de IA.

Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:

npm install intlayer elysia-intlayer

O Elysia tem como alvo o runtime Bun. O elysia-intlayer se apoia em AsyncLocalStorage (em vez da biblioteca cls-hooked usada pelos plugins Intlayer baseados em Node) justamente porque o Bun não implementa async_hooks.createHook.

Configuração

Configure as definições de internacionalização criando um arquivo intlayer.config.ts na raiz do seu projeto:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    /**
     * Locale padrão usada como fallback caso a locale solicitada não seja encontrada.
     */
    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({
      pt: "Exemplo de conteúdo retornado em português",
      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.

Configuração da Aplicação Elysia

Configure sua aplicação Elysia para usar elysia-intlayer:

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

const app = new Elysia()
  // Carregue o plugin de internacionalização
  .use(intlayer())
  // Rotas
  .get("/", ({ intlayer }) => ({
    // Locale usado para esta solicitação, negociado `Accept-Language` ou lido do armazenamento
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      pt: "Olá",
      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}`
);

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!.locale) — ou optional chaining — para satisfazer o TypeScript no modo strict.

O contexto da rota expõe:

Os mesmos helpers também são exportados de forma standalone. Eles resolvem a requisição atual através de AsyncLocalStorage, então você pode chamá-los sem desestruturar o contexto:

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({
      pt: "Exemplo de conteúdo retornado em português",
      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);

O contexto da request é libertado assim que a resposta é mapeada, para que os helpers autónomos nunca sejam resolvidos contra uma request já terminada. Quando chamados fora de uma request tratada pelo plugin, recorrem ao locale por omissão configurado.

Executar sua aplicação

Adicione os scripts do Intlayer ao seu package.json. O intlayer build compila suas declarações de conteúdo no diretório .intlayer e gera os tipos TypeScript:

{
  "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"
  }
}

Em seguida, inicie o servidor:

bun run dev

Teste a negociação de locale com 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"}

O intlayer build não é estritamente necessário antes de bun run src/index.ts: o plugin também prepara os dicionários quando a aplicação Elysia inicia. Executá-lo antecipadamente mantém os tipos gerados sincronizados para o seu editor e evita o custo do build na primeira requisição.

Compatibilidade

elysia-intlayer é totalmente compatível com:

• react-intlayer para aplicações React
• next-intlayer para aplicações Next.js
• vite-intlayer para aplicações Vite

Também funciona perfeitamente com qualquer solução de internacionalização em vários ambientes, incluindo navegadores e requisições de API.

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.

Você pode personalizar o cookie e o header usados para a detecção da locale:

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

const config: IntlayerConfig = {
  // ... Outras opções de configuração
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Para mais informações sobre configuração e tópicos avançados, visite nossa documentação.

Configurar TypeScript

elysia-intlayer aproveita as robustas capacidades do TypeScript para melhorar o processo de internacionalização. A tipagem estática do TypeScript garante que cada chave de tradução seja contabilizada, reduzindo o risco de traduções ausentes e melhorando a manutenibilidade.

Certifique-se de que os tipos gerados automaticamente (por padrão em ./types/intlayer.d.ts) sejam incluídos no seu arquivo tsconfig.json.

{
  // ... Suas configurações TypeScript existentes
  "include": [
    // ... Suas configurações TypeScript existentes
    ".intlayer/**/*.ts", // Inclua os tipos gerados automaticamente
  ],
}

Extensão VS Code

Para melhorar sua experiência de desenvolvimento com Intlayer, você pode instalar a Extensão Oficial Intlayer VS Code.

Instalar do VS Code Marketplace

Esta extensão fornece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Visualizações inline de conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções facilmente.

Para mais detalhes sobre como usar a extensão, consulte a documentação da Extensão Intlayer VS Code.

Configuração do Git

É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite fazer commit deles em seu repositório Git.

Para fazer isso, você pode adicionar as seguintes instruções ao seu arquivo .gitignore:

# Ignorar os arquivos gerados pelo Intlayer
.intlayer