Gerador de hreflang: monte a malha das suas versões de idioma

Para quem é esta página: quem tem o mesmo conteúdo em mais de um idioma e precisa declarar isso sem quebrar a reciprocidade. Se o que você quer são as outras tags do head de uma página só, como title, description, canônica e Open Graph, o lugar é o gerador de meta tags. Se o assunto é dado estruturado, que é outro formato e outra função, vá para o gerador de schema FAQ. E se a dúvida é sobre rastreio do site inteiro, o caminho é o gerador de robots.txt. Aqui o escopo é um só: a ligação entre as versões de idioma da mesma página.

O hreflang é a única marcação do head cuja unidade não é a página

Quase toda tag de SEO descreve a página em que ela está. O hreflang descreve um grupo. Ele diz que aquele endereço em português, aquele em inglês e aquele em espanhol são a mesma página em idiomas diferentes, e pede ao buscador que entregue a versão certa para cada pessoa. O efeito não é ganhar posição: é trocar qual endereço aparece na posição que você já tem, e evitar que as suas próprias versões concorram entre si como se fossem conteúdo repetido.

Daí vem a regra que derruba a maioria das implementações: o bloco precisa ser recíproco e conter a si mesmo. Cada versão carrega a lista inteira, inclusive a própria. Quando a versão em inglês aponta para a portuguesa mas a portuguesa não aponta de volta, o par não é confirmado e é descartado em silêncio. É por isso que este gerador não produz o bloco de uma página só: ele recebe o grupo e devolve o bloco que vale para todas, igualzinho em cada uma. Copiar a mesma coisa em todo lugar é o comportamento certo, e não um atalho.

Como usar

1. Escreva uma linha por versão, no formato código e URL, separados por espaço. Inclua a versão que você está editando: ela também entra na lista.
2. Confira os códigos. O primeiro valor é o idioma em duas letras minúsculas, e a região é opcional, em duas letras maiúsculas, depois do hífen. O gerador conserta sublinhado e caixa e avisa quando faz isso.
3. Escolha o formato de saída: tags no head para a maioria dos casos, cabeçalho HTTP para arquivos que não são HTML, sitemap XML para site grande.
4. Escolha qual versão responde pelo x-default, que é quem atende o público que não bate com nenhum idioma da lista.
5. Confira a nota e os avisos, clique em copiar e aplique o bloco em todas as URLs da lista, sem editar nada entre uma e outra.

Como funciona: o que a nota mede

A nota vai de 0 a 100 e é a soma de oito checagens, cada uma correspondendo a um jeito conhecido de a malha quebrar. Todas são tudo ou nada, de propósito: hreflang não tem meio-termo útil, porque um código inválido não é lido pela metade, ele simplesmente não é lido.

Duas checagens costumam surpreender. A de barra final existe porque muitos servidores tratam o endereço com e sem barra como páginas diferentes: quando metade da lista tem barra e a outra metade não, metade dos pares aponta para um redirecionamento, e hreflang que cai em redirecionamento não conta. A de URL repetida existe porque a mesma página não pode responder por dois idiomas: os dois pares se anulam e o buscador descarta ambos.

Exemplo trabalhado (reproduz o resultado padrão)

O exemplo já carregado é uma página de preços em três idiomas, com o x-default apontando para a versão em inglês. Conferindo o painel, número por número:

• 3 versões e 3 idiomas: português, inglês e espanhol, cada um com a sua região.
• 4 tags geradas. São as três versões mais a linha de x-default, que se soma às outras em vez de substituir uma delas.
• Nota 100, faixa A, com as oito checagens verdes e apenas os dois lembretes de sempre na lista de avisos: o da autorreferência e o da reciprocidade, que a ferramenta não consegue conferir do lado de cá.

Agora troque, na segunda linha, o código en-US por en-UK, que é o erro mais frequente do atributo. Sem mexer em mais nada, o painel responde: a checagem de códigos válidos cai para 0 de 22, a nota vai para 78, a faixa cai de A para B e aparece o aviso da armadilha de região explicando que Reino Unido é GB. As outras sete checagens continuam verdes, e o número de tags continua 4: a malha não desaba, ela mostra exatamente quanto custou aquele código.

Troque agora o formato para sitemap XML e olhe a saída: são três blocos de URL, um por versão, cada um listando as quatro tags. É a malha completa, com a reciprocidade escrita por construção, num arquivo só. É exatamente assim que o sitemap deste blog é montado para as versões em português, inglês e espanhol.

Como interpretar cada número

A nota responde se o bloco está pronto para colar, e não se o hreflang vai funcionar. Ela mede o formato, que é a parte sob o seu controle; o que decide o resultado é a reciprocidade completa, e disso só o buscador tem a visão inteira.

A contagem de versões contra a de idiomas revela um caso comum: cinco versões e dois idiomas significa que você tem o mesmo idioma em várias regiões, como pt-BR e pt-PT. Isso é legítimo, e vale conferir se o conteúdo realmente muda entre elas. Se for o mesmo texto para os dois países, muitas vezes uma versão só, sem região, resolve melhor.

A contagem de tags é o número de versões mais um quando existe x-default. Se ela vier igual ao número de versões, o x-default não entrou, e a checagem correspondente diz isso.

Os avisos não descontam nota sozinhos: eles explicam o desconto que as checagens já fizeram, e dois deles aparecem sempre, mesmo com nota cheia, porque são as duas coisas que nenhuma ferramenta client-side consegue verificar por você.

Limites conhecidos

A ferramenta confere formato, não existência. Ela não visita as URLs, não confirma que a página do outro lado aponta de volta e não lê a canônica de cada versão, porque tudo isso exigiria uma chamada de rede e quebraria a promessa de que a sua lista não sai do navegador. Depois de publicar, confira com o inspetor de URL do Search Console ou com um rastreador do site: é lá que a falta de reciprocidade aparece.

Também vale saber o que o hreflang não faz. Ele não traduz nada, não cria versão nenhuma e não melhora posição. Página traduzida por máquina, sem revisão, continua sendo conteúdo fraco com a marcação certa. E se as versões estiverem em domínios diferentes, o atributo funciona igual, desde que todos sejam seus e a reciprocidade seja mantida entre eles.

Por fim, o suporte varia entre buscadores. O Google usa o atributo como sinal, não como ordem: ele pode ignorar a sua indicação quando os outros sinais da página contradizem, e a canônica é o mais forte deles. Outros buscadores tratam idioma e região com pesos próprios. Marcação bem feita aumenta a chance de a versão certa aparecer, e não garante que ela apareça sempre.

Do bloco colado ao teste no ar

Declarar o idioma é o começo. Depois vem a pergunta de sempre, que é o que acontece com quem chega:

• Monte o resto do head da página no gerador de meta tags, e confira se a canônica de cada versão aponta para ela mesma.
• Veja o desenho do seu resultado na busca, com o ponto exato do corte, no simulador de SERP.
• Antes de decidir se uma versão da página converte mais que a outra, veja quanto tráfego o teste exige na calculadora de tamanho de amostra.
• Com o teste no ar, leia o veredito na calculadora de significância estatística em vez de encerrar no primeiro dia bom.
• Para entender como as respostas de IA tratam o que você publica em cada idioma, veja o checklist de prontidão GEO.

Perguntas frequentes

O que o hreflang faz, na prática?

Ele diz ao buscador que duas ou mais URLs são a mesma página em idiomas ou países diferentes, para que a pessoa receba a versão certa na busca. O hreflang não muda posição: ele troca qual endereço aparece. Um brasileiro procurando pelo seu produto continua encontrando a mesma página, só que na versão em português em vez da versão em inglês. Sem o atributo, as versões podem competir entre si como conteúdo parecido, e a que aparece é a que o buscador achar mais forte, que nem sempre é a do idioma de quem buscou.

Preciso mesmo listar a própria página no bloco?

Precisa, e essa é a regra mais quebrada do atributo. Cada página do grupo carrega a lista inteira, incluindo a si mesma, chamada de autorreferência. É isso que permite ao buscador confirmar que todas as versões concordam sobre o grupo. Um bloco que só aponta para as outras versões faz o conjunto ficar sem confirmação e costuma ser descartado inteiro, sem aviso nenhum. O gerador monta um bloco só justamente por isso: a mesma cópia vai em todas as versões, cada uma listando a si mesma.

x-default é obrigatório?

Não é obrigatório, mas resolve um problema que aparece cedo. Ele indica a versão que atende quem não bate com nenhum idioma da lista: alguém na Alemanha, com o navegador em alemão, num site que só tem português, inglês e espanhol. Sem x-default, o buscador escolhe sozinho qual mostrar. O uso mais comum é apontar para a versão em inglês, ou para uma página seletora de idioma quando ela existe. Uma coisa que confunde muita gente: o x-default não substitui a tag da própria versão, ele se soma a ela, e é por isso que a saída sai com uma tag a mais do que o número de versões.

Posso usar hreflang só com o código de país, tipo br ou uk?

Não. O primeiro valor é sempre o idioma, na sigla de duas letras da ISO 639-1, e a região é opcional e vem depois. hreflang igual a br não é Brasil, é bretão, o idioma da Bretanha francesa. hreflang igual a uk não é Reino Unido, é ucraniano. Reino Unido é GB. O detalhe cruel é que os dois valores são sintaticamente válidos, então nenhum validador de HTML reclama e nenhum erro aparece em lugar nenhum: a página simplesmente é servida ao público errado, e o problema só é descoberto quando alguém pergunta por que o tráfego de um mercado nunca chegou.

Tags no head, cabeçalho HTTP ou sitemap: qual escolher?

Os três são equivalentes para o buscador, e a escolha é de operação. As tags no head são as mais simples quando você controla o template da página. O cabeçalho HTTP é a única opção para arquivos que não são HTML, como um PDF em duas línguas. O sitemap é o mais eficiente em site grande: a malha inteira fica num arquivo só, sem tocar no HTML de nenhuma página, e é bem mais fácil de revisar em bloco. Escolha um e use só ele. Declarar nos três lugares não soma nada e multiplica a chance de um deles ficar desatualizado e contradizer os outros.

Quantas versões cabem no bloco?

Não há limite prático no atributo, e sites globais rodam com dezenas de versões. O que cresce é o custo: a malha completa tem uma tag por versão em cada página, então trinta idiomas viram trinta tags no head de trinta páginas. Aí o sitemap deixa de ser preferência e vira decisão de arquitetura, porque manter o head sincronizado à mão em trinta templates é onde a malha quebra. Se o seu número de versões passou de dez, gere o bloco em formato de sitemap e trate ele como arquivo de configuração, não como HTML escrito à mão.

O hreflang funciona sem a canônica bater?

Não funciona, e essa combinação é a segunda causa mais comum de malha ignorada. Cada URL do bloco precisa ser a mesma que a própria página declara como canônica. Se a versão em espanhol tem canônica apontando para a versão em inglês, você está dizendo duas coisas contraditórias: que ela é uma versão de idioma independente e que ela é uma cópia da inglesa. Diante da contradição, o buscador segue a canônica e joga o hreflang fora. A regra prática: canônica autorreferente em cada versão, e o hreflang apontando exatamente para essas canônicas.

O que eu digito aqui fica salvo em algum lugar?

Não. Tudo roda em JavaScript no seu navegador: a lista é lida, o bloco é montado e a nota é calculada na sua máquina, sem nenhuma chamada de rede, e nada é salvo nem registrado. A ferramenta também não visita as URLs que você informou, o que significa que ela confere o formato dos endereços e não a existência das páginas. Isso importa quando o site ainda não foi publicado e a lista revela um lançamento em outro mercado. Dá para conferir abrindo a aba de rede do navegador enquanto digita: nenhuma requisição sai.

Continue

Para entender o que muda entre otimizar para busca e otimizar para conversão, siga por CRO e SEO, o que muda em cada um, veja o guia de GEO em 2026 e aprenda a montar blocos citáveis em FAQ para citação por IA.