@devix-tecnologia/directus-email-ptbr

Traduz para português brasileiro os e-mails que o Directus envia por conta própria: recuperação de senha, convite e confirmação de cadastro.

O problema, em duas metades

O corpo do e-mail vem de um template Liquid e basta sobrescrever. O assunto não: ele é fixado no código do Directus, em services/users.ts, e a rota POST /auth/password/request nunca preenche o parâmetro que o mudaria.

A issue #23839 pediu que o assunto fosse configurável e foi fechada como não planejada, remetendo à #8239, ainda aberta. O caminho suportado é o filtro email.send, acrescentado pela PR #23024 em julho de 2024. Ele roda antes do envio e o payload que devolve substitui o original.

Por isso o pacote entrega duas coisas de naturezas diferentes: uma extensão, para o assunto, e arquivos de template, para o corpo.

Instalação

pnpm add -D @devix-tecnologia/directus-email-ptbr

A extensão, que traduz o assunto

O Directus carrega extensões de EXTENSIONS_PATH e também descobre as instaladas como dependência. Numa imagem própria, a forma mais previsível é copiar:

COPY node_modules/@devix-tecnologia/directus-email-ptbr/dist \
     /directus/extensions/directus-email-ptbr/dist
COPY node_modules/@devix-tecnologia/directus-email-ptbr/package.json \
     /directus/extensions/directus-email-ptbr/package.json

Os templates, que traduzem o corpo

O Directus não descobre template de e-mail dentro de extensão. Template de e-mail não é um tipo de extensão — a documentação diz que eles "não estão incluídos no Extensions SDK". O Directus olha apenas o diretório de EMAIL_TEMPLATES_PATH e o interno da própria API, então os .liquid precisam ser entregues à parte:

COPY node_modules/@devix-tecnologia/directus-email-ptbr/templates /directus/templates

Em desenvolvimento, um volume resolve:

volumes:
  - ./node_modules/@devix-tecnologia/directus-email-ptbr/templates:/directus/templates:ro

As variáveis de ambiente que mandam nisso

| Variável | O que faz | Padrão | | --- | --- | --- | | EMAIL_TEMPLATES_PATH | Onde o Directus procura os .liquid | ./templates | | EXTENSIONS_PATH | Onde o Directus procura as extensões | ./extensions |

Os dois padrões são relativos ao diretório de trabalho, que na imagem oficial é /directus. Resolvem, portanto, para /directus/templates e /directus/extensions — que são exatamente os caminhos usados acima. Por isso nenhum dos exemplos precisa definir a variável: eles entregam os arquivos no lugar onde o Directus já procura. Declará-la só é necessário para colocar os templates em outro lugar.

Duas armadilhas, ambas silenciosas

Os .liquid não podem ficar em subpasta. A documentação é explícita: "these cannot go in a subdirectory". O Directus não varre recursivamente o diretório.

EMAIL_TEMPLATES_PATH=/directus/templates

/directus/templates/base.liquid            ✅ encontrado
/directus/templates/password-reset.liquid  ✅ encontrado
/directus/templates/ptbr/base.liquid       ❌ ignorado

Apontar a variável um nível acima tem o mesmo efeito. Montar os arquivos em /directus/templates/ e definir EMAIL_TEMPLATES_PATH=/directus faz o Directus procurar em /directus e não achar nada.

Nos dois casos não há erro: o Directus cai para os templates internos e o e-mail sai em inglês. Como a falha não aparece no log, a forma de conferir é disparar uma recuperação de senha e ler o que chega.

O que vem dentro

| Arquivo | Papel | | --- | --- | | src/hooks/email/assuntos.ts | Regra pura: nome do template para assunto. | | src/hooks/email/index.ts | Registra o filtro email.send e aplica a regra. | | src/templates/base.liquid | Layout do e-mail, traduzido. | | src/templates/password-reset.liquid | Corpo da recuperação de senha. |

Os assuntos não citam o nome do projeto, porque ele já viaja no remetente, que o Directus monta com o projectName. Assunto curto também é mais legível na caixa de entrada. Um template que o pacote não conhece passa intacto, com o assunto que o Directus escolheu — inclusive um template customizado do projeto.

O que o projeto ainda precisa configurar

Este pacote traduz o texto, mas a identidade continua sendo do projeto. O Directus tira nome, cor, logotipo e URL de directus_settings, e cai para "Directus", roxo e o logotipo dele quando estão vazios. Sem preencher isso, o e-mail sai traduzido mas falando "Directus".

| Campo | Efeito no e-mail | | --- | --- | | project_name | título, corpo, assinatura, rodapé e nome do remetente | | project_logo | as duas imagens, cabeçalho e assinatura | | project_color | fundo do quadrado do logotipo | | project_url | o link "Gerenciar minha conta" no rodapé |

O logotipo é buscado pelo cliente de e-mail de forma anônima, então o arquivo precisa ser legível sem autenticação, e o PUBLIC_URL precisa ser um endereço que o destinatário alcance.

Versão do Directus

O base.liquid é cópia do layout do Directus, traduzida. Isso é dívida assumida: numa atualização do Directus, o layout de lá pode mudar e este não acompanha sozinho.

A regra é a linha maior deste pacote acompanhar a do Directus, como o próprio SDK de extensões faz:

| Este pacote | Directus | | --- | --- | | 0.x / 1.x | 11.x |

O cabeçalho do base.liquid registra a versão exata de origem e a lista de trocas feitas. Ao subir o Directus: comparar com o base.liquid da versão nova e reaplicar.

Desenvolvimento

pnpm --filter @devix-tecnologia/directus-email-ptbr test       # regra pura
pnpm --filter @devix-tecnologia/directus-email-ptbr build      # dist/ + templates/
pnpm --filter @devix-tecnologia/directus-email-ptbr validate   # extensão válida