Como construir um site institucional: notas sobre o nosso próprio site

O site de uma empresa de software é o primeiro software que a empresa escreve. Quem o visita não vê o código, mas vê o resultado. Se a página demora a abrir, se ficou uma frase em turco noutra língua, se o formulário de contacto falha em silêncio, o visitante atribui isso ao trabalho da empresa.

Por isso, construímos o site não como uma brochura, mas como um pequeno produto. Escrevo abaixo que decisões tomámos, porquê, e onde nos enganámos.

Geração estática

O site foi escrito com Next.js. Na primeira versão, as páginas eram geradas de novo no servidor a cada pedido. A causa era uma linha inocente: o layout raiz lia o cabeçalho do pedido para descobrir a língua. O Next considera dinâmica qualquer página onde vê isso.

O resultado era que a Cloudflare não conseguia guardar nenhuma página em cache. Cada visita ia até ao servidor na Hetzner. Medido localmente, o tempo até ao primeiro byte era de poucos milissegundos. Ou seja, o código não era lento. O problema ia surgir com a escala.

A solução foi deduzir a língua a partir do endereço e não do pedido. Cada língua tem o seu próprio layout raiz, e a língua fica clara pela pasta onde a página está. Hoje, todas as cerca de trezentas páginas são geradas uma única vez, durante a compilação.

Sete línguas e coerência

O site está publicado em turco, inglês, francês, português, alemão, espanhol e árabe. A tradução em si é a parte fácil. O difícil é que, quando um texto muda, mude em sete sítios ao mesmo tempo.

A maioria dos erros que encontrámos nas primeiras revisões vinha do mesmo padrão. Uma longa cadeia de condições que escolhia o texto conforme a língua caía em silêncio no último ramo quando se esquecia de uma língua. E o último ramo era quase sempre o turco. Era assim que aparecia uma frase em turco a meio de uma página em francês.

Resolvemos isto com uma função auxiliar. Qualquer sítio que escolha um texto tem de fornecer as sete línguas de uma vez. Se faltar uma, o código não compila. O erro é apanhado antes de chegar à produção.

Os títulos académicos eram um problema parecido. Numa tradução, o título «Doç. Dr.» tinha-se transformado em professor catedrático. Agora o título não é traduzido em nenhuma língua. Vem do registo em turco, e um teste verifica isso a cada push.

Testes

Não montámos uma framework de testes pesada. Escrevemos nove testes com o módulo de testes do próprio Node. Cada um apanha um erro que já nos aconteceu de verdade.

Entre eles: o título manter-se igual em todas as línguas, não haver travessões longos em nenhum texto, o nome da marca não ser traduzido, cada artigo em turco ter equivalente nas outras seis línguas e os textos jurídicos não serem resumidos na tradução. O último teste é grosseiro, mas funciona: se a página jurídica numa língua for mais curta do que sessenta por cento da versão turca, é muito provável que tenha sido resumida.

A cada push para o GitHub correm a verificação de tipos, o lint, estes testes e a compilação de produção. Se algum falhar, a versão não vai para produção.

Segurança

A política de segurança de conteúdo é rigorosa. Não se pode carregar nenhum script, tipo de letra ou imagem de um domínio externo. Os tipos de letra vêm do nosso próprio servidor. Assim, o navegador do visitante não envia pedidos a terceiros ao abrir a página. O Google Analytics só é carregado se o visitante der consentimento.

O ecrã do protocolo de trabalho na página inicial envia a um modelo de linguagem o texto que o visitante escreve. É o ponto do site mais fácil de usar de forma abusiva. Alguém que queira usar de graça um modelo pago pode chamar diretamente o endpoint. Impedimos isso com várias camadas: a verificação de que o pedido vem da nossa página, um bilhete assinado de curta duração e utilização única, um limite por hora e por dia para cada endereço, um teto diário para o site inteiro e um limite para o número de pedidos que podem ir ao modelo em simultâneo.

Implementação

O código está no GitHub. No servidor da Hetzner corre o Coolify, que a cada push para o ramo principal volta a compilar o site como imagem Docker e o coloca em produção. Uma implementação demora cerca de dois minutos e meio.

À frente está a Cloudflare. Com a passagem para a geração estática, também o HTML passou a poder ficar em cache, e as páginas ficam lá guardadas até uma hora.

Onde nos enganámos

A cache foi a fonte da velocidade, mas também de um equívoco. Pusemos uma nova versão em produção, o Coolify disse que tinha corrido bem, mas a página inicial continuava a aparecer na versão antiga. A causa era simples. A Cloudflare não pedia a cópia nova enquanto a que tinha não expirasse.

A solução certa é limpar a cache automaticamente no fim de cada implementação. O processo de publicação só está concluído quando termina no sítio que o visitante vê, e não apenas no servidor.

Há também a acessibilidade. A análise automática não encontrava erros nas páginas. Mas as pequenas etiquetas da página inicial estavam sobre uma fotografia semitransparente, e a ferramenta de análise não consegue medir o contraste sobre uma fotografia. Medimos à parte os píxeis por trás das etiquetas e o rácio rondava 3:1. Depois de esbater um pouco a fotografia e escurecer as etiquetas um tom, passou acima de 5:1. Mesmo quando a ferramenta diz «sem erros», é preciso olhar.

Porque contamos isto

É fácil dizer a um cliente «entregamos software que funciona». Quando escrevemos abertamente o que fizemos neste site, também se torna fácil ver em que se apoia essa frase.