a21glossary para TYPO3

Quem precisa de um glossário geralmente tem um problema de SEO

Explicar termos técnicos em um site parece um serviço ao usuário. Na prática, a21glossary resolve um problema técnico concreto: páginas TYPO3 com conteúdo que exige explicações ranqueiam melhor quando os termos são vinculados internamente, indexáveis como páginas próprias e acessíveis via tooltip. A extensão gera, a partir de um banco de termos centralizado, links automáticos no conteúdo, sem que os editores precisem criar cada link manualmente.

Para empresas com portais especializados, plataformas de conhecimento ou produtos que demandam explicação, a21glossary cria exatamente a estrutura de links internos que o Google interpreta como autoridade temática. Em vez de esconder 50 termos em uma FAQ, surgem 50 páginas independentes e indexáveis com potencial de Schema Markup.

Cenários típicos de uso

Portais especializados com mais de 100 termos. Associações setoriais, universidades e editoras técnicas mantêm glossários com centenas de entradas. a21glossary vincula automaticamente cada termo na primeira ocorrência no texto corrido. Em um cliente com 340 entradas de glossário, a densidade de links internos aumentou 28%, mensurável via Google Search Console.

Páginas de produtos com vocabulário técnico. Fabricantes de máquinas, empresas químicas e fabricantes de tecnologia médica utilizam linguagem especializada que compradores e decisores nem sempre conhecem. Um tooltip com 2 a 3 frases de explicação mantém o leitor na página, em vez de enviá-lo ao Google. O tempo de permanência aumenta, a taxa de rejeição diminui.

Plataformas de conhecimento multilíngues. Em combinação com o gerenciamento de idiomas do TYPO3, glossários podem ser mantidos por idioma. Termos em português vinculam a explicações em português, termos em inglês a explicações em inglês. Funciona corretamente desde que a configuração de idiomas no TYPO3 esteja bem implementada.

Arquitetura técnica

a21glossary funciona como um pós-processador de conteúdo. Após a renderização de uma página TYPO3, a extensão percorre o output HTML em busca de termos definidos e os substitui por variantes com links. Os termos são armazenados em uma tabela própria no banco de dados e gerenciados por um módulo no backend.

A extensão se registra via um Content Object Post User Func Hook no processo de renderização TypoScript. Isso significa que ela só intervém depois que o TYPO3 renderizou completamente o conteúdo. Por isso funciona independentemente do tipo de elemento de conteúdo utilizado, seja Textmedia, News ou Custom Content Elements.

A exibição do tooltip é feita por um pequeno snippet JavaScript e CSS. Ambos são personalizáveis. Em configurações modernas do TYPO3, recomenda-se substituir o JavaScript padrão por uma solução CSS-only para não prejudicar os Core Web Vitals. Com o atributo title e um seletor :hover, tooltips simples podem ser criados sem nenhuma linha de JavaScript.

As entradas do glossário são configuráveis via TypoScript: quais páginas devem ser percorridas, quantas vezes um termo pode ser vinculado por página (recomendado: uma vez) e quais áreas HTML são excluídas (navegação, footer, outras entradas de glossário).

Problemas frequentes e soluções

Queda de performance em glossários grandes. A partir de cerca de 500 termos, o passo de pós-processamento pode se tornar perceptível, especialmente em páginas com muito texto. A solução: ativar o cache. O cache de páginas do TYPO3 armazena o resultado após a primeira renderização. Apenas na limpeza do cache ocorre novo processamento. Adicionalmente, ajuda reduzir a lista de termos ao vocabulário efetivamente utilizado. 200 termos precisos superam 800 incluindo variantes.

Links incorretos em títulos e links existentes. a21glossary vincula por padrão em todos os lugares, inclusive dentro de tags H2 ou hiperlinks existentes. Isso resulta em links aninhados que são HTML inválido. Através da configuração TypoScript, tags podem ser excluídas: excludeTags = h1,h2,h3,a,script. Essa configuração pertence a toda primeira instalação.

Conflitos com RealURL e roteamento. Em versões mais antigas do TYPO3 (antes da v9), havia problemas quando páginas de detalhe do glossário eram roteadas via RealURL. Com TYPO3 v10+ e o Site Routing nativo, esse problema não existe mais. Quem ainda usa RealURL deveria migrar de qualquer forma.

Migração e compatibilidade de versões

a21glossary foi originalmente desenvolvida para TYPO3 v4.x e atualizada ao longo dos anos. A última versão mantida ativamente no TER suporta TYPO3 v10 e v11. Para TYPO3 v12 existe um fork comunitário no GitHub que porta a extensão para a nova estrutura TCA e o sistema de hooks alterado. Para TYPO3 v13, não há versão oficial disponível no momento.

A migração de v11 para v12 requer três ajustes: primeiro, a mudança de $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS'] para o novo sistema Event-Dispatcher; segundo, a atualização das definições TCA (configuração de Wizard); e terceiro, a adaptação do setup TypoScript à nova configuração de Site.

Quem planeja migrar para TYPO3 v13 enfrenta uma decisão: continuar desenvolvendo o fork comunitário ou mudar para uma solução alternativa. Como alternativa, é possível implementar a funcionalidade de glossário diretamente como Custom Content Element com DataProcessor. O esforço é de aproximadamente 2 a 3 dias de desenvolvimento, o resultado é à prova de futuro e independente de manutenção de terceiros. A Gosign realizou essa migração em diversos projetos e pode estimar realisticamente o esforço real com base na análise dos dados de glossário existentes.