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

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

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.
• Recuperação de Conteúdo Multilíngue: Para aplicações que extraem conteúdo de um banco de dados, a internacionalização garante que você possa fornecer esse conteúdo em vários idiomas. Isso é crucial para plataformas como sites de e-commerce ou sistemas de gestão de conteúdo que precisam exibir descrições de produtos, artigos e outros conteúdos no idioma preferido pelo usuário.
• Envio de E-mails Multilíngues: Seja para e-mails transacionais, campanhas de marketing ou notificações, enviar e-mails 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 aumentar a interação e a retenção. Esse toque pessoal pode fazer com que as notificações pareçam mais relevantes e acionáveis.
• Outras Comunicações: Qualquer forma de comunicação proveniente do backend, como mensagens SMS, alertas do sistema ou atualizações da interface do usuário, se beneficia por 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 as diferenças culturais, mas também se alinha melhor às necessidades do mercado global, tornando-se um passo-chave para escalar seus serviços mundialmente.

Primeiros Passos

Instalação

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

npm install intlayer fastify-intlayernpx intlayer init

Configuração

Configure as definições de internacionalização criando um 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_MEXICO,      Locales.SPANISH_SPAIN,    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Declare o seu conteúdo

Crie e gerencie as suas declarações de conteúdo para armazenar traduções:

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-ES": "Ejemplo de contenido devuelto en español (España)",      "es-MX": "Ejemplo de contenido devuelto en español (México)",    }),  },} satisfies Dictionary;export default indexContent;

As suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação desde que estejam incluídas no diretório contentDir (por padrão, ./src). E correspondam à extensão de ficheiro de declaração de conteúdo (por padrão, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Para mais detalhes, consulte a documentação de declaração de conteúdo.

Configuração da aplicação Fastify

Configure sua aplicação Fastify para usar fastify-intlayer:

import Fastify from "fastify";import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";import dictionaryExample from "./index.content";const fastify = Fastify({ logger: true });// Carregar plugin de internacionalizaçãoawait fastify.register(intlayer);// Rotasfastify.get("/t_example", async (_req, reply) => {  return t({    pt: "Exemplo de conteúdo retornado em inglês",    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)",  });});fastify.get("/getIntlayer_example", async (_req, reply) => {  return getIntlayer("index").exampleOfContent;});fastify.get("/getDictionary_example", async (_req, reply) => {  return getDictionary(dictionaryExample).exampleOfContent;});// Iniciar servidorconst start = async () => {  try {    await fastify.listen({ port: 3000 });  } catch (err) {    fastify.log.error(err);    process.exit(1);  }};start();

Compatibilidade

fastify-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. Você pode customizar o middleware para detectar o locale através de headers 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",  },};export default config;

Por padrão, fastify-intlayer interpretará o cabeçalho Accept-Language para determinar o idioma preferido do cliente.

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

Configurar TypeScript

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

Garanta que os tipos gerados automaticamente (por padrão em ./types/intlayer.d.ts) estejam incluídos no seu arquivo tsconfig.json.

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

Extensão do VS Code

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

Instalar no 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 do conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções com facilidade.

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

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que você os envie (commit) para o seu repositório Git.

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

# Ignorar os arquivos gerados pelo Intlayer.intlayer