# Como corrigir o módulo Image SEO do Rank Math no WordPress

O Rank Math Image SEO não funciona quando o módulo está desativado, quando os campos de formato de ALT e title estão vazios ou quando se espera que ele grave os atributos na Biblioteca de Mídia, sendo que o módulo aplica ALT e title dinamicamente apenas no HTML da página publicada.

## O que é Image SEO do Rank Math?

O Image SEO é o módulo do Rank Math que preenche automaticamente os atributos ALT e title das imagens que estão sem esses dados, usando variáveis como o nome do arquivo, o título do post ou a categoria. No plano PRO ele também adiciona legenda, descrição, ajusta a capitalização do texto e aplica ALT em avatares. O objetivo é cobrir imagens que foram inseridas sem texto alternativo, melhorando acessibilidade e o SEO de imagens sem trabalho manual.

A confusão mais comum, e o motivo número um do módulo parecer que não funciona, é que o Rank Math aplica esses atributos de forma dinâmica, no momento em que a página é carregada, e não grava nada na Biblioteca de Mídia. Por isso a imagem continua aparecendo sem ALT dentro do wp-admin, mas o atributo está presente no HTML da página publicada. Quando o módulo realmente não está agindo, a causa costuma ser ele estar desativado em Modules, os campos de formato estarem vazios ou outro plugin sobrescrever o filtro de saída do conteúdo.

## Como identificar

- As imagens do post continuam aparecendo sem o atributo ALT no código-fonte da página publicada, mesmo com o módulo Image SEO supostamente ligado.
- Na Biblioteca de Mídia o campo 'Texto alternativo' continua vazio e a pessoa conclui que o Rank Math 'não fez nada', quando na verdade o módulo nunca grava ali.
- O cartão do módulo aparece como 'Inactive' em Rank Math SEO -> Dashboard -> Modules e a aba Images some de General Settings.
- O ALT e o title saem repetidos e iguais em todas as imagens porque o campo de formato ficou só com a variável %filename% ou ficou em branco.
- Ferramentas de auditoria (Lighthouse, Site Audit) seguem acusando 'image elements do not have alt attributes' mesmo depois de configurar o módulo.

**Antes de começar:** Antes de ativar ou desativar módulos e plugins em um site no ar, faça um backup completo (arquivos e banco de dados) ou teste primeiro em um ambiente de staging, para reverter caso a alteração afete a saída das imagens em produção.

## Como prevenir

- Mantenha o módulo Image SEO ativo e os formatos de ALT e title preenchidos com variáveis que gerem textos distintos por imagem, evitando ALT repetido em todo o site.
- Trate o módulo como uma rede de segurança, não como substituto: continue preenchendo o texto alternativo real na Biblioteca de Mídia para imagens importantes, já que o Rank Math só completa as que estão sem ALT.
- Padronize a limpeza de cache após mudar configurações de imagem, para que a página servida reflita os novos atributos injetados.
- Documente quais outros plugins filtram a saída do conteúdo (cache, otimização de imagem, outro SEO) para identificar rápido se algum deles sobrescreve os atributos do Rank Math.

Erros relacionados

- [Como corrigir o schema do Rank Math que não lê custom fields do ACF PRO](https://full.services/wp-fixer/corrigir-schema-rank-math-acf/)
- [Como corrigir o Link Counter do Rank Math que não conta links](https://full.services/wp-fixer/corrigir-link-counter-rank-math/)
- [Como corrigir a integração do Analytics no Rank Math PRO](https://full.services/wp-fixer/corrigir-analytics-integration-rank-math/)

## Causa

- O módulo Image SEO está com o status Inactive em Rank Math SEO -> Dashboard -> Modules, então a aba Images nem aparece em General Settings e nenhum atributo é injetado.
- As opções 'Add Missing ALT Attributes' e 'Add Missing Title Attributes' estão desligadas em General Settings -> Images, então o Rank Math não preenche os atributos ausentes.
- Os campos 'Image Alt Attribute Format' e 'Title Attribute format' ficaram vazios, o que faz o Rank Math não ter um padrão para gerar o ALT ou o title e a saída sair em branco.
- A expectativa está errada: o módulo aplica ALT e title dinamicamente no HTML da página no carregamento e nunca grava na Biblioteca de Mídia, então olhar só o wp-admin dá a impressão de que não funcionou.
- Um plugin de cache ou de otimização de imagem serve a página a partir de um HTML antigo, ou outro plugin de SEO filtra a saída do conteúdo depois do Rank Math, sobrescrevendo os atributos injetados.
- As imagens em questão já possuem um ALT (mesmo que vazio com aspas) ou foram inseridas como background via CSS pelo tema ou page builder, e o módulo só preenche atributos que estão realmente ausentes na tag img do conteúdo.

## Como resolver

1. Ative o módulo Image SEO: Confirme que o módulo está ligado antes de procurar qualquer configuração. Enquanto ele estiver Inactive, a aba Images nem aparece nas configurações e nenhum atributo é injetado nas imagens.

```
Painel WP -> Rank Math SEO -> Dashboard -> Modules
Localize o cartão 'Image SEO' e clique para deixar o status como Active
```

2. Ligue o preenchimento de ALT e title: Abra a aba Images e ative as duas chaves principais. São elas que mandam o Rank Math completar os atributos que estiverem ausentes nas imagens do conteúdo.

```
Painel WP -> Rank Math SEO -> General Settings -> Images
Ligue 'Add Missing ALT Attributes'
Ligue 'Add Missing Title Attributes'
```

3. Preencha os formatos de ALT e title: Defina um padrão para o texto gerado usando as variáveis do Rank Math. Se os campos 'Image Alt Attribute Format' e 'Title Attribute format' ficarem vazios, o atributo sai em branco. Combine o título do post com o nome do arquivo para gerar textos distintos por imagem.

```
Em Image Alt Attribute Format, use por exemplo: %title% %count%
Em Title Attribute format, use por exemplo: %title% %filename%
Clique em Save Changes
```

4. Verifique no HTML da página, não na Biblioteca de Mídia: Como o módulo injeta os atributos dinamicamente no carregamento, eles não aparecem na Biblioteca de Mídia. Abra a página publicada e inspecione o código para confirmar que o ALT está presente na tag de imagem.

```
Abra a página publicada no navegador
Clique com o botão direito sobre a imagem -> Inspecionar
Confirme que a tag de imagem agora tem o atributo alt preenchido
```

5. Limpe o cache e isole conflitos: Se o ALT ainda não aparece no HTML, limpe todos os caches para servir a página atualizada e teste se outro plugin sobrescreve a saída. Um plugin de cache servindo HTML antigo ou outro plugin de SEO filtrando o conteúdo derruba os atributos injetados.

```
Limpe o cache do plugin de cache e do CDN/Cloudflare
Desative temporariamente plugins de otimização de imagem e de outro SEO
Recarregue a página e inspecione a tag de imagem novamente
```


## Código

```php
<?php
// Personaliza o ALT injetado pelo modulo Image SEO do Rank Math
// quando o atributo esta ausente na imagem do conteudo.
add_filter( 'rank_math/sitemap/enable_caching', '__return_false' );

add_filter( 'rank_math/image_seo/alt', 'full_rank_math_image_alt', 10, 2 );
function full_rank_math_image_alt( $alt, $attachment_id ) {
    if ( ! empty( $alt ) ) {
        return $alt; // ja tem ALT real: nao sobrescreve.
    }
    $title = get_the_title();
    $file  = get_post_meta( $attachment_id, '_wp_attached_file', true );
    $name  = $file ? pathinfo( $file, PATHINFO_FILENAME ) : '';
    return trim( $title . ' ' . str_replace( array( '-', '_' ), ' ', $name ) );
}
```

## Perguntas frequentes

### Por que o Rank Math não grava o ALT na Biblioteca de Mídia

Porque o módulo Image SEO foi feito para aplicar ALT e title dinamicamente no HTML da página no momento do carregamento, sem alterar os registros da Biblioteca de Mídia. Por isso o campo continua vazio no wp-admin, mas o atributo aparece no código da página publicada.

### Onde fica a configuração do Image SEO no Rank Math

Primeiro ative o módulo em Rank Math SEO -> Dashboard -> Modules, no cartão Image SEO. Depois as opções ficam em Rank Math SEO -> General Settings -> Images, onde você liga o preenchimento de ALT e title e define os formatos.

### O Image SEO do Rank Math é gratuito ou só PRO

Adicionar ALT e title ausentes e definir os formatos desses atributos está disponível na versão gratuita. Recursos como legenda, descrição, ajuste de capitalização e ALT em avatares são exclusivos do Rank Math PRO.

### Por que o ALT das minhas imagens ficou todo igual

Isso acontece quando o campo de formato usa só uma variável fixa como o título do post. Combine variáveis que variem por imagem, como %filename% ou %count%, junto com %title%, para que cada imagem receba um texto alternativo distinto.

### O módulo preenche ALT em imagens de fundo do tema ou do page builder

Não. O Image SEO só completa o atributo de imagens que estão na tag img do conteúdo e que estão sem ALT. Imagens inseridas como background via CSS pelo tema ou por um page builder não são alcançadas pelo módulo.

### Ativei o módulo mas o ALT continua sem aparecer, o que falta

Verifique se as chaves Add Missing ALT Attributes e Add Missing Title Attributes estão ligadas, se os campos de formato não estão vazios e limpe o cache do site e do CDN. Inspecione o HTML da página publicada, não a Biblioteca de Mídia, para confirmar o atributo.

### O Lighthouse ainda acusa imagens sem alt depois de configurar

Confirme que a auditoria roda sobre a página publicada com cache limpo, já que o atributo é injetado no carregamento. Se persistir, verifique se um plugin de otimização ou de cache serve um HTML antigo, ou se outro plugin filtra a saída do conteúdo após o Rank Math.

**Fonte:** [Rank Math — How to Use the Image SEO Module](https://rankmath.com/kb/image-seo/)