TCDEV Blog

Deixe seu LLM pensar em inglês

2026-04-27T00:00:00Z

Você envia um chatbot para a sua equipa alemã. A interface do usuário é alemã. Os documentos de origem são parcialmente em alemão e parcialmente em inglês. As ferramentas por detrás do assistente esperam valores de enum em inglês, descrições de funções em inglês, nomes de produtos em inglês, tudo em inglês.

Depois, alguém faz uma pergunta perfeitamente normal em alemão, o modelo escolhe a ferramenta correta, passa um argumento em alemão em vez de inglês e tudo se desmorona silenciosamente.

Já vi versões disto vezes suficientes e já não penso nisto como um problema de tradução. **É um problema de execução.

O meu padrão atual é simples: deixar os utilizadores falarem a língua que quiserem, mas deixar o LLM fazer a sua recuperação, raciocínio e trabalho de ferramenta em inglês sempre que a fiabilidade for realmente importante. Depois, localizar a resposta fora desse ciclo.

Isto parece um pouco herético à primeira vista. Mas é também, na minha opinião, a coisa mais prática que se pode fazer neste momento.

A pesquisa está a começar a dizer isto em voz alta

Os números já não são subtis.

No [MASSIVE-Agents benchmark] (https://aclanthology.org/2025.findings-emnlp.1099/), os investigadores avaliaram a chamada de funções multilingues em 52 línguas, 47.020 amostras e 21 modelos. A melhor pontuação média em todas as línguas foi de apenas 34,05%. O inglês atingiu 57,37%. O amárico desceu para 6,81%.

Isto não é uma pequena oscilação de qualidade. É um abismo de fiabilidade.

Depois, há o [Lost in Execution] (https://arxiv.org/abs/2601.05366), que se aproxima ainda mais do problema dos sistemas reais. O documento mostra que muitas falhas na chamada de ferramentas multilingues acontecem depois de o modelo já ter compreendido a intenção e selecionado a ferramenta correta. A questão dominante era a incompatibilidade linguística do valor dos parâmetros. Em termos simples, o modelo sabia o que fazer, mas expressou os bits executáveis na língua do utilizador em vez da língua da interface, pelo que a chamada falhou na mesma.

E isto não se limita à chamada de ferramentas. Em [Do Multilingual Language Models Think Better in English?] (https://aclanthology.org/2024.naacl-short.46/), Etxaniz e colegas descobriram que a auto-tradução para inglês superava consistentemente a inferência direta em língua não inglesa em cinco tarefas. A sua formulação é refrescantemente direta: os modelos são "incapazes de aproveitar todo o seu potencial multilingue quando solicitados em línguas que não o inglês".

Portanto, sim, os modelos multilingues são impressionantes. Mas se a sua fasquia não for "soa muito bem" mas sim "deve comportar-se corretamente na produção", o inglês continua a parecer a língua de trabalho mais segura com uma frequência notável.

Porque é que o RAG quebra no mesmo sítio

As pessoas normalmente ouvem este argumento e pensam primeiro em agentes. Chamada de função, saída estruturada, execução de API, esse tipo de coisa.

O RAG tem a mesma fraqueza, apenas uma camada antes.

Se a sua camada de recuperação tiver de fazer corresponder a fraseologia local de um utilizador ao conteúdo escrito em idiomas mistos, com terminologia inconsistente, nomes de produtos traduzidos e etiquetas de taxonomia semi-localizadas, cria mais hipóteses de o sistema se desviar antes mesmo de a geração começar. Honestamente, é daqui que vêm muitas das queixas "o modelo não é fiável". O modelo pode ser bom. A interface de conteúdo não é.

Eu prefiro normalizar cedo.

Traduzir a pergunta para inglês. Recuperar a partir de um corpus canónico inglês. Deixar o modelo raciocinar sobre uma camada terminológica estável. Gerar um rascunho de resposta em inglês, se necessário. Em seguida, traduzir ou localizar a resposta final para o utilizador.

Isto dá-lhe um local onde a nomenclatura se mantém estável:

um título de documento canónico
um vocabulário de produto canónico
um esquema de ferramenta canónico
um conjunto canónico de etiquetas de recuperação

Continua a ser possível suportar todas as línguas do utilizador no exterior. Basta deixar de exigir que o percurso de execução principal seja perfeitamente multilingue em cada etapa.

Isto não é anti-localização

Muito pelo contrário.

Uma má arquitetura de IA multilingue prejudica normalmente os utilizadores locais em primeiro lugar. Estes obtêm uma interface localizada agradável, mas depois o sistema oculto centrado no inglês comporta-se de forma inconsistente e fá-los pagar o preço.

Uma localização correta significa ser honesto sobre onde a linguagem deve ser flexível e onde não deve.

Para mim, a divisão é a seguinte:

Localizar a interface do utilizador, os avisos, o texto de ajuda, a integração e as respostas finais.
Localizar o conteúdo de origem que as pessoas lêem diretamente quando esse conteúdo tem de existir no mercado.
Mantenha as definições internas da ferramenta, os identificadores canónicos, as etiquetas de recuperação e os pivôs de raciocínio em inglês, se essa for a camada mais estável.
Adicionar pós-processamento explícito ou revisão humana quando um resultado localizado tiver peso legal, regulamentar ou contratual.

Este último ponto é mais importante do que as equipas gostam de admitir. Se o modelo estiver a falar com um ser humano, a localização é uma decisão de experiência do utilizador. Se o modelo está a falar com outro sistema, a linguagem é um contrato de interface.

Não são a mesma coisa.

A arquitetura em que mais confio neste momento

Esta é a versão em que eu apostaria atualmente para produtos de IA multilingues:

O utilizador pergunta na sua língua.
O sistema traduz ou normaliza o pedido para inglês.
A recuperação, o raciocínio, a classificação e as chamadas de ferramentas ocorrem em relação aos dados canónicos em inglês.
A resposta final é localizada de volta para a língua do utilizador.
Os resultados de alto risco recebem uma etapa de validação adicional antes de saírem do sistema.

Não é filosoficamente puro. É operacionalmente sensato.

O que é bom é que a investigação recente aponta na mesma direção. A [Lost in Execution] (https://arxiv.org/abs/2601.05366) descobriu que a pré-tradução das consultas dos utilizadores reduzia geralmente os erros de incompatibilidade linguística melhor do que as correcções post-hoc, mesmo que ainda não recuperasse totalmente o desempenho ao nível do inglês. Isto corresponde ao que muitos construtores já suspeitam na prática. Se esperar até ao fim para eliminar as incoerências multilingues, normalmente é demasiado tarde.

E sim, há excepções. Se estiver a construir para línguas com poucos recursos, para uma linguagem específica de um domínio ou para um fraseado culturalmente dependente, traduzir tudo para inglês pode introduzir desvios. O documento acima referido alerta explicitamente para esse facto. Por isso, não transforme isto num dogma.

Mas como padrão para co-pilotos de empresas, assistentes internos, RAG multilingues e agentes utilizadores de ferramentas, penso que a regra se mantém surpreendentemente bem.

O que isto significa para o Rasepi

É exatamente por isto que me preocupo tanto com a estrutura canónica do conteúdo.

Se a sua base de conhecimento tiver uma camada de fonte limpa, terminologia estável e localização controlada no topo, a IA torna-se mais fácil de confiar. Se cada versão linguística se desviar independentemente dentro do caminho de execução, está a pedir ao modelo para improvisar onde o seu sistema deve ser preciso.

Toda a abordagem do Rasepi é construída em torno de separar essas preocupações de forma limpa. Manter um núcleo canónico. Localizar deliberadamente. Rastrear onde existem variantes. Não finja que todas as camadas da pilha devem ser igualmente multilíngues só porque a interface do usuário é.

Eu costumava pensar que a melhor experiência de IA multilingue significava "fazer tudo na língua do utilizador". Já não penso assim. Não para sistemas que têm de obter o parágrafo certo, escolher a ferramenta certa e devolver algo em que se possa confiar.

A regra prática é simples: os utilizadores devem permanecer locais, mas o caminho de execução do LLM deve permanecer estável. Atualmente, isso significa geralmente inglês no meio e localização nas extremidades.

Isso vai mudar com o tempo. Espero que mude rapidamente. Mas, se estiver a fazer envios hoje e a fiabilidade for mais importante do que a estética, eu deixaria o modelo pensar em inglês e deixaria o seu produto falar a língua do utilizador.

Claude Design e a agência criativa de uma pessoa só

2026-04-18T00:00:00Z

Ontem, a Anthropic lançou o Claude Design, um novo produto da sua equipa Anthropic Labs que lhe permite criar designs, protótipos, apresentações e material de marketing falando com o Claude. E eu fiquei ali sentado a olhar para o anúncio a pensar: ok, então agora uma pessoa com uma subscrição do Claude tem genuinamente a maior parte do que uma pequena agência criativa oferece. Design. Código. Automatização. Apresentações. Consistência da marca. Tudo dentro do mesmo ecossistema.

Esta é uma frase louca para escrever em 2026. Mas não acho que seja um exagero.

O que o Claude Design realmente faz

A versão curta: você descreve o que precisa e o Claude cria uma primeira versão. Depois, refina-se através de conversas, comentários inline, edições diretas ou sliders personalizados que o Claude gera para si. É alimentado por Opus 4.7 e é surpreendentemente bom a manter a consistência visual.

Mas a funcionalidade que mais me chamou a atenção foi o onboarding. Durante a configuração, o Claude lê a sua base de código e os ficheiros de design existentes para criar um sistema de design para a sua equipa. Cores, tipografia, componentes. A partir daí, todos os projectos seguem automaticamente a sua marca. Pode importar imagens, documentos (DOCX, PPTX, XLSX) ou apontar diretamente para a sua base de código. Existe uma ferramenta de captura da Web que recolhe elementos do seu sítio Web ativo para que os protótipos se assemelhem ao produto real.

Tem uma maquete do Figma que pretende utilizar? Exporte-o, coloque-o no Claude Design e inicie uma conversa sobre o que deve ser alterado. Ou simplesmente capture o seu site existente e diga "aumente a secção de heróis e adicione um carrossel de testemunhos". Esse tipo de coisas.

Os testemunhos do anúncio são reveladores. O designer de produto sénior da Brilliant disse que as suas páginas mais complexas, que precisavam de [mais de 20 prompts para recriar noutras ferramentas, apenas precisavam de 2 prompts no Claude Design] (https://www.anthropic.com/news/claude-design-anthropic-labs). O Gestor de Produto da Datadog descreveu a passagem de uma ideia aproximada para um protótipo funcional antes de qualquer pessoa sair da sala, e disse que o que costumava demorar uma semana de briefings, maquetas e rondas de revisão, agora acontece numa única conversa.

Uma semana de idas e vindas, resumida numa só conversa. Pensem nisso por um segundo.

A pilha que muda tudo

É aqui que as coisas ficam interessantes. O Claude Design não existe isoladamente. A Anthropic tem agora três produtos que, combinados, cobrem uma quantidade absurda de terreno:

Claude Code: Escrever, rever e enviar software real. [2,5 mil milhões de dólares em receitas correntes] (https://www.anthropic.com/news/anthropic-raises-30-billion-series-g-funding-380-billion-post-money-valuation) a partir de fevereiro, responsável por cerca de 4% de todos os commits públicos do GitHub em todo o mundo.
Cowork**: Automatizar o trabalho do conhecimento. Investigação, análise, processamento de documentos, tarefas recorrentes a partir do seu ambiente de trabalho.
Claude Design: Criar trabalho visual. Protótipos, apresentações, material de marketing, activos consistentes com a marca.

E eles trocam de mãos. Quando um design está pronto para ser criado, o Claude agrupa tudo num pacote de transferência que pode passar para o Claude Code com uma única instrução. Do design à produção num único fluxo. Sem ticket do Jira. Sem reunião de transferência. Nada de "você pode me enviar as especificações no Slack".

Não paro de pensar na previsão de Sam Altman, do início de 2024, sobre [a empresa de uma pessoa que vale bilhões de dólares] (https://every.to/napkin-math/the-one-person-billion-dollar-company). Na altura, parecia uma aspiração, talvez um pouco hiperbólica. As ferramentas ainda não estavam disponíveis. Era possível gerar texto e imagens, é certo, mas a distância entre gerar coisas e enviar produtos reais era enorme.

Essa distância está a diminuir rapidamente.

O que eu teria dado por isto há dois meses

Quando construí o Rasepi, o sítio de marketing era uma das partes mais aborrecidas. Não era o código. O código era bom, o Claude lida com HTML e CSS como um campeão. Mas as decisões de design visual? A disposição dos heróis, os cartões da página de preços, as tabelas de comparação de caraterísticas? Eu descrevia as coisas por palavras, o Claude produzia algo e depois eu passava horas a tentar ajustar o espaçamento, as cores, a tipografia. Tudo através de mensagens de texto. Não havia um ciclo de feedback visual.

Com o Claude Design, esse fluxo de trabalho passa a ser: "Aqui está o meu site" (captura da web), "redesenhar a secção de preços para enfatizar o plano da equipa" (conversa), ajustar a cor verde com uma barra deslizante, aprovar, entregar ao Claude Code para implementação. Calculo que isso me teria poupado um fim de semana inteiro.

(Honestamente, estou um pouco aborrecido por não ter sido lançado dois meses antes).

E a exportação do Canva é inteligente. O Canva tem 220 milhões de utilizadores activos e uma receita anual de 3 mil milhões de dólares. O Anthropic não está a tentar substituir o Canva. Está a tentar ser o local onde as ideias começam antes de aterrarem no Canva para polimento e distribuição final. Essa é uma jogada de posicionamento inteligente. A criatividade é gerada no Claude Design e depois exportada para o Canva, onde a sua equipa de marketing a recolhe. Ou exporta para o PPTX para aquele deck de investidores. Ou exportar como HTML autónomo para uma página de destino.

O multiplicador "basta adicionar ferramentas

Este é o padrão que continuo a ver no espaço da IA em 2026. O modelo de base fica mais inteligente, é certo, mas o verdadeiro salto de produtividade vem da ligação de ferramentas entre si. O Claude, por si só, é um gerador de texto muito inteligente. O Claude com o Code é um engenheiro de software. O Claude com Cowork é um analista de investigação. O Claude com Design é um diretor criativo. O Claude com os três? Isso é uma pequena agência.

E as ligações continuam a aumentar. A Anthropic afirmou que irá adicionar mais integrações nas próximas semanas. Os servidores MCP já permitem ligar o Claude a ferramentas e fontes de dados externas. O ecossistema está a construir-se a si próprio.

Para fundadores individuais, freelancers e pequenas equipas, isto muda completamente o cálculo. Não é necessário contratar um designer para produzir decks e protótipos com aspeto profissional. Não precisa de um programador de front-end separado para transformar as maquetas em código. Não precisa de um gestor de projeto para coordenar a transferência entre o design e a engenharia, porque não há transferência. É uma conversa contínua.

Não estou a dizer que os designers são obsoletos. Longe disso. A Brilliant e a Datadog descreveram os seus designers utilizando o Claude Design. A ferramenta torna os bons designers mais rápidos e dá a todos os outros acesso a resultados visuais competentes. Isso é diferente de substituir pessoas.

O que isto significa para os produtos de documentação

Esta é uma questão que estou a observar de perto. Na Rasepi, estamos a construir uma plataforma de documentação onde a qualidade visual é importante. As páginas de entrada precisam de ter bom aspeto. Os guias de início rápido precisam de diagramas claros. Os documentos de marketing precisam de consistência de marca entre línguas e equipas.

Um mundo onde cada membro da equipa pode gerar documentação visual de acordo com a marca, entregá-la ao motor de tradução e distribuí-la em sete línguas sem tocar no Figma, no Photoshop ou no InDesign? É exatamente esse o problema que estamos a resolver de um ângulo diferente. (E sim, este é exatamente o tipo de fluxo de trabalho que o Rasepi foi concebido para suportar).

A parte em que fica estranhamente caro

Aqui está a coisa de que ninguém está a falar ainda. Criei uma nova conta Anthropic especificamente para experimentar o Claude Design. Uma conta nova, sem histórico, sem utilização anterior. Importei um pequeno ficheiro Figma e gerei um único ativo. Foi só isso. Duas operações. E fiquei sem créditos.

Numa conta totalmente nova. Com uma nova dotação.

Não sei como é a matemática dos tokens do lado do Anthropic quando o Opus 4.7 está a fazer a geração visual, mas seja o que for, queima créditos a um ritmo que faz com que a ideia de "agência criativa de uma só pessoa" pareça muito mais cara do que o esperado. Se importar um pequeno modelo Figma e produzir uma imagem consome todo o seu orçamento, a economia da utilização desta ferramenta de design diária ainda não funciona.

Para ser justo, esta é uma pré-visualização de investigação e os preços irão provavelmente mudar. Mas, neste momento, existe uma diferença significativa entre a promessa (substituir o seu fluxo de trabalho de design) e a realidade (pode ficar sem créditos antes do almoço). Os ganhos de produtividade são reais. Se o rácio de créditos por produção o torna prático para uma utilização regular é uma questão completamente diferente.

A advertência honesta

O Claude Design está em fase de pesquisa prévia. Terá algumas arestas. Os testemunhos são de equipas de design de empresas bem financiadas com sistemas de design estabelecidos. A sua quilometragem pode variar, especialmente se estiver a começar do zero, sem diretrizes de marca para o alimentar.

Mas a trajetória é clara. Há dezoito meses, era necessário um designer, um programador e um gestor de projectos para passar do conceito à página de destino enviada. Hoje em dia, uma única pessoa com uma subscrição Claude pode fazer uma versão surpreendentemente credível desse mesmo fluxo de trabalho numa tarde.

Ainda não chegámos à empresa de mil milhões de dólares com uma só pessoa. Mas a agência criativa de uma só pessoa? Acho que acabámos de chegar.

Uma chave de API, muitos inquilinos: Como isolamos as traduções de DeepL entre os clientes

2026-04-18T00:00:00Z

Há uma pergunta que surge sempre que explico a arquitetura de tradução do Rasepi a outro programador: "Espera, então todos os teus inquilinos partilham uma chave de API DeepL? Como é que evita que os seus glossários e regras de estilo se infiltrem uns nos outros?"

É uma pergunta justa. E a resposta envolve mais trabalho de design do que seria de esperar.

Cobrimos a linha de tradução completa num post anterior, o hashing ao nível do bloco, o orquestrador, todo o fluxo desde a gravação do documento até à saída traduzida. Este post aborda o problema específico de multi-tenancy. Como se pega numa API de terceiros que não tem qualquer conceito de inquilinos e se constrói o isolamento de inquilinos em cima dela.

O problema: DeepL não sabe sobre seus clientes

A API do DeepL é autenticada com uma única chave de API. Tudo o que é criado com essa chave, glossários, listas de regras de estilo, histórico de tradução, pertence à mesma conta. Não há nenhum conceito de "este glossário pertence ao inquilino A" no lado do DeepL.

Quando se chama GET /v2/glossaries, obtém-se todos os glossários de todos os inquilinos. Quando se cria uma lista de regras de estilo, ela vive no mesmo espaço de nomes que as regras de estilo de todos os outros locatários. A API é plana.

Para um produto auto-hospedado em que cada cliente executa a sua própria instância com a sua própria chave DeepL, isto é ótimo. Para um SaaS multi-tenant em que gerimos a infraestrutura? É necessária uma camada de isolamento.

A base de dados é a fonte da verdade

A nossa principal decisão de conceção: **a base de dados possui todo o conteúdo do glossário e a configuração das regras de estilo. DeepL é um alvo de execução em tempo de execução, nada mais.

Todas as entidades TenantGlossary e TenantStyleRuleList implementam ITenantScoped, o que significa que os filtros de consulta global do EF Core automaticamente abrangem todas as leituras para o locatário atual. Uma consulta de glossários no contexto de solicitação do locatário A nunca retornará as entradas do locatário B. Este é o mesmo padrão de isolamento que usamos em todo o Rasepi, aplicado ao nível do ORM.

O que torna isto interessante é o seguinte. Quando um locatário edita um termo do glossário, não chamamos imediatamente DeepL. Actualizamos a linha da base de dados e definimos IsDirty = true. É só isso. O glossário DeepL real é criado (ou recriado) preguiçosamente, mesmo antes de a próxima tradução precisar dele.

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage);

    if (glossary?.Entries.Count == 0) return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty: delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var created = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = created.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync();

    return glossary.DeepLGlossaryId;
}

O filtro de consulta em TenantGlossaries faz o isolamento. O sinalizador IsDirty faz a sincronização preguiçosa. E a convenção de nomenclatura (rasepi-{glossary.Id}) é apenas para depuração no painel DeepL, não tem qualquer objetivo funcional.

Porquê preguiçosa? Porque os glossários de DeepL v2 são imutáveis. Não é possível editá-los. Qualquer alteração significa apagar e recriar. Se uma equipa importar um CSV com 200 termos e depois corrigir um erro de digitação numa entrada, não queremos apagar e recriar o glossário DeepL duas vezes. Basta definir IsDirty em ambas as vezes e a única recriação acontece quando a próxima tradução for executada.

Regras de estilo: mesmo padrão, API diferente

As regras de estilo do DeepL são mais novas (API v3) e realmente mutáveis, o que é melhor. Você pode atualizar regras configuradas no lugar com PUT /v3/style_rules/{style_id}/configured_rules, e instruções personalizadas podem ser adicionadas ou removidas individualmente.

Nós ainda usamos o mesmo padrão IsDirty. Um TenantStyleRuleList tem um DeepLStyleId que mapeia para o identificador de tempo de execução de DeepL, mais ConfiguredRulesJson para as regras de formatação e uma coleção de entradas TenantCustomInstruction para diretivas de tradução de texto livre.

O verdadeiro poder está nessas instruções personalizadas. Cada uma é uma diretiva de linguagem simples, até 300 caracteres, que molda a forma como DeepL traduz. Exemplos reais dos nossos inquilinos:

"Utilize sempre a forma 'Sie', nunca 'du'" para uma firma de advogados alemã
"Traduzir 'deployment' como 'Bereitstellung', nunca 'Deployment'" para termos dependentes do contexto que vão para além de simples mapeamentos de glossários
"Utilizar a ortografia do inglês britânico (cor, organização, licença)" para uma empresa do Reino Unido que esteja a traduzir entre variantes do inglês
"Colocar símbolos de moeda após o valor numérico" para convenções europeias

Cada locatário pode ter instruções completamente diferentes por língua de destino, todas elas com a mesma chave API. O isolamento resulta do facto de cada chamada de tradução incluir apenas o glossary_id e o style_id pertencentes ao locatário requerente. Os recursos DeepL de outros locatários nunca são referenciados.

A chamada de tradução: tudo compõe

Quando o orquestrador traduz um bloco, ele reúne todas as configurações específicas do locatário em uma única solicitação:

var glossaryId = await _glossaryService
    .GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang);
var styleId = await _styleRuleService
    .GetOrSyncStyleIdAsync(targetLang);
var formality = langConfig.Formality ?? "default";

var options = new TranslationOptions
{
    GlossaryId = glossaryId,
    StyleId = styleId,
    Formality = formality,
    Context = documentContext,
    ModelType = styleId != null ? "quality_optimized" : null
};

Todos os parâmetros aqui são específicos do locatário. O glossaryId foi resolvido por meio de uma consulta filtrada por locatário. O styleId foi resolvido da mesma forma. O formality provém do TenantLanguageConfig, também com escopo de locatário. Mesmo o context (parágrafos envolventes enviados para melhorar a qualidade da tradução, não facturados) provém do próprio documento do locatário.

Um aspeto que quero realçar: quando style_id é definido, DeepL utiliza automaticamente o seu modelo quality_optimized. Não é possível combinar regras de estilo com latency_optimized. Essa é uma restrição do DeepL, mas honestamente uma restrição razoável. Se está a investir em regras de estilo personalizadas, provavelmente quer a melhor qualidade de saída.

Caching a nível de bloco: a base de dados como memória de tradução

Nós não chamamos DeepL para blocos que não foram alterados. O mecanismo de cache é a própria tabela TranslationBlock.

Cada EntryBlock de origem tem um ContentHash, um SHA256 do seu conteúdo semântico (com atributos de metadados como blockId e deleted eliminados). Cada TranslationBlock armazena o SourceContentHash que estava atual quando a tradução foi feita. Quando o bloco de origem muda, seu hash muda. O orquestrador compara os hashes e só coloca em fila os blocos com incompatibilidades.

A árvore de decisão para cada bloco se parece com isso:

Hash corresponde, existe tradução = ignorar (em cache, atualizado)
Hash alterado, tradução automática, não bloqueado = retraduzir automaticamente
Hash alterado, editado por humanos ou bloqueado = marcar como obsoleto, não sobrescrever

Este terceiro caso é crucial. Se o seu tradutor de alemão tiver refinado manualmente um parágrafo, não o apagamos só porque a fonte inglesa mudou. Marcamo-lo como obsoleto para que ele saiba que precisa de ser revisto, mas o texto traduzido permanece intacto.

O resultado prático: a edição de um parágrafo num documento de 30 parágrafos desencadeia exatamente uma chamada à API DeepL (bem, um lote que inclui um bloco). Os outros 29 parágrafos, em todas as línguas, já estão armazenados em cache e não custam nada.

Porque não usar uma chave separada por inquilino?

Pensei seriamente nisso. Dar a cada inquilino a sua própria chave API DeepL, eliminando completamente o problema de isolamento.

Três razões para não o fazermos:

Complexidade de faturação Cada inquilino precisaria da sua própria subscrição de DeepL ou de uma forma de fornecer subcontas. O DeepL não oferece gestão de chaves multi-tenant nativamente.
**Eficiência de custos: Infraestrutura partilhada significa limites de taxas e descontos por volume partilhados. A nossa utilização agregada obtém melhores preços.
**Simplicidade operacional: uma chave para rodar, uma quota para monitorizar, uma integração para manter.

A desvantagem é que precisamos da camada de isolamento que descrevi. Mas como já temos consultas EF Core com escopo de locatário para todo o resto do sistema, adicioná-las a glossários e regras de estilo foi simples. O padrão já estava lá.

O que realmente o protege

Para resumir as garantias de isolamento:

Entradas do glossário são armazenadas em TenantGlossary (implementa ITenantScoped), filtradas pelos filtros de consulta global do EF Core. DeepL IDs de glossário são referências opacas que só são resolvidas dentro do contexto do locatário.
As regras de estilo e as instruções personalizadas** seguem o mesmo padrão através do TenantStyleRuleList.
O conteúdo traduzido** reside em TranslationBlock, com escopo através da cadeia Entry → Hub, que também tem escopo de locatário.
O SaveChanges guard** define TenantId automaticamente em novas entidades e lança em escritas entre inquilinos.
Não há IgnoreQueryFilters()** em código de produção. Sempre.

O princípio de design é simples: DeepL vê IDs de recursos. O Rasepi vê entidades com escopo de locatário. O mapeamento entre eles nunca ultrapassa os limites do locatário porque a consulta que resolve o mapeamento é fisicamente incapaz de devolver os dados de outro locatário.

Se estiver a construir um SaaS multilocatário que se integra com APIs de terceiros sem suporte nativo do locatário, este padrão funciona bem. Trate a API externa como um mecanismo de execução sem estado, mantenha toda a configuração em seu próprio banco de dados com escopo de locatário, sincronize preguiçosamente e nunca confie em listagens de recursos externos para isolamento.

Tokens queimados são as novas linhas de código

2026-04-13T00:00:00Z

O meu feed do LinkedIn está cheio disso há semanas. A minha linha de tempo do X também. Pessoas a publicar capturas de ecrã de gastos com tokens como se fossem relatórios de progresso. Fundadores de startups a gabarem-se de terem gasto 16 mil dólares em Claude Code no mês passado e de terem como objetivo os próximos 60 mil dólares. Tabelas de classificação. Rankings. Títulos como "Lenda do Token" e "Deus da IA".

E então, na semana passada, atingiu a massa crítica. A Forbes noticiou o movimento "tokenmaxxing" que está a varrer o Vale do Silício, onde as empresas competem para ver quem queima mais tokens de IA. Jensen Huang foi ao podcast All-In e disse: "Aquele engenheiro de 500 mil dólares, no final do ano, vou perguntar-lhe: 'Quanto gastaste em tokens? Se essa pessoa disser '$5.000', eu vou-me passar. Se esse engenheiro de 500.000 dólares não consumiu pelo menos 250.000 dólares em fichas, vou ficar profundamente alarmado."

Depois, a [Fortune noticiou] (https://fortune.com/2026/04/09/meta-killed-employee-ai-token-dashboard/) que um funcionário da Meta tinha criado uma tabela de classificação interna chamada "Claudeonomics", que monitorizava o consumo de tokens pelos mais de 85.000 funcionários da empresa. Os melhores utilizadores recebiam títulos. Num período de 30 dias, o consumo total atingiu 60 biliões de tokens. O melhor utilizador individual teve uma média de 281 mil milhões. Mark Zuckerberg nem sequer entrou no top 250. Enquanto isso, o CTO da Meta, Andrew Bosworth, dizia publicamente que seu melhor engenheiro estava gastando seu salário equivalente em tokens, mas funcionando "5x a 10x mais produtivo". "É como se fosse dinheiro fácil", disse Bosworth. "Sem limite."

Já trabalho com software há tempo suficiente para perceber o que está a acontecer aqui. Isto são "linhas de código" com um preço muito mais elevado.

Já estivemos aqui antes

Em 2003, Martin Fowler escreveu [um pequeno artigo sobre por que a produtividade de software não pode ser medida] (https://martinfowler.com/bliki/CannotMeasureProductivity.html) que provavelmente deveria ser leitura obrigatória para todos os executivos técnicos. O seu argumento sobre as linhas de código era preciso:

"Uma das minhas maiores irritações são os estudos de produtividade baseados em linhas de código. Qualquer bom programador sabe que pode codificar as mesmas coisas com grandes variações nas linhas de código."

O problema é óbvio quando o dizemos em voz alta. O LOC mede a atividade, não a produção. Dois programadores podem construir a mesma funcionalidade: um escreve 1.200 linhas, o outro escreve 80. O mais conciso provavelmente construiu um sistema melhor. Sob um regime de LOC, o verboso parece mais produtivo.

As equipas avaliadas com base no LOC responderam de forma racional. Escreveram mais linhas. Copiaram e colaram em vez de abstrair. Evitaram refactoring porque a eliminação de código prejudicaria os seus números. A métrica moldou o comportamento, mas não em direção a um software melhor. Mais código. Sistemas piores.

Então, em 2023, a McKinsey publicou um artigo afirmando ter descoberto a medição objetiva da produtividade dos programadores. A resposta completa de Gergely Orosz e Kent Beck apontou a mesma falha: quase todas as métricas da McKinsey estavam medindo esforço e produção, não resultados. Kent Beck contou como os inquéritos internos do Facebook sobre o sentimento dos programadores deixaram de ser um feedback útil e passaram a ser negociados pelos gestores com os engenheiros para obterem pontuações mais elevadas. É isso que acontece quando se incentiva uma métrica proxy. O número melhora. A coisa que realmente importava não melhora.

Seria de esperar que tivéssemos aprendido. Mas não aprendemos.

O mesmo erro, unidade diferente

A lógica sedutora do tokenmaxxing é assim. Consumo de fichas = uso de IA. Mais uso de IA = as equipas estão a usar IA. Portanto, alto gasto de token = alta adoção de IA = bom.

É precisamente tão falho quanto medir linhas de código, apenas com um painel de faturamento em vez de um gráfico de confirmação. E para ser justo com o artigo da Forbes, o CEO da Sendbird, John Kim, basicamente disse exatamente isso: "Já vimos este filme antes". Ele estava a referir-se à cultura LOC dos anos 90 e 2000. O verdadeiro indicador, observou ele, é a quantidade de código gerado por IA que realmente entra em produção. Os gastos com tokens "são mais para iniciar uma conversa". Eu concordo com isso. Torna-se um problema quando o início da conversa é promovido ao KPI principal.

[Pesquisa de desenvolvedor 2024 do GitHub] (https://github.blog/news-insights/research/survey-ai-wave-grows/) descobriu que 97% dos desenvolvedores corporativos usaram ferramentas de codificação de IA no trabalho em algum momento. A adoção organizacional significativa, no entanto, exigiu políticas claras, fluxos de trabalho e resultados mensuráveis vinculados aos resultados reais do negócio. Não apenas uso. Não apenas consumo.

Boris Cherny, o engenheiro por trás do Claude Code, [compartilhou publicamente] (https://x.com/bcherny/status/2004626064187031831) que ele não abriu um IDE durante um mês de trabalho, com o Opus 4.5 escrevendo cerca de 200 PRs. Isso é impressionante. Mas o que o torna impressionante não são os tokens que esses 200 PRs consumiram. O que torna isso impressionante não são os tokens que esses 200 PRs consumiram, mas sim o facto de serem 200 contribuições reais com software a funcionar do outro lado.

O valor está no resultado. Os tokens são a energia que o levou até lá, nada mais.

Quando a métrica se torna o objetivo

Existe um princípio chamado Lei de Goodhart: quando uma medida se torna um alvo, ela deixa de ser uma boa medida. A história do desenvolvimento de software é basicamente um museu da Lei de Goodhart em ação.

O rastreamento de tokens como um KPI de adoção de IA estabelece exatamente a mesma dinâmica. As equipas de engenharia medidas pelo consumo de tokens irão consumir mais tokens. É assim que os incentivos funcionam. Quer parecer mais produtivo? Execute mais alguns loops agênticos. Deixe o modelo raciocinar longamente antes de gerar resultados. Envolva cada tarefa em uma camada de orquestração que chama quatro ferramentas onde uma seria suficiente. O gasto de fichas aumenta. O valor entregue não aumenta.

Na verdade, a história da Claudeonomics provou-o quase imediatamente. A Fortune observou que "alguns funcionários colocaram agentes de IA a trabalhar durante horas para maximizar a utilização de tokens". Aí está. A Lei de Goodhart a ser executada em tempo real, dentro de uma empresa que é suposto estar na fronteira da produtividade impulsionada pela IA. A tabela de classificação estava no ar há talvez algumas semanas antes de ser encerrada, e os funcionários já a estavam a manipular, executando agentes em loops. A métrica tinha três semanas e já tinha deixado de medir o que era suposto medir.

Qualquer programador que esteja a ler isto pode provavelmente pensar em cinco formas de inflacionar as métricas de utilização de tokens sem qualquer benefício para ninguém. Eu não vou listá-las. Mas se eu consigo pensar em cinco, os engenheiros que estão a ser medidos também conseguem.

Andrej Karpathy descreveu [o momento atual da engenharia de software] (https://x.com/karpathy/status/2004607146781278521) como um "terramoto de magnitude 9" para a profissão. Ele tem razão. Mas os terramotos não se medem pela eletricidade consumida. Eles são medidos pelo que se moveu.

A versão documental deste problema

Este não é apenas um problema para as equipas de engenharia. Vejo a mesma dinâmica na gestão do conhecimento, que está muito mais perto de nós na Rasepi.

"Publicámos 400 documentos este trimestre" é um número que soa bem numa apresentação de diapositivos. Não tem nada a dizer sobre se esses documentos são exactos, se alguém os leu ou se a informação neles contida ainda é verdadeira seis meses depois. É possível atingir esse número com IA e sem qualquer tipo de raciocínio. Ruído assistido por tokens publicado em grande escala.

A métrica honesta é mais difícil de recolher, mas muito mais útil: que percentagem da sua base de conhecimentos reflecte realmente a forma como os seus sistemas funcionam atualmente? Quantas pessoas chegaram a uma resposta correta utilizando a sua documentação? Quantas tentaram, falharam e acabaram por perguntar a alguém no Slack?

Essas perguntas ainda não têm painéis de controle bonitos. Elas exigem uma reflexão real sobre o que você deseja que a documentação faça pela sua organização. (Este é, não por coincidência, exatamente o problema em torno do qual o Rasepi foi construído. As datas de expiração forçadas existem precisamente para que as equipas tenham de avaliar se o conteúdo ainda é válido, em vez de o deixarem decair silenciosamente por detrás de uma métrica de elevado número de páginas).

O que acompanhar em vez disso

A resposta honesta a "o nosso investimento em IA está a compensar?" não pode ser lida a partir de um painel de faturação.

É possível aproximá-la com perguntas melhores: os tempos de ciclo estão a melhorar? O rácio entre as funcionalidades enviadas e os bugs reportados está a evoluir na direção certa? Os engenheiros estão a reportar que passam mais tempo a fazer trabalho de avaliação e menos a escrever? A sua documentação está a manter-se actualizada em vez de se acumular como sedimentos?

Estes são dados mais difíceis de extrair de uma API. Requerem uma reflexão sobre os resultados que se pretende obter das equipas, o que, reconhecidamente, é o trabalho mais difícil. Mas são as perguntas que interessam, porque têm a ver com resultados e não com entradas.

O gasto com tokens diz-lhe a quantidade de computação que comprou. Se esse computador se transformou em algo útil é uma questão totalmente diferente. As empresas que não fazem essa distinção vão construir painéis de controlo muito caros que não lhes mostram quase nada.

Passámos anos a otimizar a métrica errada para a produtividade dos programadores. Temos talvez um trimestre antes que o mesmo erro seja incorporado em todos os relatórios de adoção de IA na empresa. A janela para evitar isso está aberta, mas não vai continuar assim.

A divisão da IA está a dividir a sua equipa ao meio

2026-04-10T00:00:00Z

Na semana passada, estava numa chamada com um amigo meu que me falou de um dos seus clientes, uma empresa de logística. Um chefe de equipa teve uma reunião de planeamento em que dois dos seus colaboradores construíram um modelo de cenário completo utilizando IA antes mesmo de a reunião começar. Previsões, análises de risco, três abordagens alternativas. As outras quatro pessoas da equipa apareceram com o mesmo formato de apresentação de diapositivos que têm vindo a utilizar há dois anos. A mesma estrutura, o mesmo processo manual, as mesmas estimativas de prazos.

A reunião foi rapidamente por água abaixo. O par assistido por IA não conseguia perceber porque é que os outros não tinham feito a preparação básica que "demora cinco minutos". Os outros sentiram-se emboscados, como se as regras do jogo tivessem mudado e ninguém lhes tivesse dito nada. O líder da equipa passou o resto do dia a controlar os danos.

Esta história já não me surpreende. Há meses que ouço versões dela.

A diferença agora é mensurável

Não se trata apenas de vibrações. O [2025 Work Trend Index] da Microsoft (https://www.microsoft.com/en-us/worklab/work-trend-index/2025-the-year-the-frontier-firm-is-born), um inquérito a 31.000 trabalhadores em 31 países, revelou que 67% dos líderes estão familiarizados com os agentes de IA, em comparação com apenas 40% dos funcionários. Os líderes são muito mais propensos a ver a IA como um acelerador de carreira (79% contra 67% dos funcionários), e também estão a poupar mais tempo com ela. Quase um terço dos líderes afirma que a IA lhes poupa mais de uma hora por dia.

Mas aqui está a parte que realmente me marcou: quando questionados sobre como vêem a IA, 52% dos inquiridos disseram que a tratam como uma ferramenta baseada em comandos. Dá-lhe uma instrução, obtém um resultado. Apenas 46% a descreveram como um parceiro de pensamento, algo com o qual se tem uma troca de ideias.

Esta não é uma diferença pequena. São duas relações fundamentalmente diferentes com a mesma tecnologia. E estes dois grupos participam nas mesmas reuniões, trabalham nos mesmos projectos e, supostamente, caminham na mesma direção.

Duas velocidades, uma equipa

A consequência prática é que as equipas estão agora a trabalhar a duas velocidades completamente diferentes. As pessoas que integraram a IA no seu trabalho diário não se limitam a produzir mais depressa. Pensam de forma diferente. Abordam os problemas de forma diferente. Chegam às reuniões com o trabalho que costumava demorar uma semana feito numa tarde.

E as pessoas que ainda não adoptaram a IA (ou que a experimentaram uma vez, acharam-na pouco satisfatória e seguiram em frente) estão a fazer um trabalho genuinamente sólido. Quero ser claro quanto a isso. Não é que eles sejam maus no seu trabalho. É que o teto do que é possível mudou e eles estão a trabalhar sob o antigo.

Um [estudo de Harvard sobre IA generativa em equipas] (https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5188231) descobriu algo notável: um único indivíduo com IA tem um desempenho superior ao de uma equipa inteira sem IA. Mas uma equipa em que todos utilizam a IA tem um desempenho superior a todos. A implicação é brutal. A adoção mista não oferece um meio-termo. Dá-nos fricção.

Vi isto em primeira mão num workshop que organizei no mês passado. Os participantes que utilizavam a IA regularmente estavam a terminar os exercícios em metade do tempo, ficando depois frustrados à espera do resto. Os participantes que não utilizavam a IA sentiram-se apressados e, honestamente, um pouco humilhados. Ninguém pretendia este resultado. Aconteceu simplesmente porque a diferença de velocidade é agora tão grande.

A vantagem competitiva de que ninguém fala

É aqui que isto se torna realmente consequente. O inquérito [State of AI 2025] da McKinsey (https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai) concluiu que 88% das organizações estão a utilizar a IA em pelo menos uma função. Parece ótimo, certo? Mas quase dois terços ainda estão presos em fases de experimentação e piloto. Apenas cerca de um terço começou a escalar a IA em seus negócios. E as empresas que escalaram, aquelas que a McKinsey chama de "alto desempenho"? Representam cerca de 6% dos inquiridos.

Esses 6% estão a afastar-se de todos os outros a uma velocidade que penso que a maioria das pessoas subestima.

As empresas de elevado desempenho têm três vezes mais probabilidades de ter redesenhado fundamentalmente os seus fluxos de trabalho em torno da IA. Têm três vezes mais probabilidades de ter líderes seniores a defender ativamente e a modelar a utilização da IA. Três quartos deles estão a expandir ou já expandiram a IA na sua organização, em comparação com um terço de todos os outros.

Os dados da Microsoft contam uma história semelhante. As empresas que eles chamam de "Empresas de Fronteira" (aquelas com implantação de IA em toda a organização e maturidade avançada) relatam resultados dramaticamente diferentes. 71% dos líderes das Empresas de Fronteira dizem que a sua empresa está a prosperar, em comparação com 39% dos trabalhadores a nível global. 55% dizem que podem assumir mais trabalho, contra 25% globalmente. E têm menos medo de que a IA lhes tire o emprego, e não mais.

O fosso entre estas empresas e todas as outras não está a diminuir. Está a acelerar.

Este é um problema de pessoas disfarçado de um problema de tecnologia

A tentação é resolver isto com ferramentas. Lançar o Copilot, comprar algumas licenças, enviar um e-mail a toda a empresa sobre os recursos de IA. Pronto.

Mas o verdadeiro desafio é cultural. É o chefe de equipa que está na chamada a tentar manter unido um grupo em que metade das pessoas se sente sobrecarregada e a outra metade se sente deixada para trás. É o gestor que tem de explicar a um veterano de 20 anos que o seu fluxo de trabalho, aquele que aperfeiçoou ao longo de uma década, pode já não ser a melhor abordagem. É o empregado júnior que está a utilizar discretamente a IA para produzir trabalho de nível superior e não sabe se deve estar orgulhoso ou preocupado com as consequências políticas.

A Microsoft descobriu que 47% dos líderes listam a melhoria das competências dos funcionários existentes como uma das principais estratégias da força de trabalho. Isso é encorajador, suponho. Mas a melhoria das competências só funciona se as pessoas quiserem efetivamente aprender. E, neste momento, uma parte significativa da força de trabalho decidiu que a IA não é relevante para eles, não é fiável ou não vale a pena o esforço. Alguns deles podem ter razão em relação a ferramentas específicas. Mas a trajetória mais geral não é opcional (digo isto como alguém que tem sido cético em relação a muitos ciclos de propaganda tecnológica ao longo dos anos, mas este parece diferente).

Para onde isto está a ir

Não creio que o fosso desapareça. Penso que se alarga. As pessoas que adoptam a IA vão continuar a ser mais rápidas, a produzir mais, a elevar a fasquia do que é uma "produção normal". As pessoas que não o fizerem sentir-se-ão cada vez mais pressionadas, seja pela administração, pelos colegas ou apenas pela realidade ambiente de que os seus colegas estão a fazer coisas que elas não conseguem.

As empresas que descobrirem como fazer com que toda a sua equipa acompanhe o processo, e não apenas os entusiastas, terão uma vantagem genuína. E essa vantagem aumenta. Cada mês de fluência organizacional em IA é um mês que os seus concorrentes passam a discutir se devem comprar licenças do ChatGPT.

A maior vantagem competitiva na era da IA não será o modelo que utilizar. Será se toda a sua equipa o utiliza realmente.

A equipa de logística de que falei? O meu amigo disse-me que o chefe da equipa marcou um workshop interno de dois dias. Não é "aqui está como fazer". É mais do tipo "eis como isto muda a forma como planeamos em conjunto". Os cépticos precisavam de ver o que era possível no contexto do seu trabalho, não numa demonstração genérica com um cenário inventado. E os entusiastas precisavam de aprender a ter paciência. Para trazer as pessoas consigo em vez de correrem à frente.

Parece que é esse o trabalho neste momento. Não apenas adotar a IA. Fechar o fosso. Antes que ela nos feche a nós.

Construir vs Comprar Reimaginado: O que realmente significa em 2026

2026-04-07T00:00:00Z

Na semana passada, vi um programador júnior da nossa equipa criar uma aplicação CRUD funcional com autenticação, migrações de bases de dados e uma interface de utilizador decente em cerca de 90 minutos. Com o Copilot. Do zero.

Há cinco anos, essa mesma tarefa teria demorado uma semana. Talvez duas, se contarmos com as configurações de implantação e os fluxos OAuth. E essa mudança, essa compressão do tempo de construção de dias para horas, está a desmantelar silenciosamente uma das questões mais antigas do software: devemos construir ou devemos comprar?

A velha estrutura está morta

Durante décadas, "construir vs comprar" era um cálculo de custo. Você estimava quantos meses de desenvolvimento seriam necessários para construir algo, multiplicava pelo salário, adicionava algum buffer para manutenção e comparava com a taxa de licença anual de qualquer produto SaaS que fizesse mais ou menos a mesma coisa. Se o SaaS fosse mais barato, comprava-se. Se os seus requisitos fossem suficientemente estranhos, construía.

Esse enquadramento pressupunha que construir era caro. E era. Mas [de acordo com os dados do Octoverse 2025 do GitHub] (https://github.blog/ai-and-ml/generative-ai/how-ai-is-reshaping-developer-choice-and-octoverse-data-proves-it/), o desenvolvimento assistido por IA agora produz um aumento de 20 a 30 por cento na taxa de transferência. Oitenta por cento dos novos desenvolvedores no GitHub usam o Copilot na primeira semana. Mais de 1,1 milhão de repositórios públicos já integram SDKs do LLM. Construir ficou dramaticamente mais barato, quase da noite para o dia.

Portanto, a questão não é mais "construir ou comprar". É algo mais parecido com: pelo que está realmente a pagar quando compra SaaS?

O Novo Cálculo

Aqui está o que eu acho que a maioria dos fundadores de SaaS (eu incluído, honestamente) não querem ouvir: se toda a sua proposta de valor é "nós salvamos você de construir isso", você está em apuros. Porque esse fosso acabou de ficar muito mais raso.

Quando uma equipa consegue criar um protótipo de uma ferramenta interna funcional num dia, a fasquia para o que justifica uma subscrição mensal sobe muito. Não precisa apenas de ser melhor do que aquilo que eles conseguem construir. Tem de ser melhor do que aquilo que eles poderiam construir com a ajuda da IA.

[A Gartner previu em abril de 2026] (https://www.gartner.com/en/newsroom/press-releases/2026-04-02-gartner-expects-most-enterprises-to-abandon-assistive-ai-for-outcome-focused-workflow-by-2028) que, até 2028, mais de metade das empresas deixará de pagar pela inteligência de assistência e preferirá plataformas que se comprometam com os resultados do fluxo de trabalho. Ainda mais grave: prevêem que, até 2030, as empresas de software que colocam IA sobre aplicações antigas, em vez de as redesenharem para uma execução agêntica, enfrentarão uma compressão das margens de até 80%.

Oitenta por cento. Isto não é um erro de arredondamento.

Então, o que é que realmente sobrevive?

Tenho pensado muito sobre isto, em parte porque estamos a construir o Rasepi e preciso de ser honesto comigo mesmo sobre onde está o nosso valor. E acho que a resposta se resume a três coisas que são genuinamente difíceis de replicar com um sprint de codificação de fim de semana, por melhor que seja o seu assistente de IA.

**Qualquer pessoa pode construir um editor de texto. Construir um sistema de tradução que acompanhe as alterações de conteúdo ao nível do parágrafo, detecte traduções obsoletas através de hashing de conteúdo e trate da adaptação estrutural entre línguas? Isso requer anos de conhecimento do domínio incorporado na arquitetura. A IA pode ajudá-lo a escrever o código mais rapidamente, mas não lhe pode dizer o que construir.

**Alguém ainda tem de o executar e manter. Eis o que se passa com a construção: é divertido. Manter? Não é nada divertido. Lidar com casos extremos em sistemas de permissão multi-tenant, acompanhar as peculiaridades dos browsers, gerir migrações de bases de dados entre versões, corrigir CVEs às 2 da manhã, lidar com aquele bug de exportação de PDF que só aparece no Safari. A IA torna a construção inicial mais rápida, com certeza. Mas [pesquisa da Forrester de abril de 2026] (https://www.forrester.com/press-newsroom/forrester-three-years-into-genai-enterprises-are-still-chasing-its-true-transformative-value/) mostra que a maioria das empresas ainda não consegue transformar a adoção da IA em um impacto mensurável, em parte porque a parte difícil nunca foi escrever código. É manter a coisa funcionando, atualizada e funcionando corretamente por anos. A construção é a parte fácil. É o tempo de atividade, as rotações de plantão e as correções incrementais que realmente custam caro.

**Confiança, segurança e privacidade dos dados: Esta é subestimada. Quando se constrói algo por si próprio, a segurança é sua. É responsável pela encriptação em repouso, registo de auditorias, testes de penetração, conformidade com o GDPR, SOC 2 e o próximo regulamento de que ainda ninguém ouviu falar. Um bom fornecedor de SaaS tem uma equipa inteira cuja única função é garantir que os seus dados não vão parar a um sítio onde não deveriam estar. Para a maioria das empresas, esse não é um custo que queiram suportar internamente. E, honestamente, a maioria das ferramentas internas que vi nem sequer têm controlos de acesso adequados, quanto mais uma pista de auditoria de segurança.

O meio-termo compostável

O que é interessante é que a resposta cada vez mais não é "construir" ou "comprar". É compor. Escolha as ferramentas SaaS que fazem bem as coisas difíceis, expõem boas APIs e permitem que você construa em torno delas.

É por isso que as arquitecturas de plugins são tão importantes neste momento (e sim, é exatamente nisto que temos investido com o sistema de plugins do Rasepi). Os produtos SaaS que vão prosperar são aqueles que dizem: "Nós tratamos do núcleo duro e específico do domínio. Você personaliza tudo o resto". Não "aqui está o nosso monólito, é pegar ou largar".

[O relatório da Forrester de abril de 2026] (https://www.forrester.com/press-newsroom/forrester-three-years-into-genai-enterprises-are-still-chasing-its-true-transformative-value/) concluiu que a maioria das empresas ainda está a lutar para transformar a adoção da IA num impacto comercial mensurável. As empresas que mais adotam a IA têm 47% mais probabilidade de trabalhar com parceiros de consultoria para preparar seus dados e sistemas. A mensagem é clara: a capacidade de construção em bruto não é o estrangulamento. Saber o que construir e ter a infraestrutura para o suportar é que é o verdadeiro constrangimento.

O que isto significa para o SaaS

Se estiver a gerir uma empresa SaaS em 2026, penso que existem algumas verdades incómodas:

O seu argumento de venda "vamos poupar-lhe tempo" está mais fraco do que nunca.** A poupança de tempo era a venda clássica de SaaS. Mas quando a IA comprime o tempo de construção em 20-30%, o número "tempo poupado" na sua folha de cálculo do ROI diminui proporcionalmente. Você precisa de uma história diferente.
Ninguém quer saber se você tem 47 integrações. O que lhes interessa é que a documentação permaneça actualizada, que as traduções sejam exactas e que a sua equipa utilize efetivamente a ferramenta. A linguagem da Gartner sobre "fluxo de trabalho centrado nos resultados" não é apenas jargão de analista. É para onde o mercado se está a dirigir.
O instinto de fechar a sua plataforma e dificultar a mudança é compreensível. Mas a Gartner avisou explicitamente que "os fornecedores de SaaS antigos que tentam fechar os sistemas de registo correm o risco de serem ultrapassados por camadas de orquestração em que as empresas confiam mais". Ai.

A versão honesta

Vou ser franco sobre o meu ponto de vista. Construir vs comprar nunca foi realmente sobre a tecnologia. Foi sempre uma questão de confiança. Será que confio que este fornecedor compreende o meu problema de forma suficientemente profunda para que a sua solução seja melhor do que a que eu poderia arranjar?

Em 2026, o "remendar" sofreu uma grande atualização. Por isso, a fasquia da confiança também subiu.

Para nós, na Rasepi, isso significa que não podemos ser apenas uma ferramenta de documentação que, por acaso, suporta traduções. Temos de ser tão bons nos problemas difíceis, no acompanhamento da tradução ao nível do bloco, na aplicação da frescura do conteúdo, na complexidade multi-tenant, que construir um substituto seria genuinamente doloroso, mesmo com as melhores ferramentas de IA do mundo.

Esta é a nova questão "construir ou comprar". Não se trata de "é possível construí-lo?", mas sim de "deve gastar a sua energia a construí-lo quando outra pessoa já resolveu as partes mais difíceis?"

A questão nunca foi realmente o custo. A questão era saber onde quer gastar a sua atenção. E num mundo onde construir é barato, a atenção é o único recurso escasso que resta.

Pare de despedir pessoas porque a IA existe

2026-04-04T00:00:00Z

Uma amiga minha gere conteúdos para uma empresa SaaS de média dimensão. No ano passado, a sua equipa era composta por oito pessoas. Escritores, editores, um especialista em localização, alguém que tratava da base de conhecimentos. Boa equipa, resultados sólidos. Depois, o diretor executivo participou numa conferência, voltou entusiasmado com a IA e, em três meses, a equipa ficou reduzida a três pessoas. O motivo? _"Com as ferramentas de IA, três pessoas podem produzir o que oito costumavam produzir.

E, tecnicamente, isso é verdade. As três pessoas restantes estão a produzir praticamente o mesmo volume. Publicações em blogues, documentos de ajuda, actualizações de produtos, comunicações internas. Os números parecem bons num painel de controlo.

Mas a minha amiga não dorme bem há meses. Está a alternar entre a escrita, a edição, a engenharia de prontidão, o controlo de qualidade dos resultados da IA, a gestão das traduções e todo o trabalho estratégico que costumava ser partilhado por toda a equipa. Os dois colegas que lhe restam estão no mesmo barco. Um deles já está à procura de outro emprego.

A empresa poupou cinco salários. Está também a perder lentamente as três pessoas que sabem realmente como as coisas funcionam.

A matemática que parece correta mas não é

Eis o argumento que tem estado a circular nas salas de reuniões desde que o ChatGPT se tornou popular: uma pessoa com IA pode agora fazer o trabalho de dez. E se for esse o caso, porquê manter dez?

É um argumento convincente. Simples. Limpo. Cabe num slide.

Também é perigosamente incompleto.

Sim, a IA pode comprimir tarefas. De acordo com o [Índice de Tendências de Trabalho 2024 da Microsoft] (https://www.microsoft.com/en-us/worklab/work-trend-index/ai-at-work-is-here-now-comes-the-hard-part), 90% dos utilizadores de IA no trabalho afirmam que as ferramentas os ajudam a poupar tempo. Os utilizadores mais intensivos do Microsoft Teams resumiram oito horas de reuniões utilizando o Copilot num único mês. Isto representa um dia inteiro de trabalho recuperado apenas com os resumos das reuniões. E 85% dizem que a IA ajuda-os a concentrarem-se no trabalho mais importante.

Estes são números reais. Os ganhos de produtividade não são imaginários.

Mas eis o que os adeptos do "despedir nove pessoas" nunca mencionam: a pessoa que fica não absorve apenas o resultado. Absorve a carga cognitiva, o contexto, a tomada de decisões, a coordenação, a garantia de qualidade e todo o conhecimento institucional que saiu pela porta fora com esses nove antigos colegas.

A carga mental não é uma folha de cálculo

Existe um conceito em psicologia chamado teoria da carga cognitiva. Este conceito descreve a quantidade total de esforço mental que está a ser utilizado na memória de trabalho num determinado momento. E sempre que se pede a uma pessoa para pensar o que cinco pessoas costumavam partilhar, não se está a poupar esforço. Está a concentrá-lo.

Penso muito nisto quando as pessoas me dizem que a IA torna os trabalhadores "10 vezes mais produtivos". Produtivos em quê? A produzir mais palavras? A enviar mais bilhetes? A gerar mais apresentações de diapositivos? Claro. Mas a parte difícil do trabalho do conhecimento nunca foi a produção. É o pensar. Decidir o que produzir. Compreender o contexto. Fazer juízos de valor. Saber quando algo está errado, mesmo quando parece correto à primeira vista.

A IA não faz isso por si. A IA dá-lhe um primeiro rascunho, e agora tem de ser suficientemente inteligente para o avaliar, suficientemente experiente para detetar os erros subtis e suficientemente presente para reparar quando o resultado está seguramente errado. (Se alguma vez viu alguém enviar um documento interno gerado por IA sem o ler, sabe exatamente o que quero dizer).

O relatório Gallup's 2025 State of the Global Workplace concluiu que o envolvimento global dos trabalhadores caiu para 21% em 2024, contra 23% no ano anterior. Esta queda custou à economia mundial um valor estimado de 438 mil milhões de dólares em perda de produtividade. O envolvimento dos gestores registou uma queda ainda mais acentuada, de 30% para 27%. As mulheres gestoras registaram um declínio de sete pontos. Os gestores com menos de 35 anos registaram uma descida de cinco pontos.

Estas são as pessoas que deveriam estar a liderar a adoção da IA. E estão a esgotar-se.

O argumento da amplificação

Deixem-me oferecer uma forma diferente de pensar sobre isto.

Se uma pessoa com IA pode fazer o trabalho de dez, então dez pessoas com IA podem fazer o trabalho de cem.

Lê isto outra vez. Porque esta é a parte de que quase ninguém está a falar, e é a parte que deveria manter todos os CEO acordados à noite. Não porque seja assustadora, mas porque é uma enorme oportunidade que a maioria das empresas está a desperdiçar.

As empresas que despedem metade da sua força de trabalho porque "a IA dá conta do recado" não estão a ser eficientes. Estão a ser míopes. Estão a otimizar para um número trimestral de efectivos enquanto os seus concorrentes descobrem o que acontece quando se dão ferramentas poderosas a uma equipa completa de pessoas motivadas e experientes.

Vi isto acontecer num evento de startups em Zurique, no mês passado. Duas empresas do mesmo sector. Mais ou menos do mesmo tamanho, no mesmo mercado. A empresa A tinha reduzido a sua equipa de conteúdos de doze para quatro pessoas. A empresa B manteve os doze e deu-lhes ferramentas de IA e formação. Adivinhe qual delas estava a produzir conteúdos multilingues em seis línguas, a fazer experiências com novos formatos e a enviar actualizações semanais de produtos para a sua base de conhecimentos? (Não era a empresa A.)

O que realmente acontece quando se corta

Deixem-me explicar o que acontece na prática quando se substitui uma equipa de dez pessoas por um ou dois super-trabalhadores "melhorados com IA".

**A primeira semana é óptima. As restantes pessoas estão cheias de energia. Têm novas ferramentas. Estão a produzir muito. A liderança está entusiasmada. Os números do painel de controlo parecem incríveis em relação ao número de funcionários.

**A única pessoa responsável pela documentação descobre que o conteúdo gerado pela IA precisa de uma revisão séria. Não é uma edição ligeira. Uma revisão profunda. Porque a IA não conhece as nuances do seu produto, o contexto do seu cliente ou as três coisas que mudou na semana passada e que invalidaram metade do que foi escrito. O trabalho de revisão, por si só, consome o tempo que foi "poupado" ao gerar conteúdo mais rapidamente.

**No quarto mês, surgem as lacunas de conhecimento institucional. Lembra-se das oito pessoas que dispensou? Elas não se limitavam a escrever conteúdos. Tinham relações com os gestores de produto. Entendiam os pontos fracos dos clientes com base em anos de padrões de tickets de suporte. Eles sabiam quais tópicos de documentação geravam mais perguntas. Esse conhecimento foi-se. A IA certamente não o tem.

**Porque as pessoas restantes estão sobrecarregadas, a qualidade caiu e alguém finalmente percebeu que a base de conhecimento não foi atualizada adequadamente em semanas. Mas os contratados também não têm contexto, pelo que está a pagar mais por hora para obter piores resultados.

Não estou a inventar isto. Vi este padrão repetir-se em três empresas diferentes só no último ano.

Os dados dizem para manter o seu pessoal (e formá-lo)

O [Relatório sobre o Futuro do Emprego 2025 do Fórum Económico Mundial] (https://www.weforum.org/publications/the-future-of-jobs-report-2025/digest/) questionou mais de 1.000 empregadores globais sobre os seus planos para a força de trabalho. Os números contam uma história interessante. Sim, 40% dos empregadores planeiam reduzir o pessoal nos casos em que a IA automatiza as tarefas. Mas 85% planeiam melhorar as competências da sua força de trabalho existente. E 70% esperam contratar pessoas com novas competências, e não menos pessoas.

O relatório prevê um crescimento líquido de 78 milhões de postos de trabalho até 2030. Isto depois de contabilizar os 92 milhões de postos de trabalho deslocados. O mundo não está a evoluir para menos trabalhadores. Está a evoluir para trabalhadores com competências diferentes.

E eis o que deveria fazer parar todos os diretores executivos "vamos reduzir o número de funcionários": 64% dos empregadores identificaram o apoio à saúde e ao bem-estar dos empregados como uma estratégia fundamental para a disponibilidade de talentos. Não é "reduzir custos". Não é "automatizar tudo". **Apoiar o bem-estar. Porque as empresas que queimam o seu pessoal não conseguem contratar os bons mais tarde.

Entretanto, um estudo [da BCG e da Harvard Business School] (https://www.bcg.com/publications/2023/how-people-create-and-destroy-value-with-gen-ai) concluiu que, quando as equipas utilizaram a IA para tarefas criativas, cerca de 90% melhoraram o seu desempenho, tendo a qualidade dos resultados aumentado 40% em relação aos grupos de controlo. Mas o estudo também descobriu algo que deveria deixar qualquer líder desconfortável: a diversidade de ideias entre os grupos assistidos por IA caiu 41%.

Pense no que isso significa. Despedimos sete pessoas da nossa equipa de dez pessoas. As três que ficam utilizam a IA para produzir o mesmo volume. Mas o leque de ideias, perspectivas e abordagens diminui para quase metade. A sua produção parece produtiva, mas torna-se gradualmente homogénea. E ninguém repara até que um concorrente lança algo genuinamente criativo e você não consegue perceber porque é que a sua equipa não está a fazer o mesmo.

A carga mental que ninguém orçamenta

O inquérito da Microsoft revelou que 68% das pessoas se debatem com o ritmo e o volume de trabalho e 46% sentem-se esgotadas. E este era o estado das coisas antes de lhes dizer que agora estão a fazer o trabalho dos seus três antigos colegas de equipa.

Aqui está algo que não aparece nos painéis de produtividade: o custo cognitivo de ser a última linha de defesa. Quando se é a única pessoa a rever os resultados da IA, não se pode ter um dia de folga. Quando é o único proprietário da base de conhecimentos, todas as questões de apoio vão parar à sua secretária. Quando não há ninguém com quem trocar ideias porque a equipa foi "bem dimensionada", cada decisão é só sua.

Tenho estado a construir o Rasepi em parte porque vi este problema de perto. Quando as equipas de documentação diminuem, o conhecimento não diminui com elas. A quantidade de conteúdo que precisa de existir, manter-se atualizado e ser exato em todas as línguas não diminui só porque há menos pessoas a mantê-lo. Pelo contrário, aumenta (isto é verdade). Pelo contrário, aumenta (este é exatamente o problema que estamos a construir para resolver com o Rasepi, já agora, com funcionalidades como datas de expiração forçadas e traduções por blocos que tornam as equipas mais pequenas genuinamente mais eficazes em vez de mais sobrecarregadas).

Mas mesmo as melhores ferramentas não resolvem uma decisão de pessoal fundamentalmente errada. Não se pode automatizar a necessidade de julgamento humano, contexto e cuidado. Apenas se pode tornar esses humanos mais eficazes.

O que as empresas inteligentes realmente fazem

O mais impressionante nos dados da Microsoft é o aspeto dos "utilizadores avançados de IA". São pessoas que utilizam a IA várias vezes por dia e poupam mais de 30 minutos. Têm 68% mais probabilidades de experimentar diferentes formas de utilizar a IA. Não se limitam a gerar mais resultados. Reformulam a forma como o trabalho acontece.

E o melhor de tudo é que existem nas organizações que investem neles. Os utilizadores avançados de IA têm 61% mais probabilidades de ouvir o seu CEO falar da importância da IA no trabalho. Têm mais 53% de probabilidades de serem encorajados pela liderança a repensar toda a sua função. Recebem formação personalizada e não apenas um login no ChatGPT.

Por outras palavras, os trabalhadores de IA mais produtivos não são sobreviventes solitários de um despedimento. São membros de equipas apoiadas e investidas.

Deixem-me comparar isto com o que vejo nas empresas que optaram pela via da "redução de efectivos". Os empregados que ficam não são utilizadores avançados. São generalistas sobrecarregados que tentam desesperadamente manter as coisas a funcionar. Não têm tempo para experimentar a IA porque estão demasiado ocupados a utilizá-la para sobreviver. Não há como repensar a função porque a função é apenas... eles, sozinhos, a fazer tudo.

O problema do conhecimento que ninguém menciona

Há mais uma coisa. E não ouço ninguém falar sobre isso, o que é estranho porque deveria ser óbvio.

Quando se despedem trabalhadores experientes, o conhecimento vai-se embora com eles. Não fica no edifício. Não fica no wiki. Não está na IA. Está nas cabeças das pessoas que criaram os processos, compreenderam os casos extremos e sabiam que clientes se preocupavam com que pormenores.

Sabe o que acontece quando se tem óptimas ferramentas de IA e nenhum conhecimento institucional? Obtém-se uma informação perfeitamente formatada, entregue com confiança e completamente errada. Em grande escala.

No mês passado, conversei com uma chefe de documentação de uma empresa de fintech (ela não quis ser identificada, o que nos diz alguma coisa). Depois de a sua equipa ter sido reduzida de seis para dois, começaram a confiar fortemente na IA para manter os documentos dos seus programadores. Em quatro meses, notaram um aumento nos pedidos de apoio. Os documentos pareciam bem. Estavam bem escritos e actualizados à primeira vista. Mas continham erros subtis que só alguém com um conhecimento profundo do produto teria detectado. Uma descrição de parâmetro de API que era tecnicamente correta mas praticamente enganadora. Um guia de migração que não incluía um passo que todos os membros da antiga equipa já conheciam. Pequenas coisas que a IA não pode saber porque a IA não participa das suas reuniões, não lê os seus tópicos do Slack, não ouve o frustrado "oh, esse documento está errado novamente" do engenheiro de suporte na máquina de café.

A verdadeira questão

Portanto, eis o que eu acho que a conversa deveria ser.

Não: "Quantas pessoas podemos cortar agora que temos IA?"

Mas sim: "O que é que se torna possível quando damos IA a todas as pessoas que já temos?"

A sua equipa de documentação de dez pessoas com ferramentas de IA não se torna redundante. Torna-se uma equipa que pode manter o conteúdo em doze línguas em vez de duas. Que pode manter todos os conteúdos actualizados com verificações automáticas de atualidade. Que pode experimentar novos formatos, executar testes A/B em conteúdos de ajuda, criar guias interactivos e ainda ter tempo para pensar estrategicamente sobre o que os clientes realmente precisam.

A sua equipa de marketing de dez pessoas com IA não se transforma em cinco pessoas a fazer o mesmo trabalho com mais stress. Passa a ser dez pessoas que podem personalizar campanhas a uma escala que antes era impossível, testar mais variações criativas, responder mais rapidamente às mudanças do mercado e ainda ter a largura de banda cognitiva para ter ideias genuinamente originais que a IA nunca teria gerado.

Isto não é um custo. É um investimento com um retorno que aumenta.

Onde é que isto vai parar

As empresas que vencerão nos próximos cinco anos não serão as que cortarem mais cabeças. Serão aquelas que descobriram como tornar as suas equipas existentes genuinamente mais capazes.

A questão não é se uma pessoa pode fazer o trabalho de dez. A questão é o que acontece quando todos os dez podem fazer o trabalho de cem.

Se é um líder que está a ler isto, gostaria de lhe pedir uma coisa. Antes de aprovar a próxima ronda de "reestruturação com recurso a IA", fale com as pessoas que ficaram depois da última ronda. Pergunte-lhes como estão a reagir. Perguntem-lhes o que deixaram de fazer por não haver tempo. Pergunte-lhes o que está a ficar para trás.

E depois imagine o que poderiam fazer se, em vez de carregarem o fardo sozinhas, tivessem uma equipa completa e as melhores ferramentas disponíveis.

Isso não é uma fantasia. Para as empresas que estão dispostas a investir nos seus colaboradores em vez de os substituir, esses são os próximos doze meses.

Leitores e escritores estão em modos mentais diferentes. Porque é que todas as ferramentas lhes dão a mesma interface de utilizador?

2026-04-03T00:00:00Z

Abra o Confluence agora mesmo e encontre um documento que precise de ler. O que é que vê?

Uma barra de ferramentas. Botões de edição. Caixas de comentários. Ligações para o histórico da página. Uma barra lateral cheia de navegação de que não precisa. Pistas de navegação. Campos de metadados. Indicadores de permissão. Toda uma interface de criação em torno do texto que veio aqui para ler.

Agora pense no que realmente queria: a resposta a uma pergunta, ou os três passos seguintes de um processo, ou uma política que precisa de consultar antes de uma reunião daqui a dez minutos.

Veio para consumir. A interface pressupõe que veio para criar.

Este é o padrão em quase todas as plataformas de documentação. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. Todas elas apresentam o mesmo ambiente aos leitores e escritores. A página é a página. Toda a gente tem a mesma visão, com mais ou menos alguns botões com permissões.

Parece normal porque nunca tivemos outra coisa. Mas é uma decisão de design, não uma lei da natureza. E é a decisão errada.

Ler e escrever não são a mesma tarefa cognitiva

Isto não é uma preferência de interface. Trata-se de uma diferença fundamental na forma como o cérebro funciona.

Quando se escreve, está-se em modo generativo. Está a construir, a organizar, a decidir o que incluir e o que deixar de fora. Precisa de ferramentas: opções de formatação, controlos de estrutura, incorporação de suportes, campos de metadados, histórico de versões, funcionalidades de colaboração. A interface deve proporcionar-lhe poder e flexibilidade.

Quando se lê, está-se em modo recetivo. Está a analisar, a filtrar, a extrair o que é relevante e a tentar seguir em frente. Necessita de clareza: tipografia limpa, disposição clara, distração mínima. A interface deve sair do caminho.

A psicologia cognitiva tem uma estrutura clara para isto. A [Teoria da Carga Cognitiva] (https://www.instructionaldesign.org/theories/cognitive-load/), desenvolvida por John Sweller no final dos anos 80, distingue entre carga intrínseca (a dificuldade do material em si), carga germânica (o esforço de aprendizagem e integração) e carga externa (tudo o que o ambiente acrescenta que não ajuda). Todas as barras de ferramentas, barras laterais e botões de edição visíveis para um leitor são cargas estranhas. Não os ajuda a compreender o conteúdo. Concorre ativamente pela atenção.

A investigação de [Mayer e Moreno (2003)] (https://doi.org/10.1207/S15326985EP3801_6) sobre a aprendizagem multimédia demonstrou que a redução de elementos estranhos melhora a compreensão e a retenção. O seu princípio de coerência é direto: Uma interface de documentação que mostra os controlos de criação aos leitores está a violar este princípio em cada carregamento de página.

**O leitor não precisa de ver as ferramentas do autor. Mostrá-las na mesma não é neutro. É ativamente prejudicial para a compreensão.

Como é que as plataformas actuais lidam com isto (a maioria não lida)

Vejamos o que existe.

O Confluence tem um modo de leitura e um modo de edição, mas o modo de leitura ainda está rodeado pela navegação, metadados e árvore de páginas da plataforma. A barra de ferramentas de edição desaparece quando não se está a editar, mas o quadro mental de "esta é uma página wiki editável" nunca desaparece completamente. Todos os leitores vêem o botão "Editar". A página sussurra: podes mudar isto.

O Notion é pior neste aspeto. A sua principal filosofia de design é que tudo é sempre editável. Clique em qualquer lugar e está a escrever. Isso é ótimo para os escritores. É terrível para os leitores que querem apenas absorver o conteúdo sem a ansiedade de modificar algo acidentalmente. A própria [galeria de modelos] do Notion (https://www.notion.com/templates) mostra isso: cada modelo é um espaço de trabalho, não uma publicação.

O SharePoint suporta tecnicamente diferentes layouts de página para visualização e edição, mas a experiência geral continua a ser uma intranet corporativa. Os leitores sentem-se como se estivessem dentro de uma ferramenta empresarial e não a ler um documento optimizado para a compreensão.

O GitBook é o que mais se aproxima de uma experiência de leitura em primeiro lugar, com a sua saída limpa ao estilo de documentação. Mas mesmo aí, a experiência de leitura serve o pressuposto de que o leitor é um programador que está a olhar para documentos técnicos. Não foi concebido para o consumidor de conhecimentos gerais.

Nenhuma destas plataformas trata a leitura como uma atividade fundamentalmente diferente da escrita. Tratam-na como escrever com a barra de ferramentas escondida.

Ferramentas actuais: uma interface, todos os públicos](/pt/blog/img/leitores-escritores-ferramentas-actuais.svg)

O custo de uma interface única

Este não é apenas um problema estético. Tem consequências mensuráveis.

A sobrecarga de informação reduz a compreensão

Um [estudo publicado no Journal of Consumer Research] (https://doi.org/10.1086/209336) descobriu que a sobrecarga de informação leva a uma pior qualidade de decisão, com o efeito a aumentar à medida que o rácio entre informação irrelevante e relevante cresce. Uma página de documentação com controlos de criação visíveis, árvores de navegação e campos de metadados aumenta esse rácio para todos os leitores que não estão lá para escrever.

A mudança de contexto tem um custo real

Quando um sinal de interface diz "pode editar isto", ativa um quadro cognitivo diferente de "leia isto". A investigação de Gloria Mark na UC Irvine sobre atenção e multitarefas concluiu que são necessários, em média, 23 minutos e 15 segundos para voltar a concentrar-se totalmente após uma mudança de contexto. Um leitor que considere momentaneamente a hipótese de editar (mesmo para corrigir uma gralha) foi retirado do modo de leitura. Não se trata de uma hipótese. Qualquer pessoa que tenha utilizado o Notion conhece a experiência de clicar para selecionar texto e acidentalmente começar a escrever.

Leitores e escritores têm necessidades diferentes para o mesmo conteúdo

Um escritor precisa de ver a estrutura, os marcadores de formatação, os tipos de blocos, os metadados e os sinais de colaboração. Precisa de toda a maquinaria.

Um leitor precisa de ver texto limpo, hierarquia clara e o caminho mais rápido para a informação que procura. Precisa do conteúdo, não da maquinaria.

Servir ambos a partir da mesma interface significa que nenhum deles obtém uma experiência optimizada para o que estão realmente a fazer.

E depois há o terceiro público: A IA

É aqui que tudo se complica e que as plataformas existentes não estão preparadas.

A documentação em 2026 tem três consumidores distintos, não dois:

Escritores que criam e mantêm conteúdos
Leitores que consomem conteúdos visualmente
Sistemas de IA que recuperam, analisam e sintetizam conteúdos de forma programática

Cada um destes públicos necessita de uma interface fundamentalmente diferente para o mesmo conteúdo subjacente.

Os escritores precisam de ferramentas de edição ricas, funcionalidades de colaboração e controlos estruturais. Os leitores precisam de uma apresentação clara e concentrada, com o mínimo de distracções. A IA necessita de resultados estruturados e analisáveis por máquina com metadados explícitos: sinais de atualidade, etiquetas de classificação, endereçamento ao nível do bloco e marcação semântica clara.

Como discutimos em Builders, Not Developers, os intermediários de IA já são o consumidor dominante de documentação para uma parte crescente dos trabalhadores do conhecimento. A pesquisa de desenvolvedores do GitHub de 2024 descobriu que 97% dos desenvolvedores corporativos usaram ferramentas de codificação de IA. Em 2026, [84% dos programadores utilizam regularmente ferramentas de IA] (https://www.index.dev/blog/developer-productivity-statistics-with-ai-tools), sendo que 41% de todo o código é gerado por IA.

Estes sistemas de IA não querem saber da sua barra lateral ou da sua barra de ferramentas. Eles precisam de dados limpos. E uma plataforma que confunde a visão do leitor com a visão do escritor também está a confundir a superfície consumível pela IA com a superfície de criação humana. São três incompatibilidades numa só interface.

Três públicos, três necessidades diferentes] (/blog/img/leitores-escritores-três-audiências.svg)

Como o Rasepi separa as experiências

O Rasepi foi concebido com base no princípio de que criar conteúdos e consumir conteúdos são actividades diferentes que merecem interfaces diferentes.

O ambiente do escritor

Quando está a escrever no Rasepi, obtém um ambiente de criação completo. Edição de texto rico com TipTap, controlos ao nível do bloco, indicadores de estado da tradução, gestão de expiração, ferramentas de colaboração, vistas da estrutura de conteúdos e tudo o que um escritor precisa para criar e manter documentação de alta qualidade.

O escritor vê a maquinaria porque precisa da maquinaria.

O ambiente do leitor

Quando alguém consome um documento Rasepi, vê uma experiência de leitura limpa e focada. Sem chrome de edição. Sem barras de ferramentas. Sem sinais de "pode modificar isto". Apenas o conteúdo, apresentado num esquema optimizado para compreensão e leitura.

O leitor não vê o botão de edição porque não está aqui para editar. Está aqui para aprender algo, seguir um processo ou encontrar uma resposta. A interface respeita essa intenção.

A superfície da IA

Para os consumidores de IA, o Rasepi expõe o conteúdo através de APIs estruturadas com metadados completos. Cada bloco tem a sua pontuação de frescura, estado de tradução, hash de conteúdo e etiquetas de classificação. Os sistemas de IA podem consultar o conteúdo ao nível do bloco, filtrar por frescura, excluir material obsoleto ou de rascunho e obter exatamente os dados estruturados de que necessitam.

Não é preciso raspar uma página wiki e esperar pelo melhor. A IA obtém uma interface criada para o efeito, tal como o leitor e o escritor.

Uma camada de conteúdo, três interfaces

O importante é que não estamos a manter três cópias do conteúdo. Este não é o problema das cinco cópias de integração que discutimos em [Stop Maintaining Five Copies of the Same Document] (/blog/stop-maintaining-five-copies-of-the-same-document/).

Trata-se de uma camada de conteúdo, armazenada como blocos estruturados, servida através de três vistas diferentes optimizadas para três públicos diferentes.

O redator edita os blocos. O leitor vê o conteúdo montado e estilizado. A IA consulta dados estruturados com metadados. Os mesmos blocos. A mesma fonte de verdade. Camada de apresentação diferente para cada consumidor.

Isto só é possível devido à arquitetura ao nível dos blocos. Cada conteúdo é uma unidade individualizável com os seus próprios metadados. Pode apresentar esses blocos de forma diferente, dependendo de quem os está a pedir:

Audiência	Necessidades	Obtém
Ambiente de criação completo com controlos ao nível dos blocos
Leitor**	Texto limpo, hierarquia clara, digitalização rápida	Vista de leitura focada, sem cromo de edição
API a nível de bloco com metadados completos

Porque é que isto é mais importante do que parece

Poderá ler isto e pensar: "É apenas a interface do utilizador. Vistas diferentes da mesma coisa. Quão importante pode ser?"

Muito importante, ao que parece.

Confiança do leitor

As pessoas confiam em conteúdos que parecem publicados. Quando uma página parece um wiki que qualquer pessoa pode editar, os leitores inconscientemente desconfiam dela. Quando o mesmo conteúdo é apresentado numa visualização de leitura limpa e com qualidade de publicação, tem mais autoridade. Isto não é irracional. É um sinal de que alguém levou a apresentação a sério, o que implica que também levou o conteúdo a sério.

O Nielsen Norman Group estudou extensivamente esta questão. A sua [investigação sobre a credibilidade do conteúdo] (https://www.nngroup.com/articles/trust-signals-content/) mostra que a qualidade do design e a apresentação são dos sinais mais fortes em que os utilizadores confiam para avaliar a fiabilidade do conteúdo. Uma vista de editor desordenada prejudica ativamente a credibilidade do conteúdo que apresenta.

Produtividade do escritor

Os escritores que trabalham num ambiente de criação dedicado não têm de alternar entre "estou a ler ou estou a escrever?". As ferramentas estão lá porque é suposto estarem lá, não porque a interface não consegue decidir quem está a olhar para ela.

Fiabilidade da IA

Quando os sistemas de IA têm uma superfície criada para o efeito com metadados estruturados, podem tomar melhores decisões sobre o que recuperar e o que excluir. Podem verificar as pontuações de atualidade antes de incluir um bloco numa resposta. Podem respeitar as etiquetas de classificação. Podem filtrar por idioma, estado ou público. Nada disto é possível quando a IA está a extrair a mesma página HTML que foi concebida para leitores humanos.

A mudança de modelo mental

O pressuposto fundamental da maioria das plataformas de documentação é: a página é a unidade, e toda a gente interage com a página.

O pressuposto do Rasepi é diferente: O pressuposto do Rasepi é diferente: o bloco é a unidade, e diferentes públicos interagem com os blocos através de superfícies criadas para o efeito.

Isto parece uma pequena distinção arquitetónica. Mas não é. É a diferença entre uma ferramenta que mostra acidentalmente conteúdos a sistemas de IA e uma que os serve deliberadamente. Entre um ambiente de escrita que por acaso é legível e uma experiência de leitura que foi concebida de raiz. Entre uma interface suficientemente boa e três excelentes.

A documentação já não é apenas escrita e lida. É escrita, lida, consultada, traduzida, pontuada, classificada e fornecida a sistemas de IA em grande escala. Uma única interface não pode otimizar tudo isso, e fingir que pode é a razão pela qual acabámos com wikis que ninguém quer ler e assistentes de IA a extrair respostas de páginas que nunca foram concebidas para serem consumidas por máquinas.

Os leitores e os escritores estão em modos mentais diferentes. A IA está num modo completamente diferente. A interface deve refletir isso mesmo.

O estado dos documentos em 2026: cinco tendências que definirão a próxima era

2026-04-03T00:00:00Z

De tempos a tempos, reservo uma manhã para ler. Não o código Rasepi, não os problemas do GitHub. Blogs de concorrentes, relatórios do setor, anúncios de palestras, pesquisas com desenvolvedores. O que quer que tenha sido lançado no último trimestre e que tenha a ver com documentação, gestão do conhecimento ou fluxos de trabalho assistidos por IA.

Fiz isso na semana passada, e a imagem que surgiu foi mais nítida do que eu esperava. Não porque um único anúncio tenha sido inovador, mas porque cinco tendências distintas estão a convergir e, quando as alinhamos, elas traçam um quadro muito claro do que as plataformas de documentação terão de fazer nos próximos dois anos.

Eis o que descobri.

1. A IA é o principal leitor agora. Não os humanos.

O GitBook publicou um número impressionante em seu [relatório de dados de documentos de IA] (https://www.gitbook.com/blog/ai-docs-data-2025): A leitura de documentação por IA aumentou mais de 500% em 2025. Quinhentos por cento. Isso não é um erro de arredondamento.

Enquanto isso, o [2024 Developer Survey] do Stack Overflow (https://survey.stackoverflow.co/2024/) mostrou que 61% dos desenvolvedores gastam mais de 30 minutos por dia procurando respostas. Mas a forma como eles pesquisam mudou. A própria pesquisa do GitHub descobriu que 97% dos desenvolvedores corporativos usaram ferramentas de codificação de IA. Até 2026, 84% dos desenvolvedores usam ferramentas de IA diariamente, com 41% do código agora gerado por IA. Estas pessoas não estão a navegar na barra lateral do seu wiki. Estão a perguntar ao Claude ou ao Copilot, e a IA está a ler os seus documentos em nome delas.

A implicação é difícil de exagerar. O seu consumidor mais frequente de documentação já não é uma pessoa com um separador do browser aberto. É um modelo de linguagem que faz chamadas de recuperação. E esse modelo não tem capacidade para olhar para uma página e pensar "hmm, isto parece desatualizado".

O GitBook apercebeu-se disso cedo e respondeu com o seu relatório State of Docs 2026 e um impulso para formatos legíveis por máquinas. Também lançaram o skill.md, uma convenção para estruturar informações sobre produtos especificamente para agentes de IA. A Google foi mais longe com o seu Gemini API Docs MCP, que liga os agentes de codificação à documentação atual através do Protocolo de Contexto de Modelo. O seu raciocínio foi explícito: os agentes geram código desatualizado porque os seus dados de treino têm uma data limite. A correção do MCP elevou a taxa de aprovação da avaliação para 96,3%.

Portanto, a primeira tendência está estabelecida. A IA é o leitor principal. As plataformas que tratarem este facto como uma restrição de conceção fundamental, e não como uma funcionalidade a acrescentar mais tarde, terão uma vantagem estrutural.

2. A frescura e os metadados de confiança estão a tornar-se obrigatórios

A Anthropic entrevistou 81.000 utilizadores do Claude em dezembro de 2025 e publicou os resultados em março de 2026. É o maior estudo qualitativo de utilizadores de IA alguma vez realizado (159 países, 70 línguas). A preocupação mais citada? A falta de fiabilidade. 27% dos inquiridos indicaram-na como a sua principal preocupação, e 79% dessas pessoas tinham-na experimentado em primeira mão.

Este número deveria deixar qualquer equipa de documentação acordada à noite.

Quando as respostas da IA não são fiáveis, o problema nem sempre é o modelo. Muitas vezes, o modelo está a reproduzir fielmente o que encontrou num documento obsoleto. O modelo não alucinou. Os seus documentos estavam simplesmente errados e ninguém os assinalou.

Os dados do Stack Overflow reforçam isso de um ângulo diferente: 81% dos programadores esperam que a IA seja mais integrada na forma como documentam o código no próximo ano. Se 81% dos seus utilizadores estão a fornecer documentos à IA, e 27% dos utilizadores de IA dizem que a falta de fiabilidade é o maior problema, tem um problema de confiança que nenhuma quantidade de engenharia rápida resolve. A correção está na fonte.

É por isso que os metadados de atualidade são importantes. Não os carimbos de data/hora da "última edição" (estes dizem-nos quando alguém tocou no ficheiro, não se o conteúdo ainda está correto). Frescura real: estado da revisão, saúde da ligação, alinhamento da tradução, sinais de leitura, deteção de desvios de conteúdo. Metadados que uma máquina pode ler e utilizar para decidir se um documento é seguro para citar.

Estou sempre a voltar a um enquadramento simples. A sua documentação precisa de uma pontuação de crédito. Não um registo de data e hora. Uma pontuação de crédito. (Temos estado a construir exatamente isto com o [sistema de pontuação de frescura] do Rasepi(/features/freshness) e, honestamente, ver os dados da indústria só me deixa mais convencido de que é a decisão certa).

3. A tradução está a passar de "projeto" para "pipeline"

DeepL publicou um artigo em fevereiro intitulado ["The 6 Translation Transformations Global Businesses Can't Afford to Miss"] (https://www.deepl.com/en/blog/six-translation-transformations). O seu argumento: a tradução está a tornar-se um desafio operacional contínuo e não um projeto de lote que se realiza trimestralmente.

Isto está de acordo com tudo o que vejo.

O modelo antigo era simples. Escrever em inglês. Quando se tem orçamento, contrata-se um tradutor ou recorre-se a um serviço. Receber as traduções. Carregue-as. Está feito até à próxima vez. O problema é que a "próxima vez" chega cada vez mais depressa quando o seu produto é enviado semanalmente e os seus documentos são actualizados constantemente. Na altura em que a versão alemã volta da revisão, a versão inglesa já foi alterada duas vezes.

O [Customization Hub] (https://www.deepl.com/customization-hub) do próprio DeepL agora oferece glossários, regras de estilo e configurações de formalidade, o que é ótimo. Mas se essas ferramentas estiverem fora da sua plataforma de documentação, está a gerir uma cadeia de ferramentas de tradução: editor, exportar, traduzir, rever, reimportar, repetir. Cada passo é uma oportunidade para se desviar.

O Notion não tem suporte multilingue nativo. O Confluence oferece-o através de plugins do mercado. O GitBook adicionou a tradução automática em agosto de 2025, que é um passo, mas funciona ao nível da página.

A verdadeira mudança é do nível da página para o nível do bloco. Quando se controlam as traduções ao nível do parágrafo, só se retraduz o que realmente mudou. Uma edição típica afecta talvez dois parágrafos em quarenta. Isso representa 94% menos trabalho de tradução. (Esta é a arquitetura de tradução principal do Rasepi e, honestamente, a coisa de que mais me orgulho no produto. Mas mesmo deixando-nos de lado, a direção da indústria é clara: tradução contínua, incremental e incorporada é para onde isto se dirige).

4. Os agentes de IA precisam de conteúdo estruturado, não de páginas wiki

Esta questão cristalizou-se para mim quando a Notion anunciou [Custom Agents] (https://www.notion.com/blog/introducing-custom-agents) em fevereiro. 21.000 agentes construídos durante o acesso antecipado. Agentes que respondem a perguntas de bases de conhecimento, encaminham tarefas, compilam relatórios de estado. Só o Ramp tem mais de 300 agentes.

A Atlassian seguiu uma direção semelhante. A Rovo AI in Confluence extrai contexto de toda a Atlassian e de aplicações de terceiros para gerar conteúdo. A sua proposta: "conteúdo rico em contexto e de alta qualidade baseado no trabalho existente da sua equipa".

E depois a Anthropic lançou equipas de agentes no Claude Code, onde vários agentes de IA se coordenam autonomamente em tarefas complexas. O Opus 4.6 tem uma pontuação de 76% no benchmark MRCR de 1M com 8 agulhas (acima dos 18,5% do modelo anterior), o que significa que pode realmente recuperar informações enterradas em grandes conjuntos de documentos sem perder o rasto.

As três empresas estão a criar agentes que consomem documentação. Nenhuma delas resolveu o problema da qualidade da fonte.

A documentação dos agentes personalizados da Notion reconhece explicitamente o [risco de injeção imediata] (https://www.notion.com/blog/introducing-custom-agents) quando os agentes lêem conteúdo não confiável. O Rovo da Atlassian pega tudo o que encontra no seu Confluence. Se esse conteúdo estiver três meses desatualizado, o Rovo não sabe. Ele se baseia nele de qualquer maneira.

Para que os agentes trabalhem de forma confiável, eles precisam de mais do que páginas de texto. Precisam de conteúdo estruturado com identificadores estáveis, sinais de atualização explícitos, metadados de classificação claros e a capacidade de distinguir "isto é atual e revisto" de "isto existe mas ninguém lhe toca há um ano". As páginas Wiki não oferecem isso. O conteúdo estruturado ao nível do bloco com metadados de confiança fornece-o.

5. O código aberto e a auto-hospedagem estão a regressar

Este último é mais um pressentimento apoiado por dados do que um anúncio único.

GitBook open-sourced sua documentação publicada no final de 2024 e lançou um fundo OSS. O seu raciocínio: os projectos de código aberto merecem ferramentas de documentação gratuitas e de alta qualidade. Mas o movimento também sinaliza algo mais amplo.

O Notion é apenas na nuvem. Não há opção de auto-hospedagem. O Confluence Data Center existe, mas requer uma licença. Quando a sua plataforma de documentação contém o seu conhecimento operacional mais sensível (manuais de incidentes, procedimentos de conformidade, decisões de arquitetura), a questão de "quem controla estes dados?" não é abstrata.

O post do Anthropic "Claude is a space to think" de fevereiro apresentou um argumento interessante sobre confiança e modelos de negócio. A sua alegação principal: os incentivos publicitários são incompatíveis com um assistente de IA genuinamente útil. Optaram por não ter publicidade para que os utilizadores possam confiar na ferramenta.

Penso que existe um paralelo para as plataformas de documentação. Se o seu sistema de documentação é de código fechado e apenas na nuvem, não pode verificar o que alimenta a IA. Não é possível auditar os cálculos de atualização. Não pode garantir que os seus dados permaneçam sob o seu controlo. Para as equipas que estão a implementar assistentes de IA sobre a sua base de conhecimentos (e cada vez mais, todos o fazem), a auditabilidade é importante.

Esta não é uma polémica sobre o código aberto ser moralmente superior. Os produtos de código fechado podem ser absolutamente fiáveis. Mas quando se está a construir fluxos de trabalho com IA em cima da documentação interna, a capacidade de inspecionar e verificar o sistema é uma vantagem prática. Para nós, o licenciamento do Rasepi pelo MIT não foi uma reflexão tardia. Foi uma decisão de design baseada na mesma lógica: a infraestrutura de documentação deve ser auditável.

O que estas cinco tendências significam em conjunto

Individualmente, cada uma dessas tendências é gerenciável. A IA lê os seus documentos? Muito bem, adicione alguns metadados legíveis por máquina. A atualidade é importante? Ótimo, adicione datas de revisão. A tradução precisa de ser contínua? Claro, integre DeepL. Os agentes precisam de estrutura? É justo, melhore o seu modelo de conteúdos. A soberania é importante? Ótimo, ofereça uma opção auto-hospedada.

Mas, em conjunto, descrevem uma plataforma que é fundamentalmente diferente da que a maioria das equipas utiliza atualmente.

A diferença é arquitetónica. Não se trata de cinco funcionalidades que se acrescentam. São cinco pressupostos que precisam de ser incorporados na base. Como o conteúdo é armazenado (a nível de bloco, não a nível de página). Como a confiança é modelada (pontuações de frescura, não carimbos de data/hora). Como funciona a tradução (incremental, incorporada, por parágrafo). Como é que os agentes de IA acedem ao conteúdo (APIs estruturadas com metadados, e não scrapes de páginas). Como é que os dados são controlados (abertos, auditáveis, auto-hospedados).

Nenhuma plataforma estabelecida foi concebida em torno de todos estes cinco aspectos em simultâneo. Algumas estão a adicioná-los peça a peça. O GitBook está a avançar mais rapidamente na frente da legibilidade da IA. A Notion está a construir uma infraestrutura de agentes. A Atlassian tem uma distribuição empresarial.

Mas projetar para todos os cinco desde o primeiro dia? Essa é a vantagem de começar do zero quando o terreno muda.

Sei que estou a ser parcial. Construímos o Rasepi especificamente porque vimos estas tendências a convergir e queríamos uma plataforma que assumisse todas elas desde o início. Tradução ao nível do bloco, expiração forçada, pontuação de frescura, conteúdo estruturado pronto para IA, código aberto. É a tese de todo o projeto.

Mas mesmo que não existíssemos, penso que qualquer leitura honesta do que aconteceu no primeiro trimestre de 2026 aponta na mesma direção. A documentação está a tornar-se infraestrutura. E as infra-estruturas têm requisitos diferentes das páginas wiki.

As equipas que descobrirem isto primeiro não terão apenas melhores documentos. Terão agentes de IA mais fiáveis, custos de tradução mais baixos, menos surpresas de conformidade e bases de conhecimento que se mantêm fiáveis ao longo do tempo.

Esse é o estado dos documentos em 2026. A questão não é se essas tendências são reais. É saber se a sua plataforma foi concebida para elas.

Cinco tendências. Uma questão de arquitetura: a sua plataforma de documentação foi concebida para 2026 ou continua a servir pressupostos de 2016?

Fontes: GitBook AI docs data report, GitBook State of Docs 2026, GitBook skill.md, Google Gemini API Docs MCP, Stack Overflow 2024 Developer Survey, GitHub 2024 developer survey, Index.dev developer productivity statistics, Anthropic "What 81,000 People Want from AI", Anthropic "Claude is a space to think", Claude Opus 4.6, Notion Custom Agents, Atlassian Rovo in Confluence, DeepL "6 Translation Transformations", DeepL Customization Hub, GitBook open source documentation, GitBook auto-translate.

Construtores, não desenvolvedores: Como a Claude mudou para quem são os seus documentos

2026-04-02T00:00:00Z

Há uma pessoa neste momento, algures, a integrar a sua API. Ela não está no seu site de documentação. Não abriu o seu guia de iniciação. Nunca viu o seu playground interativo ou a navegação cuidadosamente concebida na barra lateral.

Eles estão sentados no Claude. Ou no Copilot. Ou Cursor. Escreveram algo como "integrar a API de faturação Stripe com a minha aplicação Next.js utilizando o router de aplicações" e esperaram que o código de trabalho voltasse. A IA lia os seus documentos em nome deles. Encontrou os endpoints relevantes, compreendeu o fluxo de autenticação, escolheu os métodos SDK corretos e produziu uma implementação.

Há duas semanas, na Start Summit Hackathon em St. Gallen, vi isto acontecer em tempo real. Estava a falar com um grupo de estudantes de Ciências da Computação e com alguns fundadores de startups em fase inicial sobre a forma como abordam as novas API, e todos eles descreveram o mesmo fluxo de trabalho: colar o problema numa IA, receber o código de volta, iterar a partir daí. Uma das alunas riu-se quando lhe perguntei se tinha lido os documentos. "Porque é que eu havia de ler? O Claude lê-os por mim".

A pessoa nunca visitou o seu sítio. Pode ser que nunca visite o seu site. E é cada vez mais assim que o software é construído.

A principal mudança

A documentação tem agora dois consumidores fundamentalmente diferentes: os humanos que a lêem e os assistentes de IA que a lêem em nome dos construtores. A maior parte da documentação é optimizada exclusivamente para humanos. A IA já é o leitor dominante.

Isto muda tudo a jusante:

Quando uma IA serve conteúdos obsoletos, o construtor não tem forma de detetar o problema. Os danos são silenciosos.
Os gestores de produto, designers e analistas estão a enviar software através de assistentes de IA, muitas vezes sem nunca terem lido uma linha de documentação.
A estrutura legível pela máquina é mais importante do que o design visual. O markdown limpo, os blocos autónomos e os metadados explícitos são o que permite à IA representar o seu produto com precisão.
Os requisitos de formato dividiram-se.** Os leitores humanos precisam de narrativa. Os intermediários de IA precisam de especificações estruturadas e analisáveis. É necessário servir ambos.

O resto deste post revela como chegamos aqui, o que isso significa para o DevRel e o que você pode fazer sobre isso agora.

A viagem que ninguém planeou

Durante muito tempo, as relações com os programadores seguiram um caminho bem compreendido. Você escreveu uma documentação abrangente. Publicou guias de início rápido. Dava palestras em conferências. Mantinha uma presença no Stack Overflow. Tornou a referência da sua API pesquisável, os seus SDKs idiomáticos, as suas mensagens de erro úteis.

Esse caminho pressupõe que o desenvolvedor lerá seu conteúdo. Navegar na sua estrutura. Seguir os seus passos.

A pesquisa de desenvolvedores do GitHub de 2024 descobriu que 97% dos desenvolvedores corporativos já usaram ferramentas de codificação de IA em algum momento. [A pesquisa anual do Stack Overflow] (https://survey.stackoverflow.co/2024/) mostrou que 76% de todos os desenvolvedores estão usando ou planejando usar ferramentas de IA, com 62% dos profissionais usando-as ativamente no dia a dia. Em 2026, esse número subiu para 84%, com 41% de todo o código agora gerado por IA e 51% dos desenvolvedores profissionais usando ferramentas de IA diariamente. Estes números não estão a abrandar.

A nova viagem tem um aspeto diferente. Alguém descreve o que pretende em linguagem natural. Um assistente de IA lê a documentação, encontra as secções relevantes e gera a integração. O construtor revê o resultado, talvez refine o pedido, talvez faça um seguimento. Minutos, não horas.

O funil de arranque que as equipas DevRel passaram anos a aperfeiçoar? Está a ser contornado. Não por ser mau. O ponto de entrada simplesmente mudou.

Dois consumidores, um conjunto de documentos

A documentação tem agora dois públicos fundamentalmente diferentes.

O primeiro é o leitor humano. Esta pessoa ainda existe. Aparece para tomar decisões de arquitetura, depurar casos extremos, analisar a conformidade e compreender conceitos. Quer explicações narrativas, material de referência bem organizado e um raciocínio claro sobre as soluções de compromisso.

O segundo é o intermediário de IA. Este lê a sua documentação em nome de um construtor. Não se preocupa com a sua barra lateral. Não aprecia o seu design visual. Precisa de conteúdo estruturado e analisável por máquina: markdown limpo, formatação consistente, especificações explícitas sobre as quais possa raciocinar sem ambiguidade.

Atualmente, quase todos os sítios de documentação são optimizados exclusivamente para o primeiro público. O segundo público já é o consumidor dominante.

Jeremy Howard identificou esta tensão quando [propôs a norma /llms.txt] (https://llmstxt.org/) em 2024. A sua observação foi precisa: "Os grandes modelos linguísticos dependem cada vez mais de informações de sítios Web, mas enfrentam uma limitação crítica: as janelas de contexto são demasiado pequenas para lidar com a maioria dos sítios Web na sua totalidade." A proposta é simples. Um ficheiro markdown com curadoria em /llms.txt que dá aos modelos de IA uma visão geral estruturada do seu produto e ligações para os recursos mais importantes. FastHTML, os próprios documentos do Anthropic e um [diretório crescente de projectos] (https://llmstxt.site/) já têm um.

É uma convenção útil. Mas é também um sintoma de um problema mais profundo. O verdadeiro problema não é o formato. É o facto de a maior parte da documentação nunca ter sido concebida tendo em mente o consumo por parte das máquinas.

O construtor não está a cortar nos cantos

Existe a tentação de olhar para a pessoa que pede Claude em vez de ler a documentação e concluir que ela está a tomar atalhos. Que ela não entende realmente o que está acontecendo no código. Que ela é, de alguma forma, um desenvolvedor inferior.

Já tive esta conversa vezes suficientes para saber que isso é normalmente errado.

Muitos destes construtores são engenheiros sénior que fazem escolhas deliberadas de eficiência. Eles entendem o código, só não querem navegar por quatro páginas de documentação para encontrar as três linhas de que realmente precisam. Eles aprenderam que um assistente de IA pode extrair essas linhas mais rápido do que eles podem procurar por elas, então eles delegam a leitura. (Honestamente, eu próprio faço isto. Não me lembro da última vez que li um guia de iniciação de cima a baixo).

A Anthropic reconheceu este padrão quando construiu o [Model Context Protocol] (https://modelcontextprotocol.io/introduction). O MCP é agora suportado pelo Claude, ChatGPT, VS Code, Cursor, entre outros. Foi explicitamente concebido para que os assistentes de IA possam aceder a sistemas externos, obter contexto e agir com base nele. A especificação descreve-a como fornecendo "acesso a um ecossistema de fontes de dados, ferramentas e aplicações que irão aumentar as capacidades e melhorar a experiência do utilizador final".

Leia isto com atenção. É uma linguagem de infraestrutura, não de conveniência. Os construtores que utilizam estas ferramentas não estão a evitar o trabalho. Estão a trabalhar através de uma nova camada, e a sua documentação faz parte dessa camada, quer a tenha concebido ou não.

Os números confirmam isso. Só o Claude lida agora com [25 mil milhões de chamadas de API por mês] (https://www.incremys.com/en/resources/blog/claude-statistics), com 30 milhões de utilizadores activos mensais em 159 países. 70% das empresas da Fortune 100 usam o Claude. De acordo com um inquérito da Menlo Ventures, a Anthropic detém 32% da quota de mercado da IA empresarial por utilização de modelos, à frente da OpenAI com 25%. Um relatório de investigação do HSBC coloca esse valor ainda mais alto: 40% do total de despesas com IA. Não se trata de ferramentas experimentais. São infra-estruturas primárias.

As relações com os programadores foram criadas para uma era diferente

Se a sua estratégia DevRel foi concebida antes de 2023, foi concebida para um mundo onde os programadores liam os documentos diretamente. Esse mundo não desapareceu, mas já não é o padrão de interação dominante para uma parte crescente dos criadores.

Isto altera o cálculo de várias actividades DevRel de longa data.

**Uma apresentação de 45 minutos numa conferência de programadores chega a uma sala com algumas centenas de pessoas. Um ficheiro /llms.txt bem estruturado e uma documentação limpa e legível por máquina chegam a todos os construtores que perguntam a qualquer assistente de IA sobre o seu produto, continuamente, em qualquer altura. A palestra é um evento único. A documentação legível por máquina é composta. Não estou a dizer que as conferências não têm valor (acabei de regressar de uma, literalmente), mas a equação de alavancagem mudou.

**O clássico tutorial de início rápido em cinco passos é cada vez mais uma formalidade. O construtor não segue passos. Descrevem o que pretendem e esperam que a IA produza a integração. Se a API estiver bem documentada num formato de fácil utilização, a IA trata da experiência de arranque de forma mais eficiente do que qualquer tutorial poderia fazer. Em vez disso, os tutoriais devem tornar-se material concetual: explicar por que razão se deve escolher a abordagem A em vez da abordagem B. A IA pode gerar a implementação. É muito menos fiável a explicar as soluções de compromisso.

**Os dados do seu próprio inquérito mostraram que 84% dos programadores utilizam a documentação técnica diretamente, sendo que 90% destes confiam na documentação contida nos pacotes API e SDK. Mas a forma como acedem a esses documentos é cada vez mais através de uma camada de IA e não de um separador do browser. As perguntas que ainda chegam ao Stack Overflow tendem a ser as mais difíceis. Casos extremos, depuração de produção, coisas que exigem nuances. Valiosas, com certeza. Mas já não é onde está o volume.

Quando a IA lê os seus documentos, a atualidade torna-se crítica

Aqui está a parte em que a maioria das equipas não pensou.

Quando um ser humano lê uma página de documentação, ele pode fazer um julgamento. Pode reparar que as capturas de ecrã parecem antigas, ou que um comentário no final diz que o processo mudou. Podem olhar para ela e pensar "isto parece desatualizado".

Um assistente de IA não pode fazer nada disso. Lê o texto, processa-o como um facto e gera uma resposta com total confiança. Se a documentação descrever um ponto final obsoleto, a IA recomendará alegremente a integração com ele. Se a documentação fizer referência a uma infraestrutura que foi substituída há seis meses, a IA descreverá a configuração antiga como atual. Sem hesitação.

E aqui está o que torna isto pior do que parece: 66% dos programadores já afirmam que o maior problema das ferramentas de IA é o facto de darem resultados que estão "quase certos, mas não totalmente". A documentação obsoleta contribui diretamente para esse problema. A IA não está a alucinar. Está a reproduzir fielmente conteúdo desatualizado, e não há forma de o construtor perceber a diferença.

O construtor confia na IA. A IA confia na documentação. Se a documentação estiver desactualizada, essa cadeia de confiança dá uma resposta seguramente errada.

Isto sempre foi um problema, obviamente. Os conteúdos obsoletos sempre confundiram as pessoas. Mas os danos foram contidos porque os leitores humanos podiam, por vezes, detectá-los. Os intermediários de IA não conseguem. Amplificam os conteúdos obsoletos, fornecendo-os em grande escala, com autoridade, a pessoas que não têm motivos para duvidar deles.

A atualidade já não é uma questão de qualidade do conteúdo. É um problema de fiabilidade para todos os fluxos de trabalho alimentados por IA que tocam nos seus documentos.

A palavra "programador" é demasiado restrita

As pessoas que estão a criar software em 2026 não se identificam todas como programadores. Alguns são designers que pedem ao Claude para construir um protótipo funcional. Alguns são gestores de produto que utilizam o Cursor para enviar ferramentas internas. Outros são analistas de dados que descrevem um pipeline de dados em linguagem natural e deixam um agente montá-lo. Na Start Summit, metade das equipas da hackathon tinha membros sem qualquer experiência em programação que, no final do fim de semana, já estavam a enviar software funcional.

A Ramp é um exemplo útil. A empresa fintech passou de uma avaliação de US $ 5.8 bilhões em 2023 para [US $ 32 bilhões no final de 2025] (https://techcrunch.com/2025/11/17/ramp-hits-32b-valuation-just-three-months-after-hitting-22-5b/), ultrapassando US $ 1 bilhão em receita anualizada ao longo do caminho. Uma das startups de crescimento mais rápido da história. Uma parte amplamente discutida de sua abordagem: gerentes de produto construindo recursos diretamente com ferramentas de IA em vez de esperar em um backlog de engenharia. Os PMs da Ramp não se limitam a escrever especificações. Eles enviam o código. A IA trata da implementação. O PM lida com a intenção.

Não é um atalho. Trata-se de um novo modelo operacional, que está a funcionar a uma escala que torna muito difícil descartá-lo como uma experiência.

O próprio estudo interno da Anthropic é revelador. Quando eles [entrevistaram 132 de seus próprios engenheiros] (https://fortune.com/2025/12/02/how-anthropics-safety-first-approach-won-over-big-business-and-how-its-own-engineers-are-using-its-claude-ai/) sobre como eles usam o Claude, os engenheiros relataram usá-lo para cerca de 60% de suas tarefas de trabalho. As utilizações mais comuns? Depurar código existente, compreender o que partes da base de código estavam a fazer e implementar novas funcionalidades. Os engenheiros afirmaram que tendem a entregar ao Claude tarefas que "não são complexas, repetitivas, em que a qualidade do código não é crítica". E 27% do trabalho que agora fazem com o Claude simplesmente não teria sido feito antes.

Esta é a própria equipa da Anthropic. As pessoas que construíram o modelo estão a usá-lo como um leitor de documentação, um navegador de base de código e um gerador de primeiro rascunho. Todos os outros estão a fazer o mesmo, apenas com os seus documentos em vez dos deles.

A Anthropic foi deliberada em chamar isso de persona "construtora". As suas ferramentas foram concebidas não apenas para engenheiros de software profissionais, mas para qualquer pessoa que consiga descrever o que pretende construir. Quando Claude pode criar uma aplicação full-stack a partir de um design Figma via MCP, a linha tradicional entre "desenvolvedor" e "não desenvolvedor" se dissolve.

Isso tem implicações reais para qualquer pessoa que mantenha documentação ou se preocupe com a experiência do desenvolvedor. O seu público já não se limita às pessoas que sabem o que é um ponto de extremidade REST. Ele inclui qualquer pessoa cujo assistente de IA possa interagir com seu produto. O PM da Ramp que envia um recurso usando sua API? Provavelmente nunca lerá a sua documentação diretamente. O agente de IA deles lerá com certeza.

O que isso significa para a documentação

Se a documentação serve agora dois públicos, leitores humanos e intermediários de IA, precisa de funcionar para ambos. Parece óbvio. Na prática, quase ninguém o faz.

Eis o que eu acho que realmente importa:

**Se os documentos da sua API são uma página HTML lindamente renderizada que um LLM tem que raspar e analisar, a IA está a trabalhar mais do que deveria. Envie a especificação OpenAPI em bruto juntamente com a versão renderizada. Enviar markdown limpo. Tornar as especificações acessíveis sem exigir que a IA interprete o layout da página.

**Estrutura ao nível do bloco em vez de narrativa ao nível da página. Os assistentes de IA não consomem documentação página a página. Extraem as secções relevantes. Um documento com títulos claros, parágrafos autónomos e semântica explícita ao nível do bloco é muito mais útil para uma IA do que uma narrativa fluida que requer a leitura de toda a página para obter o contexto.

**Quando é que este documento foi revisto pela última vez? Ainda é atual? O conteúdo foi assinalado? Estes sinais têm de existir numa forma a que a IA possa aceder, e não apenas como sinais visuais numa página Web. Uma pontuação de atualidade, um estado de expiração, uma data de revisão, são os metadados que permitem a uma IA decidir se um documento é seguro para ser utilizado como fonte.

**Quando um assistente de IA fornece a um construtor uma resposta confiante baseada num ponto final obsoleto, os danos são piores do que um 404. O construtor constrói sobre ele. Faz o envio. Depois, ele quebra na produção e ninguém sabe o motivo até que alguém rastreie a documentação que deveria ter sido atualizada meses atrás. Cada documento que uma IA possa referenciar precisa de um mecanismo para provar que ainda está atualizado. (Isto é, revelação completa, exatamente o problema que estamos a construir para resolver com o Rasepi. Forçar a expiração de blocos de documentação para que o conteúdo obsoleto não se possa esconder).

Começando: audite sua documentação atual

Se leu até aqui e está a pensar "ok, mas o que é que eu faço na segunda-feira?", aqui estão quatro coisas concretas que pode verificar esta semana.

**1. Abra o Claude ou o ChatGPT e peça-lhe para integrar o seu produto num cenário realista. Não utilize os seus conhecimentos internos. Veja apenas o que a IA produz. Está correto? Está actualizada? Está a utilizar os pontos finais corretos, a versão correta do SDK, o fluxo de autenticação correto? Se a IA estiver errada, é isso que os construtores estão a receber neste momento.

**2. Escolha as cinco páginas de documentação mais visitadas e pergunte: quando foi a última revisão? Ainda descreve o estado atual do produto? Se não conseguir responder a esta pergunta com confiança, a IA também não conseguirá. Esta é a correção mais importante para a maioria das equipas.

3. Envie formatos legíveis por máquina Se você não tem um arquivo /llms.txt, crie um. Se a sua referência de API estiver disponível apenas como HTML renderizado, exporte a especificação OpenAPI bruta e torne-a acessível. Se os seus documentos estão num CMS que não produz markdown limpo, esse é um problema que vale a pena resolver agora.

4. Adicione datas de revisão e metadados de atualização. Mesmo algo simples, um campo last-reviewed em seu sistema de gerenciamento de conteúdo, um ciclo de revisão obrigatório para páginas de alto tráfego. Isto dá aos humanos e à IA um sinal sobre se o conteúdo é fiável. Ferramentas como o Rasepi podem automatizar isto com expiração forçada ao nível do bloco, mas mesmo um processo manual é melhor do que nada.

A mudança silenciosa na forma como os produtos são representados

Há uma consequência mais ampla de tudo isto que vale a pena referir diretamente.

A sua documentação já não é apenas um manual de referência para os programadores. É o material de origem que os assistentes de IA utilizam para representar o seu produto para o mundo. Quando um construtor pergunta ao Claude como utilizar o seu produto, a resposta do Claude é moldada por tudo o que consegue encontrar e analisar na sua documentação.

Bons documentos, boa resposta. Desactualizados, ambíguos, fechados em HTML que é difícil de analisar por um modelo? Pior resposta, ou uma resposta incorrecta. Tão simples quanto isso.

A qualidade da resposta da IA sobre o seu produto é agora um indicador direto da experiência do programador. A maioria das empresas ainda não está a tratar isso dessa forma.

As equipas que estão à frente nesta matéria, Stripe, Vercel, Cloudflare, Anthropic, tratam a legibilidade da IA como uma preocupação de primeira classe. Um requisito fundamental que molda a forma como a documentação é escrita, estruturada e mantida. Não é um item do backlog para o próximo trimestre.

O construtor sentado no Claude neste momento, descrevendo o que quer construir, esperando um código funcional em minutos. Talvez nunca mais volte a visitar um sítio de documentação. Mas a IA que os serve fá-lo-á. Constantemente.

Essa IA é agora o seu leitor mais frequente. A questão é saber se os seus documentos estão preparados para isso.

A melhor estratégia de experiência do programador em 2026 não é uma palestra numa conferência ou um guia de início rápido. É garantir que a IA o faz corretamente.

Este post faz referência a pesquisas e documentação de produtos disponíveis publicamente. As estatísticas são extraídas do Inquérito aos programadores do GitHub de 2024, do Inquérito aos programadores do Stack Overflow de 2024, do Relatório de produtividade dos programadores do Index.dev de 2026, das Estatísticas da Incremys Claude e do Relatório da Fortune sobre o Anthropic. A especificação /llms.txt é mantida em llmstxt.org. O Protocolo de Contexto de Modelo está documentado em modelcontextprotocol.io.

Por dentro do mecanismo de tradução: Glossários, Regras de Estilo e Retradução Inteligente

2026-03-31T00:00:00Z

O nosso post de arquitetura anterior cobriu plugins, guardas de ação e o sistema de pipeline. Este vai mais fundo no motor de tradução, a parte que eu acho que torna o Rasepi fundamentalmente diferente de qualquer outra plataforma de documentação.

Não é o discurso de marketing sobre traduzir parágrafos em vez de páginas. O código real. Como os glossários são resolvidos por locatário, como as regras de estilo do DeepL e as instruções personalizadas moldam cada tradução, como o hashing de conteúdo impulsiona a deteção de desatualização e como o orquestrador decide quais blocos devem ser retraduzidos.

A linha de tradução

Quando um utilizador guarda um documento, o sistema não se limita a retraduzir tudo. Ele executa uma sequência bastante específica:

Analisa o JSON do TipTap em blocos individuais
Compara hashes de conteúdo para detetar quais blocos foram realmente alterados
Para blocos alterados, resolver o glossário do locatário e a lista de regras de estilo para o par de idiomas
Aplicar regras de estilo, instruções personalizadas e formalidade da configuração do locatário
Enviar apenas blocos modificados para DeepL
Atualizar os blocos de tradução e sincronizar os hashes de conteúdo

Cada passo é o seu próprio serviço com a sua própria interface. Isso é importante porque qualquer etapa pode ser trocada por outra coisa, um fornecedor de tradução diferente, um algoritmo de hashing diferente, uma fonte de glossário diferente.

Resolução do glossário: com escopo do locatário, sincronizado com DeepL

DeepL glossários têm uma restrição que a maioria das pessoas não conhece: eles são imutáveis. Você não pode editar um glossário DeepL. Qualquer mudança significa apagar o antigo e criar um novo.

O Rasepi lida com isto tratando a base de dados como a fonte da verdade e os DeepL glossários como artefactos descartáveis em tempo de execução. A entidade TenantGlossary armazena tudo localmente:

public class TenantGlossary : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }     // e.g. "en"
    public string TargetLanguage { get; set; }     // e.g. "de"
    public string? DeepLGlossaryId { get; set; }   // Runtime DeepL ID
    public DateTime? LastSyncedAt { get; set; }
    public bool IsDirty { get; set; } = true;      // Triggers re-sync
    public ICollection<TenantGlossaryEntry> Entries { get; set; }
}

Quando um utilizador adiciona uma entrada no glossário, por exemplo, mapeando "Sprint Review" para "Sprint-Überprüfung" para EN→DE, o registo da base de dados é atualizado imediatamente e IsDirty é definido para true. O glossário DeepL não é recriado imediatamente. Ele é recriado preguiçosamente, na próxima vez que uma tradução realmente precisar dele.

O fluxo de sincronização

Antes de cada chamada de tradução, o sistema resolve o glossário:

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage,
    CancellationToken ct = default)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage, ct);

    if (glossary is null || glossary.Entries.Count == 0)
        return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty - delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var deepLGlossary = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = deepLGlossary.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return glossary.DeepLGlossaryId;
}

Três coisas dignas de nota aqui:

Sincronização preguiçosa Nós só acessamos a API DeepL quando uma tradução é realmente necessária. A edição de entradas do glossário em massa não desencadeia dezenas de chamadas à API.
**A consulta é executada através de filtros de consulta global EF, então TenantGlossaries é automaticamente escopo. As entradas do glossário do locatário A nunca entram nas traduções do locatário B.
Um glossário por par de línguas DeepL impõe isto de qualquer forma. Um glossário EN→DE, um glossário EN→FR, e assim por diante. O par (SourceLanguage, TargetLanguage) é único por locatário.

Entradas do glossário

As entradas individuais são apenas mapeamentos de termos:

public class TenantGlossaryEntry
{
    public Guid Id { get; set; }
    public Guid GlossaryId { get; set; }
    public string SourceTerm { get; set; }   // e.g. "Sprint Review"
    public string TargetTerm { get; set; }   // e.g. "Sprint-Überprüfung"
}

A API oferece-lhe CRUD completo e importação/exportação de CSV para gestão em massa:

POST   /admin/glossaries                       Create glossary
POST   /admin/glossaries/{id}/entries           Add term
PUT    /admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /admin/glossaries/{id}/import            Import CSV
GET    /admin/glossaries/{id}/export            Export CSV
POST   /admin/glossaries/{id}/sync              Force DeepL sync

A importação de CSV é muito útil para equipas que migram de sistemas de memória de tradução existentes. Exporte os seus termos, limpe-os, importe-os para o Rasepi, e a próxima tradução usa o novo glossário automaticamente.

Regras de estilo, instruções personalizadas e formalidade

Os glossários lidam com a terminologia. Mas a terminologia é apenas metade da questão. Uma tradução pode usar todas as palavras corretas e ainda assim soar mal. Tom errado, formato de data errado, convenções de pontuação erradas.

A ** API de regras de estilo** (v3) do DeepL resolve este problema. É possível criar listas de regras de estilo reutilizáveis que combinam dois tipos de controlos:

Regras configuradas, convenções de formatação predefinidas para datas, horas, pontuação, números e muito mais
Instruções personalizadas, diretivas de texto livre que moldam o tom, o fraseado e as convenções específicas do domínio

O Rasepi cria e gere estas instruções por inquilino, por idioma de destino. A entidade TenantStyleRuleList armazena o DeepL style_id juntamente com as regras configuradas e as instruções personalizadas do locatário:

public class TenantStyleRuleList : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string TargetLanguage { get; set; }      // e.g. "de"
    public string? DeepLStyleId { get; set; }       // Runtime DeepL style_id
    public string ConfiguredRulesJson { get; set; }  // Serialized configured rules
    public bool IsDirty { get; set; } = true;
    public DateTime? LastSyncedAt { get; set; }
    public ICollection<TenantCustomInstruction> CustomInstructions { get; set; }
}

Criar listas de regras de estilo

Quando um administrador define regras de tradução para alemão, o Rasepi chama a API v3 do DeepL para criar a lista de regras de estilo. Aqui está o que parece:

public async Task<string> CreateOrSyncStyleRuleListAsync(
    TenantStyleRuleList ruleList, CancellationToken ct = default)
{
    if (!ruleList.IsDirty && ruleList.DeepLStyleId is not null)
        return ruleList.DeepLStyleId;

    // DeepL style rule lists are mutable - we can update in place
    if (ruleList.DeepLStyleId is not null)
    {
        // Replace configured rules on existing list
        await _httpClient.PutAsJsonAsync(
            $"v3/style_rules/{ruleList.DeepLStyleId}/configured_rules",
            JsonSerializer.Deserialize<JsonElement>(ruleList.ConfiguredRulesJson),
            ct);

        // Sync custom instructions
        await SyncCustomInstructionsAsync(ruleList, ct);

        ruleList.IsDirty = false;
        ruleList.LastSyncedAt = DateTime.UtcNow;
        return ruleList.DeepLStyleId;
    }

    // Create new style rule list
    var payload = new
    {
        name = $"rasepi-{ruleList.TenantId}-{ruleList.TargetLanguage}",
        language = ruleList.TargetLanguage,
        configured_rules = JsonSerializer.Deserialize<JsonElement>(
            ruleList.ConfiguredRulesJson),
        custom_instructions = ruleList.CustomInstructions.Select(ci => new
        {
            label = ci.Label,
            prompt = ci.Prompt,
            source_language = ci.SourceLanguage
        })
    };

    var response = await _httpClient.PostAsJsonAsync("v3/style_rules", payload, ct);
    var result = await response.Content.ReadFromJsonAsync<StyleRuleResponse>(ct);

    ruleList.DeepLStyleId = result.StyleId;
    ruleList.IsDirty = false;
    ruleList.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return ruleList.DeepLStyleId;
}

Ao contrário dos glossários, as listas de regras de estilo do DeepL são mutáveis. Pode substituir as regras configuradas no local com PUT /v3/style_rules/{style_id}/configured_rules, e as instruções personalizadas podem ser adicionadas, actualizadas ou eliminadas individualmente. Muito mais amigável para refinamento iterativo.

Como são as regras configuradas

As regras configuradas cobrem convenções de formatação que variam de acordo com o idioma ou preferência da empresa. Coisas como:

{
  "dates_and_times": {
    "time_format": "use_24_hour_clock",
    "calendar_era": "use_bc_and_ad"
  },
  "punctuation": {
    "periods_in_academic_degrees": "do_not_use"
  },
  "numbers": {
    "decimal_separator": "use_comma"
  }
}

Estas regras parecem triviais, mas são muito rápidas. Um documento alemão que usa o formato de hora AM/PM e decimais separados por ponto final é lido como "traduzido do inglês" para um leitor alemão. Definir use_24_hour_clock e use_comma para separadores decimais em todas as traduções alemãs elimina isso imediatamente.

Instruções personalizadas: este é o verdadeiro poder

As instruções personalizadas são diretivas de texto livre, até 200 por lista de regras de estilo, cada uma com um máximo de 300 caracteres. Basicamente, diz a DeepL como moldar a tradução em linguagem simples:

public class TenantCustomInstruction
{
    public Guid Id { get; set; }
    public Guid StyleRuleListId { get; set; }
    public string Label { get; set; }              // e.g. "Tone instruction"
    public string Prompt { get; set; }             // e.g. "Use a friendly, diplomatic tone"
    public string? SourceLanguage { get; set; }    // Optional source lang filter
}

Exemplos reais dos nossos inquilinos:

"Use a friendly, diplomatic tone" para uma empresa em fase de arranque que pretende documentos acessíveis
"Always use 'Sie' form, never 'du'" para um escritório de advogados alemão
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" para termos que necessitam de tratamento dependente do contexto para além do simples mapeamento do glossário
"Use British English spelling (colour, organisation, licence)" para empresas sediadas no Reino Unido que traduzem entre variantes do inglês
"Put currency symbols after the numeric amount" para corresponder às convenções europeias

As instruções personalizadas são realmente poderosas para convenções específicas do domínio que não cabem nas entradas do glossário. Um glossário mapeia um termo para outro. Uma instrução personalizada pode dizer "ao traduzir documentos API, use o modo imperativo em vez da voz passiva". Trata-se de um tipo de controlo completamente diferente.

Formalidade

O parâmetro formality de DeepL (default, more, less, prefer_more, prefer_less) ainda está disponível como um controlo separado juntamente com as regras de estilo. Alemão "du" versus "Sie", francês "tu" versus "vous", níveis de polidez japoneses. Estes são definidos por idioma do locatário através de TenantLanguageConfig:

public class TenantLanguageConfig : ITenantScoped
{
    public string LanguageCode { get; set; }
    public string DisplayName { get; set; }
    public bool IsEnabled { get; set; }
    public TranslationTrigger Trigger { get; set; }
    public string? Formality { get; set; }         // "more", "less", "prefer_more", etc.
    public string? StyleRuleListId { get; set; }   // Links to TenantStyleRuleList
    public string? TranslationProvider { get; set; }
    public int SortOrder { get; set; }
    public bool IsDefault { get; set; }
}

A formalidade, as regras de estilo e os glossários são todos compostos. Uma única chamada de tradução pode conter todos os três:

var glossaryId = await GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang, ct);
var styleId = await GetOrSyncStyleRuleListAsync(targetLang, ct);
var formality = tenantLanguageConfig.Formality ?? "default";

// Build the v2/translate request payload
var payload = new
{
    text = new[] { blockContent },
    source_lang = NormalizeLanguageCode(sourceLang),
    target_lang = NormalizeLanguageCode(targetLang),
    glossary_id = glossaryId,
    style_id = styleId,
    formality = formality,
    preserve_formatting = true,
    context = surroundingContext,  // Adjacent blocks, not billed
    model_type = "quality_optimized"
};

Duas coisas que vale a pena notar aqui:

**Passamos blocos adjacentes como contexto para melhorar a qualidade da tradução. O DeepL usa-o para resolver ambiguidades, mas não o traduz nem o fatura. Um parágrafo sobre "células" é traduzido de forma diferente quando o contexto circundante é um documento de biologia versus um manual de folha de cálculo.
**Seleção do modelo Qualquer pedido com style_id ou custom_instructions utiliza automaticamente o modelo quality_optimized de DeepL. Este é o nível de qualidade mais elevado. Não é possível combiná-los com latency_optimized, o que é uma limitação deliberada de DeepL. A personalização do estilo necessita do modelo completo.

Porque é que isto é mais importante do que se pensa

Imagine uma empresa que escreve documentos internos em alemão com o informal "du" que subitamente muda para o formal "Sie" numa secção traduzida. Parece inconsistente, na melhor das hipóteses, e pouco profissional, na pior. A formalidade trata disso. Mas a formalidade, por si só, não vai apanhar um documento que usa carimbos de data e hora AM/PM quando o seu escritório alemão usa o formato de 24 horas, ou que coloca o símbolo da moeda antes do número em vez de depois.

Todos estes elementos em conjunto (regras de estilo, instruções personalizadas, formalidade, glossários) produzem traduções que parecem ter sido escritas por alguém da sua equipa. Não como se fossem produzidas por uma máquina que não sabe que a sua empresa existe.

A camada de serviço DeepL

Toda a comunicação DeepL passa pelo IDeepLService. Ele envolve o SDK oficial do DeepL .NET e lida com as chamadas da API v3 para regras de estilo:

public interface IDeepLService
{
    // Text translation (v2)
    Task<TextResult> TranslateTextAsync(
        string text, string sourceLanguage, string targetLanguage,
        string? options = null);

    Task<TextResult[]> TranslateTextBatchAsync(
        IEnumerable<string> texts, string sourceLanguage,
        string targetLanguage, string? options = null);

    // Glossary management (v2)
    Task<GlossaryInfo> CreateGlossaryAsync(
        string name, string sourceLang, string targetLang,
        Dictionary<string, string> entries);
    Task DeleteGlossaryAsync(string glossaryId);
    Task<GlossaryInfo> GetGlossaryAsync(string glossaryId);
    Task<GlossaryInfo[]> ListGlossariesAsync();
    Task<Dictionary<string, string>> GetGlossaryEntriesAsync(
        string glossaryId);

    // Style rules (v3)
    Task<StyleRuleResponse> CreateStyleRuleListAsync(
        string name, string language,
        JsonElement configuredRules,
        IEnumerable<CustomInstructionRequest> customInstructions);
    Task ReplaceConfiguredRulesAsync(
        string styleId, JsonElement configuredRules);
    Task<CustomInstructionResponse> AddCustomInstructionAsync(
        string styleId, string label, string prompt,
        string? sourceLanguage = null);
    Task DeleteCustomInstructionAsync(
        string styleId, string instructionId);
    Task DeleteStyleRuleListAsync(string styleId);

    // Usage tracking
    Task<Usage> GetUsageAsync();
    Task<Language[]> GetSourceLanguagesAsync();
    Task<Language[]> GetTargetLanguagesAsync();
}

A implementação trata da normalização do código da língua. DeepL requer EN-US ou EN-GB em vez de en simples, e PT-PT ou PT-BR em vez de pt:

private static string NormalizeLanguageCode(string code)
    => code.ToLower() switch
    {
        "en" => "EN-US",
        "pt" => "PT-PT",
        _ => code.ToUpper()
    };

A tradução em lote usa 50-item chunking para ficar dentro dos limites da API do DeepL enquanto maximiza a taxa de transferência:

public async Task<TranslationBatchResult> TranslateBatchAsync(
    Dictionary<string, string> texts,
    string sourceLanguage, string targetLanguage)
{
    var translations = new Dictionary<string, string>();
    long totalChars = 0;

    foreach (var chunk in texts.Chunk(50))
    {
        var results = await _deepL.TranslateTextBatchAsync(
            chunk.Select(kv => kv.Value),
            sourceLanguage, targetLanguage);

        for (int i = 0; i < chunk.Length; i++)
        {
            translations[chunk[i].Key] = results[i].Text;
            totalChars += chunk[i].Value.Length;
        }
    }

    return new TranslationBatchResult
    {
        Translations = translations,
        BilledCharacters = totalChars
    };
}

Como só enviamos blocos obsoletos, e não documentos inteiros, um lote de tradução típico para uma única edição contém 1-3 blocos em vez de mais de 40. É daí que vem a redução de custos de 94%.

O orquestrador de tradução

O TranslationOrchestrator decide o que fazer com cada bloco quando o documento de origem é alterado. Vamos percorrer a árvore de decisão:

public async Task OrchestrateTranslationAsync(
    Guid entryId, List<Guid> changedBlockIds,
    CancellationToken ct = default)
{
    var entry = await _db.Entries
        .FirstOrDefaultAsync(e => e.Id == entryId, ct);

    var translations = await _db.EntryTranslations
        .Where(t => t.EntryId == entryId)
        .ToListAsync(ct);

    foreach (var translation in translations)
    {
        var langConfig = await GetLanguageConfigAsync(
            translation.Language, ct);

        var translationBlocks = await _db.TranslationBlocks
            .Where(tb => changedBlockIds.Contains(tb.SourceBlockId)
                      && tb.Language == translation.Language)
            .ToListAsync(ct);

        foreach (var block in translationBlocks)
        {
            if (block.IsLocked || block.TranslatedById is not null)
            {
                // Human-edited or locked - mark stale, don't overwrite
                block.Status = TranslationStatus.Stale;
            }
            else if (langConfig.Trigger == TranslationTrigger.AlwaysTranslate)
            {
                // Machine-translated, auto mode - retranslate now
                await RetranslateBlockAsync(block, translation.Language, ct);
            }
            else
            {
                // TranslateOnFirstVisit - mark stale, translate later
                block.Status = TranslationStatus.Stale;
            }
        }
    }

    await _db.SaveChangesAsync(ct);
}

A parte chave: **Se um tradutor ajustou manualmente um bloco, talvez adicionando contexto cultural ou reformulando a redação para maior clareza, o sistema respeita esse trabalho. Marca o bloco como obsoleto para que o tradutor saiba que a fonte mudou, mas não substitui silenciosamente as suas edições.

Blocos traduzidos por máquina com AlwaysTranslate ativado são retraduzidos imediatamente. Os blocos traduzidos automaticamente com TranslateOnFirstVisit são marcados como obsoletos e traduzidos quando alguém abre efetivamente o documento nessa língua.

Gatilhos de tradução: quando as traduções acontecem

Cada língua tem um TranslationTrigger que controla o tempo:

public enum TranslationTrigger
{
    AlwaysTranslate,         // Translate on every save
    TranslateOnFirstVisit    // Translate when first opened in that language
}

O AlwaysTranslate é útil para línguas de alta prioridade onde quer que as traduções sejam imediatamente actuais. Francês para uma empresa com um grande escritório em Paris. Alemão para uma empresa com sede em Munique.

TranslateOnFirstVisit é útil para línguas que são ocasionalmente necessárias, mas que não valem o custo da API para manter perfeitamente actualizadas em todos os momentos. Quando alguém abre o documento nessa língua, os blocos obsoletos são traduzidos em tempo real.

Ambos os modos usam a mesma resolução de glossário, as mesmas configurações de formalidade e o mesmo hashing de conteúdo. A única diferença é o tempo.

Adaptação única de conteúdo e estrutura

É aqui que a arquitetura compensa realmente, para além da simples tradução.

Quando um tradutor alemão adiciona uma secção de conformidade DSGVO que não existe em inglês, adiciona-a como um novo bloco na versão alemã. Esse bloco não tem SourceBlockId, é assinalado como conteúdo único. O sistema nunca o envia para retradução porque não existe uma fonte a partir da qual traduzir. Só existe em alemão.

Quando um tradutor japonês muda uma lista de marcadores para uma lista numerada (uma convenção comum na escrita técnica japonesa), a marca IsStructureAdapted do bloco preserva-o em futuros ciclos de retradução:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    StructureAdaptationNotes = "Numbered list preferred in JP technical docs",
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

O sinalizador IsNoTranslate lida com o conteúdo que deve ser copiado literalmente: blocos de código, URLs, nomes de produtos, notação matemática. O fornecedor de tradução ignora-os completamente.

Colocando tudo junto

Vamos percorrer o fluxo completo. Um utilizador em Londres edita um parágrafo no documento de origem em inglês e o seu escritório em Munique tem o alemão definido como AlwaysTranslate:

**O utilizador guarda. O TipTap envia JSON para a API.
**O CreateBlocksFromDocumentAsync analisa o JSON, recalcula os hashes de conteúdo e compara os hashes antigos e novos para identificar os blocos que foram efetivamente alterados.
**Encontra o EntryTranslation alemão e verifica o bloco alemão. É traduzido por máquina, não está bloqueado, não foi editado por humanos, por isso é elegível para retradução.
**Configuração de tradução carregada: ID do glossário resolvido através de GetOrSyncDeepLGlossaryIdAsync("en", "de"), regras de estilo através de GetOrSyncStyleRuleListAsync("de"), formalidade definida para "more" (formal "Sie"), blocos adjacentes passados como contexto para desambiguação.
Chamada DeepL Bloco único enviado com ID do glossário, ID do estilo, formalidade e contexto.
Bloco atualizado. Conteúdo traduzido armazenado, SourceContentHash sincronizado, estado definido para UpToDate. Um bloco traduzido em vez de 40+. Os restantes 39 blocos? Inalterados.

Entretanto, o seu escritório de Tóquio tem o japonês definido para TranslateOnFirstVisit. A mesma edição marca o bloco de tradução em japonês como Stale. Quando alguém em Tóquio abre o documento, os passos 5-9 acontecem na hora. A adaptação da sua estrutura (lista numerada) é preservada. Os seus blocos únicos permanecem exatamente onde estão.

Penso que o motor de tradução é a parte do Rasepi que oferece o valor mais visível. As traduções que utilizam a sua terminologia, seguem as suas convenções de formatação, obedecem às suas instruções personalizadas, correspondem ao seu tom, respeitam o trabalho dos seus tradutores e custam uma fração do que custaria a retradução de um documento completo. A arquitetura torna tudo isto automático e mantém-se fora do caminho quando os humanos querem assumir o controlo.

O mesmo motor DeepL que alimenta as traduções escritas também alimenta o Talk to Docs, a nossa interface de documentação conversacional, com o DeepL Voice a tratar da interação falada. Os mesmos glossários, as mesmas regras de estilo, a mesma formalidade, a mesma consistência. Quer a sua equipa leia a documentação ou fale com ela, a qualidade da linguagem é idêntica.

Explore a API de tradução →

Falar com os documentos é melhor do que lê-los

2026-03-10T00:00:00Z

Há uma razão para as pessoas dizerem "vamos falar sobre isso" quando algo é complexo.

Quando estamos a tentar compreender uma nova ideia, resolver um problema ou recordar um processo sob pressão, a conversa é muitas vezes mais fácil do que a leitura. Não porque a leitura seja má. A leitura é uma das ferramentas mais poderosas que o ser humano já desenvolveu. Mas a leitura é uma competência aprendida que se sobrepõe a algo muito mais antigo: a fala.

Somos faladores muito antes de sermos leitores.

Isso é mais importante do que as pessoas imaginam, especialmente agora que a maior parte do conhecimento do mundo vive em documentos, wikis, PDFs e longas páginas internas que ninguém quer abrir a menos que seja absolutamente necessário.

A leitura é aprendida. A conversação é nativa.

Os seres humanos falaram durante muito tempo antes de escreverem qualquer coisa. As crianças aprendem a compreender a linguagem falada naturalmente. A leitura requer instrução explícita, repetição e anos de prática.

Mesmo para adultos altamente alfabetizados, a leitura continua a ser um ato mais deliberado do que ouvir ou falar. Exige concentração visual, atenção contínua, memória de trabalho e interpretação da estrutura na página. Está a descodificar símbolos, a analisar frases, a construir contextos e a decidir o que é importante.

A conversação funciona de forma diferente. Quando a informação é transmitida de forma falada e interactiva, o cérebro tem uma experiência diferente:

Parece sequencial em vez de visualmente avassaladora
Dá feedback e esclarecimentos imediatos
Reduz a necessidade de analisar e filtrar grandes blocos de texto
reflecte a forma como as pessoas já pedem ajuda na vida real

Este último ponto é muito importante. Em situações de incerteza, a maioria das pessoas não quer instintivamente ler 1500 palavras. Querem perguntar: "O que é que faço a seguir?"

Falar reduz o atrito cognitivo

Um documento é estático. Contém tudo ao mesmo tempo.

Isso parece útil, e muitas vezes é. Mas também cria fricção. Uma página cheia de títulos, chamadas de atenção, ligações, notas, exemplos e casos extremos obriga o leitor a decidir o que deve ignorar. Isso é cognitivamente dispendioso.

Quando se fala com um sistema de informação, normalmente obtém-se a experiência oposta: relevância em primeiro lugar, detalhe em segundo.

Faz-se uma pergunta. Obtém uma resposta. Depois, faz uma nova pergunta.

Este padrão de interação reduz a sobrecarga mental de algumas formas importantes:

1. Reduz o espaço do problema

Um documento completo apresenta todo o cenário. Uma conversa apresenta o próximo passo útil.

Quando alguém pergunta, "Como é que eu integro um novo engenheiro?" normalmente não quer o manual completo imediatamente. Quer orientação. A conversa permite-lhes começar com pouco e expandir apenas quando necessário.

2. Preserva a memória de trabalho

A leitura exige que mantenha várias coisas na sua cabeça enquanto procura a parte relevante. A interação falada ou conversacional externaliza esse esforço. O sistema faz a maior parte da filtragem por si.

3. Parece socialmente familiar

Os seres humanos estão profundamente adaptados à troca de informações. Nós perguntamos. Alguém responde. Nós aperfeiçoamos. Eles esclarecem-nos. Este ciclo é uma das formas mais antigas de aprendizagem que temos.

Mesmo quando o "alguém" é um sistema, a estrutura continua a parecer natural.

A leitura não é passiva. É exatamente esse o objetivo.

Uma das razões pelas quais falar pode parecer mais fácil é o facto de a leitura não ser tão fácil como as pessoas supõem. Os leitores experientes fazem com que pareça fácil, mas o processo é altamente ativo.

Para ler bem, é preciso:

identificar a estrutura
inferir a importância
resolver ambiguidades
guardar o contexto na memória
ligar uma secção a outra
decidir quando passar os olhos e quando abrandar

Este é o verdadeiro trabalho cognitivo.

Em muitas situações, esse trabalho vale a pena. A leitura aprofundada ajuda a obter nuances, precisão e uma compreensão mais alargada. Mas noutras situações, especialmente quando alguém está cansado, stressado, sobrecarregado ou apenas a tentar desbloquear, falar é muitas vezes a opção mentalmente mais leve.

Isto é especialmente verdade no local de trabalho, onde as pessoas não estão normalmente a abordar a documentação em condições ideais. Estão:

a meio da tarefa
interrompidas
a mudar de contexto
estão a tentar resolver algo rapidamente
muitas vezes já ligeiramente frustrado

Nesse estado, o acesso conversacional à informação pode parecer dramaticamente melhor do que o acesso à primeira página.

Falar muda a relação com a informação

Há também uma dimensão emocional aqui.

Os documentos podem parecer formais e distantes. Eles implicam: leia tudo isto, compreenda-o corretamente e não perca nada de importante. Isto pode ser útil como material de referência, mas também pode criar hesitação.

A conversa parece permissiva. Pode ser-se vago. Pode perguntar mal. Pode admitir-se a confusão. Pode dizer: "Não sei bem o que procuro, mas preciso da informação sobre os pedidos de acesso."

Isso é importante porque as pessoas muitas vezes evitam a documentação não porque não gostem da informação, mas porque não gostam do esforço e da incerteza envolvidos na procura da parte correta da mesma.

Falar reduz essa barreira.

Porque é que isto é importante agora

Durante muito tempo, os documentos tinham de ser lidos porque não havia alternativa prática. A pesquisa ajudou as pessoas a encontrar páginas, mas não alterou o modelo de interação. Continuava a ser necessário abrir a página, digitalizá-la e extrair o que era necessário.

Isso está a mudar.

À medida que as interfaces se tornam mais conversacionais, as pessoas esperam cada vez mais que a informação responda em vez de simplesmente existir. Querem pedir o que precisam numa linguagem simples e receber algo adaptado ao momento.

Isto não torna a leitura obsoleta. Altera o seu papel.

A leitura torna-se a camada profunda. A conversação passa a ser a camada de acesso.

Os melhores sistemas suportam ambos:

falar quando se precisa de orientação ou rapidez
ler quando se precisa de profundidade, verificação ou contexto completo

O risco de simplificação excessiva

Há uma ressalva importante: falar com a informação só é melhor se as respostas forem fiáveis.

Se uma interface de conversação der respostas parciais, enganadoras ou demasiado confiantes, a experiência torna-se pior do que a leitura, porque retira ao utilizador a capacidade de inspecionar diretamente o material de origem.

Portanto, o futuro não é "substituir todos os documentos por voz". O futuro é dar às pessoas uma forma mais humana de aceder a documentos sem perder a profundidade e a precisão que o conhecimento escrito proporciona.

Esse equilíbrio é importante. A conversação é mais fácil, mas os documentos continuam a ter a estrutura duradoura, o detalhe e a responsabilidade de que as organizações necessitam.

Uma interface mais humana para o conhecimento

O ponto mais profundo é simples: as pessoas não pensam naturalmente em páginas. Pensam em perguntas, histórias, fragmentos e diálogos.

Nós perguntamos:

O que é que isto significa?
O que é que eu faço primeiro?
Qual é a parte importante?
Consegues explicar isso de outra forma?
O que é que mudou?

Estes são movimentos de conversação, não de leitura.

Por isso, quando falar com a informação parece mentalmente mais fácil do que lê-la, isso não é um sinal de preguiça intelectual. É normalmente um sinal de que a interface corresponde à forma como o cérebro prefere abordar a incerteza.

A leitura continua a ser essencial. Mas, como ponto de entrada para o conhecimento, a conversa é muitas vezes melhor porque está mais próxima daquilo que somos por natureza.

Não somos leitores em primeiro lugar. Somos primeiro faladores. Os sistemas de conhecimento mais intuitivos lembrar-se-ão disso.

Plataformas de documentação criadas para outra era

2026-03-08T00:00:00Z

O Confluence e o Notion não são produtos ruins. Isso precisa ser dito claramente no início.

Eles tiveram sucesso por boas razões. O Confluence tornou-se o local predefinido para a documentação interna em muitas empresas porque proporcionou às equipas um local central para escrever, organizar e partilhar conhecimentos. O Notion conquistou as pessoas com flexibilidade, experiências de escrita mais limpas e uma superfície de produto mais moderna.

Ambas as plataformas resolveram problemas reais na era para a qual foram criadas.

O problema agora é que o mundo à sua volta mudou mais depressa do que as suas fundações.

Já não estamos num mundo em que a documentação só precisa de ser escrita, armazenada e pesquisada. Estamos num mundo em que se espera cada vez mais que a documentação o seja:

legível por máquinas
consciente da atualidade
segura para recuperação por IA
suficientemente estruturada para a automatização
dinâmicas entre línguas e públicos
continuamente fiável, não apenas disponível

Esta é uma barreira diferente.

Foram criados para um modelo de conhecimento anterior à IA

As plataformas de documentação tradicionais foram concebidas com base num pressuposto simples: se a página existir e for pesquisável, o problema está praticamente resolvido.

Isto era suficientemente bom quando o utilizador principal era um ser humano que abria uma wiki, passava os olhos pela página e fazia a sua avaliação. Nesse modelo, a função da plataforma era facilitar a criação e a navegação.

A IA altera a descrição do trabalho.

Agora, a plataforma não está apenas a armazenar conhecimentos para as pessoas. Está a produzir material de origem para sistemas que recuperam, classificam, resumem e respondem a perguntas automaticamente.

Isto introduz novos requisitos a que as arquitecturas mais antigas não davam prioridade:

Que conteúdos são fiáveis neste momento?
Que páginas estão desactualizadas mas ainda são pesquisáveis?
Que secções foram alteradas recentemente?
Que versão linguística é a atual?
Que conteúdos são projectos, arquivados, específicos de uma região ou de baixa confiança?
Que documentos devem ser totalmente excluídos das respostas de IA?

Uma plataforma que não tenha sido construída em torno destas questões tem de as adaptar. Isso é sempre mais difícil do que concebê-las desde o início.

A força do legado transforma-se em travão do legado

Os produtos estabelecidos têm vantagens: distribuição, ecossistema, marca, familiaridade com o cliente, integrações e equipas que sabem como fazer o envio. Mas esses mesmos pontos fortes podem atrasar a mudança estrutural.

Porquê? Porque as plataformas maduras implicam compromissos.

Elas têm:

anos de decisões acumuladas sobre produtos
enormes bases instaladas com fluxos de trabalho existentes
expectativas em relação à compatibilidade com versões anteriores
plugins e extensões que dependem de comportamentos antigos
modelos de dados optimizados para os casos de utilização de ontem

Quando uma plataforma como o Confluence ou o Notion pretende acrescentar uma capacidade genuinamente nova, muitas vezes tem de a adaptar ao sistema existente e não através dele.

Este é o desafio da incumbência: não está apenas a construir o futuro, está a arrastar o passado consigo.

Acrescentar funcionalidades de IA não é o mesmo que tornar-se nativo da IA

Muitas plataformas estabelecidas estão agora a colocar a IA no topo. Resumos. Assistência à escrita. Melhorias na pesquisa. Interfaces de perguntas e respostas. O Confluence tem Atlassian Intelligence, o Notion tem Notion AI, e o GitBook adicionou AI-powered search. Estas funcionalidades são úteis. Algumas delas são boas.

Mas há uma diferença significativa entre:

adicionar caraterísticas de IA a um produto de documentação
construir um produto de documentação cuja arquitetura central pressupõe o consumo de IA desde o primeiro dia

A primeira abordagem conduz frequentemente a funcionalidades de assistência nas extremidades. A segunda altera a base.

Uma plataforma de conhecimento nativa de IA coloca questões de design diferentes desde o início:

como é que os documentos devem ser estruturados para que os sistemas possam raciocinar sobre eles com segurança?
como deve ser representada a confiança?
que metadados devem ser de primeira classe e não opcionais?
Como é que os conteúdos obsoletos devem perder visibilidade?
como é que as respostas devem ser restringidas quando as fontes subjacentes são fracas?

Estas são questões de arquitetura, não de caraterísticas.

As plataformas novas têm uma vantagem temporária

É aqui que as plataformas mais recentes podem ganhar, pelo menos durante algum tempo.

Uma nova plataforma tem a liberdade de conceber em função das restrições actuais e não dos hábitos de ontem. Não tem de preservar uma década de pressupostos sobre o que é um documento ou como uma wiki se deve comportar. Pode fazer escolhas diferentes numa fase inicial:

tratar a atualidade como um conceito de primeira classe
tornar a confiança na fonte visível tanto para humanos como para máquinas
armazenar metadados mais ricos sobre o estado do conteúdo
incorporar fluxos de trabalho multilingues no modelo principal, em vez de os acrescentar
decidir que a pesquisa e a recuperação por IA devem ser classificadas por confiança e não apenas por relevância

Essa liberdade é importante.

Na tecnologia, os operadores históricos são frequentemente mais fortes durante períodos estáveis. Os novos operadores são muitas vezes mais fortes quando o próprio modelo está a mudar.

A era da IA é uma dessas mudanças.

Porque é que isto é especialmente difícil para o Confluence

O Confluence é poderoso, mas vem de uma visão de mundo mais antiga. Foi construído em torno de [espaços de equipa, páginas, navegação hierárquica] (https://support.atlassian.com/confluence-cloud/docs/use-spaces-to-organize-your-work/) e de um [modelo empresarial rico em plug-ins] (https://marketplace.atlassian.com/). Essas escolhas faziam sentido. Ainda fazem sentido para muitas organizações.

Mas também significam que o produto está a carregar uma grande complexidade. As plataformas empresariais raramente se conseguem reinventar de forma limpa. Têm de negociar com a sua própria história.

Isso torna a modernização mais lenta. Não é impossível. Apenas mais lenta.

Quando os requisitos da era da IA exigem metadados mais limpos, uma modelação de confiança mais explícita ou uma governação de conteúdos mais opinativa, um sistema criado para uma flexibilidade máxima através de anos de extensões pode ter dificuldade em avançar de forma coesa.

Por que isso é especialmente complicado para o Notion

O Notion tem um problema diferente. Ele parece mais novo, mais leve e mais flexível. Mas a flexibilidade também pode funcionar contra ele.

O ponto forte do Notion é que [quase tudo pode se tornar uma página, um banco de dados, uma nota, um documento leve ou um espaço colaborativo] (https://www.notion.com/product). Essa flexibilidade é óptima para as equipas. Não é tão boa quando são necessárias garantias sólidas sobre o significado do conteúdo, o estado em que se encontra e se deve ser utilizado como uma fonte fiável por um sistema de IA.

Quanto mais livre for uma plataforma, mais difícil será impor posteriormente uma semântica fiável.

Os sistemas de IA prosperam com estrutura, metadados explícitos e sinais de confiança. Os espaços de trabalho flexíveis de uso geral precisam frequentemente de muita interpretação antes de o seu conteúdo ser seguro para esse tipo de utilização.

Nada disto significa que estão condenados

Seria uma análise preguiçosa dizer que o Confluence e o Notion não se podem adaptar. Claro que podem.

Têm equipas inteligentes, recursos significativos e fortes incentivos. Vão lançar mais capacidades de IA. Vão melhorar a recuperação, a assistência à criação, os resumos, a governação e os fluxos de trabalho estruturados. Com o tempo, poderão colmatar uma grande parte da lacuna.

Mas o tempo é importante.

Quando uma mudança como esta acontece, a vantagem pertence frequentemente a quem estiver disposto a reconstruir os pressupostos mais rapidamente. As plataformas mais recentes podem avançar com mais coerência porque não estão a adaptar-se tanto. Isso dá-lhes uma janela.

Pode não ser uma janela permanente. Mas é real.

A próxima fase das plataformas de documentação

A próxima geração de ferramentas de documentação será provavelmente julgada menos pela forma como permitem que as pessoas escrevam páginas e mais pela forma como gerem o conhecimento como um sistema de confiança.

Isso significa que os vencedores provavelmente farão cinco coisas bem:

Modelarão a confiança de forma explícita.
Distinguem o conhecimento atual do conhecimento obsoleto.
Tratarão a recuperação de IA como uma superfície central do produto e não como um complemento.
Suportarão conhecimentos multilingues e específicos do público sem fragmentação.
Darão às equipas um maior controlo sobre as informações que são apresentadas, a quem e em que condições.

Esta é uma categoria diferente da wiki clássica.

Porque é que os novos começos são importantes

Há momentos no software em que um produto novo tem uma vantagem, não porque os operadores históricos sejam incompetentes, mas porque a história é cara.

Este é um desses momentos.

Uma nova plataforma pode decidir, desde o primeiro dia, que os documentos não são apenas páginas. São fontes activas para humanos, agentes, sistemas de pesquisa e assistentes de IA. Esse pressuposto altera tudo a jusante.

O Confluence e o Notion podem lá chegar. Mas o caminho é mais longo porque têm de transformar sistemas que foram optimizados para outra era.

Essa transformação leva tempo. Entretanto, as plataformas mais recentes têm espaço para definir o que deve ser uma infraestrutura de conhecimento moderna.

A maior vantagem de uma nova plataforma não é a novidade. É a libertação de velhos pressupostos exatamente no momento em que esses pressupostos deixam de funcionar.

Este é um artigo de perspetiva. As afirmações sobre produtos concorrentes baseiam-se em documentação e anúncios de produtos disponíveis publicamente em março de 2026. Temos um respeito genuíno pelo Confluence e pelo Notion - são produtos excelentes que servem bem milhões de equipas.

Por dentro da arquitetura Rasepi: Plugins, Action Guards e Pipelines

2026-03-06T00:00:00Z

A maioria das plataformas de documentação fala sobre "extensibilidade" da mesma forma que as companhias aéreas falam sobre "espaço para as pernas". Tecnicamente presente, praticamente dececionante. Eu queria que a arquitetura do Rasepi fosse genuinamente extensível sem se tornar imprevisível, por isso construímos três sistemas interligados: plugins para capacidade, action guards para controlo, e pipelines para execução determinística.

Este post mostra como cada um deles funciona em nossa base de código atual.

O sistema de plugins: modular por design

Cada plugin no Rasepi implementa IPluginModule, uma única interface que declara o que o plugin é, quais serviços ele precisa, e quais rotas ele expõe:

public interface IPluginModule
{
    PluginManifest Manifest { get; }
    void RegisterServices(IServiceCollection services);
    void MapRoutes(IEndpointRouteBuilder routes);
}

O PluginManifest é puro dado. Ele descreve o plugin sem executar nada:

public sealed class PluginManifest
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public string Description { get; init; }
    public string Category { get; init; }
    public IReadOnlyDictionary<string, string> UiContributions { get; init; }
    public bool HasSettings { get; init; }
    public bool HasEndpoints { get; init; }
    public IReadOnlyList<string> Dependencies { get; init; }
}

Repare no UiContributions. Esse dicionário mapeia os pontos de extensão do frontend para os nomes dos componentes, então o frontend do Vue sabe quais componentes de UI cada plugin contribui (um botão da barra de ferramentas, um painel da barra lateral, uma página de configurações).

O registo é uma linha por cada plugin

Na inicialização, nós registramos plugins através de uma API fluente:

var pluginRegistry = new PluginRegistry();

pluginRegistry
    .AddPlugin<WorkflowPluginModule>(builder.Services)
    .AddPlugin<RulesPluginModule>(builder.Services)
    .AddPlugin<RetentionPluginModule>(builder.Services)
    .AddPlugin<ClassificationPluginModule>(builder.Services);

Cada chamada instancia o módulo, armazena-o no registo e chama RegisterServices() para ligar as suas dependências. Depois que a aplicação é construída, uma única linha mapeia todas as rotas de plugins:

app.MapPluginRoutes(pluginRegistry);

Por baixo do capô, cada plugin recebe um grupo de rotas com escopo em /plugins/{pluginId}/ com autorização aplicada automaticamente.

Exemplo real: o plugin Workflow

Aqui está o aspeto de um plugin real, o módulo Workflow & Approvals:

public sealed class WorkflowPluginModule : IPluginModule
{
    public const string PluginId = "workflow";

    public PluginManifest Manifest { get; } = new()
    {
        Id = PluginId,
        Name = "Workflow & Approvals",
        Version = "1.0.0",
        Description = "Adds approval workflows to entry publishing.",
        Category = "Workflow",
        HasSettings = true,
        HasEndpoints = true,
        UiContributions = new Dictionary<string, string>
        {
            ["entry.toolbar.publish"] = "WorkflowPublishButton",
            ["entry.sidebar.status"]  = "WorkflowStatusPanel",
            ["hub.admin.settings"]    = "WorkflowHubSettings",
        }
    };

    public void RegisterServices(IServiceCollection services)
    {
        services.AddScoped<IWorkflowService, WorkflowService>();
        services.AddScoped<IActionGuard, WorkflowPublishGuard>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        WorkflowEndpoints.Map(routes);
    }
}

A plataforma principal nunca referencia WorkflowService ou WorkflowPublishGuard diretamente. Descobre-os através do contentor DI. Essa é a chave para o acoplamento zero. A aplicação principal nunca toca no código do plugin.

Guardas de ação: a camada de controlo

Os plugins adicionam capacidades. Os guardas de ação decidem se essa capacidade, ou qualquer ação do núcleo, tem permissão para continuar. Eles são validadores síncronos que interceptam operações antes da execução.

Fluxo de avaliação dos guardas de ação](/pt/blog/img/action-guard-flow.svg)

A interface é deliberadamente mínima:

public interface IActionGuard
{
    string PluginId { get; }
    string? ActionName { get; }  // null means guard ALL actions

    Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default);
}

Quando ActionName é null, o guarda é executado para cada ação. Quando está definido para algo como "Entry.Publish", apenas intercepta essa ação específica.

O contexto e os contratos de resultado

Cada guard recebe um contexto tipado com o nome da ação, inquilino, utilizador, entidade e um saco de propriedades:

public sealed record ActionGuardContext(
    string ActionName,
    Guid TenantId,
    Guid UserId,
    Guid EntityId,
    IReadOnlyDictionary<string, object?> Properties)
{
    public T? Get<T>(string key) =>
        Properties.TryGetValue(key, out var v) && v is T typed
            ? typed : default;
}

E cada guarda retorna um resultado previsível: permitir, negar ou permitir-com-modificações:

public sealed record ActionGuardResult
{
    public bool IsAllowed { get; init; }
    public string? ReasonCode { get; init; }
    public string? Message { get; init; }
    public IReadOnlyDictionary<string, object?>? Modifications { get; init; }

    public static ActionGuardResult Allow() =>
        new() { IsAllowed = true };

    public static ActionGuardResult Deny(
        string reasonCode, string message) =>
        new() { IsAllowed = false, ReasonCode = reasonCode, Message = message };
}

O campo Modifications é importante. Um guard pode aprovar uma ação mas reescrever parte do conteúdo (por exemplo, redigir segredos antes de publicar).

Nomes de acções canónicas

Nós definimos todas as ações interceptáveis como constantes de string para que não haja nenhuma ambigüidade sobre o que um guard pode ter como alvo:

public static class ActionNames
{
    public static class Entry
    {
        public const string Create  = "Entry.Create";
        public const string Save    = "Entry.Save";
        public const string Publish = "Entry.Publish";
        public const string Delete  = "Entry.Delete";
        public const string Archive = "Entry.Archive";
        public const string Renew   = "Entry.Renew";
    }

    public static class Hub
    {
        public const string Create = "Hub.Create";
        public const string Delete = "Hub.Delete";
        public const string TransferOwnership = "Hub.TransferOwnership";
    }

    public static class Translation
    {
        public const string Create  = "Translation.Create";
        public const string Publish = "Translation.Publish";
    }
}

Exemplo real: bloquear publicação sem aprovação

O plugin Workflow regista um guard que intercepta Entry.Publish:

public sealed class WorkflowPublishGuard : IActionGuard
{
    public string PluginId => WorkflowPluginModule.PluginId;
    public string? ActionName => ActionNames.Entry.Publish;

    public async Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var db = services.GetRequiredService<RasepiDbContext>();
        var entry = await db.Entries
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == context.EntityId, ct);

        if (entry is null)
            return ActionGuardResult.Allow();

        var workflowService = services.GetRequiredService<IWorkflowService>();
        var check = await workflowService
            .CheckPublishAllowedAsync(entry.Id, entry.HubId);

        if (check.IsAllowed)
            return ActionGuardResult.Allow();

        return ActionGuardResult.Deny(
            "workflow.approval_required",
            check.Message ?? "Approval required before publishing.");
    }
}

A plataforma principal não sabe nada sobre workflows de aprovação. Apenas chama Entry.Publish através do pipeline, e o guard bloqueia-o se o workflow não tiver sido concluído.

O pipeline de ação: onde tudo converge

O ActionPipeline é o único caminho de execução para todas as operações protegidas. Ele resolve quais guardas se aplicam, avalia-os, e bloqueia ou executa a ação.

public sealed class ActionPipeline : IActionPipeline
{
    public async Task<ActionPipelineResult> ExecuteAsync(
        string actionName,
        ActionGuardContext context,
        Func<Task> action,
        CancellationToken ct = default)
    {
        var result = await EvaluateAsync(actionName, context, ct);
        if (!result.IsAllowed) return result;

        await action();  // All guards passed — execute

        return result;   // Return modifications for caller
    }
}

O método EvaluateAsync faz o trabalho pesado:

public async Task<ActionPipelineResult> EvaluateAsync(
    string actionName,
    ActionGuardContext context,
    CancellationToken ct = default)
{
    // 1. Which plugins are enabled for this tenant?
    var enabledPlugins = await _resolver.GetEnabledPluginIdsAsync();

    // 2. Which guards match this action?
    var applicable = _guards
        .Where(g => enabledPlugins.Contains(g.PluginId))
        .Where(g => g.ActionName == null || g.ActionName == actionName)
        .ToList();

    // 3. Evaluate each guard
    var denials = new List<ActionGuardResult>();
    var modifications = new List<ActionGuardResult>();

    foreach (var guard in applicable)
    {
        try
        {
            var guardResult = await guard.EvaluateAsync(context, _services, ct);
            if (!guardResult.IsAllowed)
                denials.Add(guardResult);
            else if (guardResult.Modifications?.Count > 0)
                modifications.Add(guardResult);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Guard threw. Treating as Allow.");
        }
    }

    // 4. Any denial blocks the whole action
    if (denials.Count > 0)
        return ActionPipelineResult.Blocked(denials);

    return modifications.Count > 0
        ? ActionPipelineResult.Allowed(modifications)
        : ActionPipelineResult.Allowed();
}

Três importantes decisões de design aqui:

Resolução por inquilino O TenantPluginResolver verifica quais os plugins que cada inquilino tem instalados e activados. Um guarda para um plugin desativado nunca é executado.
**Se algum guarda negar, a ação é bloqueada. Esta é uma postura de segurança deliberada.
**Se um guarda lança uma exceção, esta é registada e tratada como Allow(). Isso evita que um plugin quebrado bloqueie toda a plataforma.

Resolução de plugins por inquilino

O resolvedor consulta a tabela TenantPluginInstallations (com escopo automático para o locatário atual pelos filtros de consulta global EF):

public sealed class TenantPluginResolver : ITenantPluginResolver
{
    public async Task<IReadOnlySet<string>> GetEnabledPluginIdsAsync(
        CancellationToken ct = default)
    {
        if (_cache is not null) return _cache;

        var ids = await _db.TenantPluginInstallations
            .Where(i => i.IsEnabled)
            .Select(i => i.PluginId)
            .ToListAsync(ct);

        _cache = ids.ToHashSet();
        return _cache;
    }
}

Efeitos colaterais orientados por eventos

As acções são síncronas. Os efeitos colaterais não são. Depois que uma ação é concluída, o serviço publica um evento de domínio:

await _eventPublisher.PublishAsync(
    EventNames.Entry.Created, entry.Id, new { entry.OriginalLanguage });

Os eventos são enfileirados em um canal na memória e processados por um EventConsumerWorker em segundo plano. O trabalhador encaminha os eventos para vários sistemas:

Registo de actividades. Regista quem fez o quê, quando
Faturação da tradução: regista os custos por fornecedor
Manipuladores de eventos de plugins.** Qualquer plugin pode subscrever eventos do domínio

Os manipuladores de eventos de plugins implementam IPluginEventHandler:

public interface IPluginEventHandler
{
    string PluginId { get; }
    IReadOnlyList<string> SubscribedEvents { get; }

    Task HandleAsync(
        string eventName, Guid entityId,
        Guid? tenantId, Guid? userId,
        string payloadJson, IServiceProvider services,
        CancellationToken ct = default);
}

O trabalhador só invoca manipuladores cujo plugin está habilitado para o locatário. Isso significa que os efeitos colaterais do plugin A nunca vazam para um locatário que só tem o plugin B instalado.

O motor de tradução a nível de bloco

É aqui que a arquitetura compensa de forma mais visível.

Tradução por blocos: apenas os blocos alterados são retraduzidos](/pt/blog/img/block-translation.svg)

As plataformas tradicionais traduzem documentos inteiros. Nós traduzimos blocos individuais: parágrafos, títulos, itens de lista. Quando um utilizador edita um parágrafo num documento de 50 blocos, apenas esse parágrafo precisa de ser traduzido novamente. Esta é a fonte da nossa poupança de custos de 94%.

Como os blocos são criados a partir do TipTap JSON

Quando um usuário salva um documento, o editor TipTap envia JSON como este:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "attrs": { "blockId": "a1b2c3d4-..." },
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

O BlockTranslationService analisa este JSON e cria registos EntryBlock individuais:

public async Task<List<EntryBlock>> CreateBlocksFromDocumentAsync(
    Guid entryId, string language, string contentJson,
    int version, Guid userId)
{
    var doc = JsonDocument.Parse(contentJson);
    var content = doc.RootElement.GetProperty("content");

    int position = 0;
    foreach (var node in content.EnumerateArray())
    {
        var blockType = node.GetProperty("type").GetString();
        var blockJson = JsonSerializer.Serialize(node);

        // Strip metadata attrs before hashing
        var hashInput = StripBlockMetaAttrs(blockJson);

        var block = new EntryBlock
        {
            Id = ExtractOrGenerateBlockId(node),
            EntryId = entryId,
            Language = language,
            Position = position++,
            BlockType = blockType,
            ContentJson = blockJson,
            ContentHash = CalculateContentHash(hashInput),
            IsNoTranslate = ExtractNoTranslateFlag(node),
            Version = version,
        };

        _context.EntryBlocks.Add(block);
    }

    await _context.SaveChangesAsync();
    return blocks;
}

hashing SHA256 para deteção de desatualização

O hash de conteúdo é o núcleo da deteção de desatualização. Fazemos o hash do conteúdo do bloco (depois de retirar os atributos de metadados como blockId e deleted) usando SHA256:

private string CalculateContentHash(string content)
{
    using var sha256 = SHA256.Create();
    var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToHexString(hashBytes);
}

Quando um bloco de origem muda, seu hash muda. O sistema compara então o SourceContentHash de cada bloco de tradução com o hash de origem atual, e as incompatibilidades são marcadas como Stale:

public async Task MarkTranslationsAsStaleAsync(List<Guid> changedBlockIds)
{
    var affected = await _context.TranslationBlocks
        .Where(t => changedBlockIds.Contains(t.SourceBlockId))
        .ToListAsync();

    foreach (var translation in affected)
    {
        translation.Status = TranslationStatus.Stale;
        translation.UpdatedAt = DateTime.UtcNow;
    }

    await _context.SaveChangesAsync();
}

Adaptação da estrutura

Os tradutores podem alterar os tipos de blocos nas várias línguas. Uma lista de pontos em inglês pode tornar-se numa lista numerada em alemão, uma preferência cultural. O sistema regista este facto:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Fornecedores de tradução como plugins

Os serviços de tradução externos (DeepL, Google Translate, etc.) ligam-se através de ITranslationProviderPlugin:

public interface ITranslationProviderPlugin : IRasepiPlugin
{
    string[] GetSupportedLanguages();

    Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage);

    Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage);
}

O método batch recebe um dicionário de IDs de blocos para o conteúdo, traduz todos eles e retorna as traduções com uma contagem de caracteres facturados. Como só enviamos blocos antigos, e não o documento inteiro, os custos são mínimos.

Isolamento do inquilino: a rede de segurança invisível

Todos os sistemas descritos acima funcionam dentro de um isolamento rigoroso do locatário.

O TenantContextMiddleware resolve o inquilino a partir do JWT em cada pedido e verifica a adesão:

public async Task InvokeAsync(
    HttpContext context, TenantContext tenantContext, RasepiDbContext db)
{
    var tenantIdClaim = context.User.FindFirstValue("tenant_id");
    var userIdClaim = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

    // Populate scoped context
    tenantContext.TenantId = Guid.Parse(tenantIdClaim);
    tenantContext.UserId = Guid.Parse(userIdClaim);

    // Verify membership — fail closed
    var membership = await db.TenantMemberships
        .Where(m => m.TenantId == tenantContext.TenantId
                  && m.UserId == tenantContext.UserId)
        .FirstOrDefaultAsync();

    if (membership == null)
    {
        context.Response.StatusCode = 401;
        return;  // No membership = no access
    }
}

Os filtros de consulta globais do Entity Framework garantem que, mesmo que um programador se esqueça de filtrar por inquilino, a camada de base de dados fá-lo automaticamente:

modelBuilder.Entity<Hub>()
    .HasQueryFilter(h => h.TenantId == _tenantContext.TenantId);

O resultado: db.Hubs.ToListAsync() sempre retorna apenas os hubs do locatário atual. As fugas de dados exigem que se contorne ativamente o filtro de consulta, o que é proibido na nossa base de código.

A imagem completa

Quando um utilizador clica em "Publicar" numa entrada, eis o que acontece:

**A autenticação valida o JWT, TenantContextMiddleware resolve e verifica o inquilino.
**O controlador chama o pipeline.
O pipeline resolve os guardas. Consulta quais os plugins que o inquilino activou, seleciona os guardas aplicáveis.
Os guardas avaliam. O guarda de Fluxo de trabalho verifica as aprovações, o guarda de Retenção verifica a política, o guarda de Regras valida o conteúdo. Todos passam? A entrada é publicada.
**O evento Entry.Published é colocado na fila. Um trabalhador em segundo plano regista a atividade, actualiza a faturação da tradução e chama os manipuladores de eventos do plugin.
Traduções de blocos verificadas. Blocos obsoletos são identificados para retradução.

Cada camada faz o seu trabalho. Nenhuma camada se intromete em outra. Esta é a arquitetura.

Não construímos isto porque a extensibilidade está na moda. Construímo-la porque uma plataforma de documentação que não se pode adaptar ao fluxo de trabalho de cada equipa acabará por ser substituída por uma que o possa fazer. E uma plataforma que se adapta sem proteção acabará por quebrar algo que é importante.