Internacionalização de Backend (i18n) no Express usando Intlayer

Olá, pessoal!

Recentemente, precisei adicionar suporte multilíngue a uma API baseada em Express. Decidi compartilhar um breve tutorial para quem estiver interessado em fazer com que seu backend responda com conteúdo traduzido dependendo do idioma preferido do usuário.

Por Que Internacionalizar Seu Backend?

Aqui estão alguns casos de uso práticos para a internacionalização do backend:

- Exibir Erros do Backend no Idioma do Usuário: Mostre mensagens de erro no idioma nativo do usuário para melhorar a compreensão e reduzir a frustração. Isso permite que os erros sejam exibidos diretamente em um toast sem a necessidade de mapeá-los no frontend.

- Enviar Emails, Notificações Push, etc., Multilíngues: Aumente o engajamento enviando emails transacionais, de marketing ou notificações no idioma do destinatário. Localize notificações push, mensagens SMS para garantir clareza e melhorar a experiência do usuário.

- Recuperar Conteúdo Multilíngue: Sirva conteúdo do seu banco de dados em vários idiomas.

Começando

Instalação

Primeiro, instale os pacotes necessários usando seu gerenciador de pacotes preferido:

npm install intlayer express-intlayer

### Configuração

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

// intlayer.config.ts
import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
internationalization: {
  locales: [
    Locales.ENGLISH,
    Locales.FRENCH,
    Locales.SPANISH_MEXICO,
    Locales.SPANISH_SPAIN,
  ],
  defaultLocale: Locales.ENGLISH,
},
};

export default config;

Configuração da Aplicação Express

Agora, configure sua aplicação Express para usar o express-intlayer:

// src/index.ts
import express, { type Express } from "express";
import { intlayer, t } from "express-intlayer";

const app: Express = express();

// Carrega o manipulador de requisições de internacionalização
app.use(intlayer());

// Rotas
app.get("/", (_req, res) => {
res.send(
  t({
    en: "Example of returned content in English",
    fr: "Exemple de contenu renvoyé en français",
    "es-ES": "Ejemplo de contenido devuelto en español (España)",
    "es-MX": "Ejemplo de contenido devuelto en español (México)",
  })
);
});

// Inicia o servidor
app.listen(3000);

Compatibilidade

O express-intlayer funciona perfeitamente com react-intlayer ou next-intlayer. Além disso, é compatível com várias soluções de internacionalização.

Personalizando a Detecção de Local

Por padrão, o express-intlayer usa o cabeçalho Accept-Language para determinar o idioma preferido do cliente. Você pode personalizar esse comportamento para detectar locais através de cabeçalhos ou cookies:

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

const config: IntlayerConfig = {
// Outras opções de configuração
middleware: {
  headerName: "my-locale-header",
  cookieName: "my-locale-cookie",
},
};

Sinta-se à vontade para conferir a documentação oficial para configurações e recursos mais avançados, bem como o site oficial da solução.