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

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

Casos de Uso Práticos

• Exibição de Erros do Backend no Idioma do Usuário: Quando ocorre um erro, 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 de front-end, como toasts ou modais.

• 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 servir esse conteúdo em vários 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 do usuário.

• Envio de E-mails Multilíngues: Seja para e-mails transacionais, campanhas de marketing ou notificações, o envio de 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, o envio de 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 do backend, como mensagens SMS, alertas do sistema ou atualizações da interface do usuário, beneficia-se 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 as diferenças culturais, mas também se alinha melhor às necessidades do mercado global, tornando-se um passo fundamental para escalar seus serviços em todo o mundo.

Primeiros Passos

See Application Template on GitHub.

Instalação

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

npm install intlayer adonis-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.RUSSIAN,
      Locales.JAPANESE,
      Locales.FRENCH,
      Locales.KOREAN,
      Locales.CHINESE,
      Locales.SPANISH,
      Locales.GERMAN,
      Locales.ARABIC,
      Locales.ITALIAN,
      Locales.ENGLISH_UNITED_KINGDOM,
      Locales.PORTUGUESE,
      Locales.HINDI,
      Locales.TURKISH,
      Locales.POLISH,
      Locales.INDONESIAN,
      Locales.VIETNAMESE,
      Locales.UKRAINIAN,
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Declarar Seu Conteúdo

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

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      pt: "Exemplo de conteúdo retornado em português",
      "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;

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 ou ./app) e correspondam à extensão de arquivo de declaração de conteúdo (por padrão, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

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

Configuração da Aplicação AdonisJS

Configure sua aplicação AdonisJS para usar o adonis-intlayer.

Registrar o middleware

Primeiro, você precisa registrar o middleware intlayer na sua aplicação.

router.use([() => import("adonis-intlayer/middleware")]);

Definir suas rotas

import router from "@adonisjs/core/services/router";import { t, getIntlayer, getDictionary } from "adonis-intlayer";import indexContent from "../app/index.content";router.get("/t_example", async () => {  return t({    en: "Example of returned content in English",    fr: "Exemple de contenu renvoyé en français",    pt: "Exemplo de conteúdo retornado em português",    "es-ES": "Ejemplo de contenido devuelto en español (España)",    "es-MX": "Ejemplo de contenido devuelto en español (México)",  });});router.get("/getIntlayer_example", async () => {  return getIntlayer("index").exampleOfContent;});router.get("/getDictionary_example", async () => {  return getDictionary(indexContent).exampleOfContent;});

Funções

O adonis-intlayer exporta várias funções para lidar com a internacionalização na sua aplicação:

• t(content, locale?): Função básica de tradução.
• getIntlayer(key, locale?): Recupera o conteúdo por chave dos seus dicionários.
• getDictionary(dictionary, locale?): Recupera o conteúdo de um objeto de dicionário específico.
• getLocale(): Recupera a localidade atual do contexto da requisição.

Uso em Controllers

import type { HttpContext } from "@adonisjs/core/http";import { t } from "adonis-intlayer";export default class ExampleController {  async index({ response }: HttpContext) {    return response.send(      t({        en: "Hello from controller",        fr: "Bonjour depuis le contrôleur",        pt: "Olá do controlador",      })    );  }}

Compatibilidade

O adonis-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 personalizar o middleware para detectar a localidade por meio 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",  },};export default config;

Por padrão, o adonis-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

O adonis-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 contabilizada, reduzindo o risco de traduções ausentes e melhorando a manutenibilidade.

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

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

Extensão para VS Code

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

Instalar a partir do VS Code Marketplace

Esta extensão oferece:

• 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 do Intlayer para VS Code.

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite commitá-los no 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