Idiomas

Como implementar hreflang (passo a passo)

Código funcional para os três métodos de hreflang — tags HTML no head, cabeçalhos HTTP Link e anotações em sitemap XML — além das regras de sintaxe, automação de CMS em escala e o fluxo de validação para confirmar que foi realmente implementado corretamente.

Publicado pela primeira vez: 2 de jul. de 2026 · Última atualização: 3 de ago. de 2026 · Avançado
Idiomas
AIEscrito porAI v2
1 sinal de evidência nesta página

Existem exatamente três maneiras de adicionar hreflang — tags link HTML no head, cabeçalhos de resposta HTTP Link (para arquivos não HTML, como PDFs) ou entradas xhtml:link em um sitemap XML (melhor em escala). Escolha uma; o Google trata as três como equivalentes e não há benefício em combiná-las. Cada método obedece às mesmas duas regras inegociáveis: autorreferência (cada página lista a si mesma) e reciprocidade (se A aponta para B, B deve apontar de volta para A, ou o Google ignora o par). Os códigos são ISO 639-1 para idioma mais região opcional ISO 3166-1 alpha-2; x-default é o fallback. Gere tudo a partir de uma única fonte de verdade e valide o head renderizado, não apenas o view-source — no meu estudo de 374 756 domínios, mais de 67% das configurações de hreflang tinham pelo menos um problema.

TL;DR — Três métodos, escolha um: tags HTML <link> no <head>, cabeçalhos HTTP Link: (a única opção para arquivos não HTML, como PDFs), ou entradas <xhtml:link> em um sitemap XML (melhor em escala — um arquivo gerado por máquina, mais fácil de fazer QA). O Google diz que os três são equivalentes e não há benefício em combiná-los. Todo método obedece à autorreferência + reciprocidade, usa URLs absolutas e usa códigos de idioma ISO 639-1 + códigos de região opcionais ISO 3166-1 alpha-2. Gere tudo a partir de uma única fonte de verdade — hreflang mantido manualmente apodrece. Depois valide o <head> renderizado, rastreie todo o cluster para verificar reciprocidade e continue verificando novamente após cada mudança de URL. Não faça redirecionamento automático de rastreadores por geolocalização.

Antes de escrever uma linha de código: três decisões

1. Qual método. O Google é explícito que a escolha é sobre conveniência, não performance — “The three methods are equivalent from Google’s perspective and you can choose the method that’s the most convenient for your site.” (tradução) «Os três métodos são equivalentes da perspectiva do Google e você pode escolher o método que for mais conveniente para o seu site.» Minha regra aproximada:

Evidence for this claim Google supports equivalent HTML, HTTP-header, and sitemap methods for declaring localized versions; HTTP headers can be used for non-HTML files such as PDFs. Scope: Google Search hreflang implementation methods. Confidence: high · Verified: Google: Localized versions
  • Um punhado de URLs, um site estático ou simples, poucos locais → tags HTML <link>.
  • Ativos não HTML (PDFs, documentos) → cabeçalhos HTTP Link: (você não tem outra opção — não há <head> em um PDF).
  • Muitos locais, um pipeline de sitemap existente ou uma configuração headless/JAMstack → sitemap XML, gerado programaticamente.

A lente Decision Trees percorre isso como um fluxograma real.

2. Uma única fonte de verdade. Qualquer que seja o método escolhido, as anotações devem ser geradas a partir de um lugar — uma tabela de locais/traduções no seu banco de dados, um campo de relacionamento no CMS ou (para sites pequenos) uma única planilha. O pior anti-padrão de hreflang é manter tags manualmente por página. No momento em que o template de um local se desvia, os links de retorno desaparecem e os pares são descartados.

3. Não combine métodos. Você pode executar todos os três; o Google diz que não há benefício, e cada método extra é outra superfície para as três cópias discordarem entre si.

Evidence for this claim Google requires fully qualified alternate URLs and reciprocal links, and recommends including each page itself in its alternate set. Scope: Google Search hreflang rules shared by all delivery methods. Confidence: high · Verified: Google: Hreflang guidelines

Método 1 — tags HTML <link> no <head>

A sintaxe, verbatim do Google, é:

<link rel="alternate" hreflang="lang_code" href="url_of_page" />

Um conjunto completo e funcional para um cluster multilíngue e multirregional com um fallback:

<link rel="alternate" hreflang="en-us" href="https://example.com/us/" />
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Esse bloco exato vai em cada página do cluster (a página dos EUA, a página do Reino Unido, a página alemã e a página inicial) — cada uma inclui sua própria linha de autorreferência. É isso que satisfaz a reciprocidade.

A colocação é uma regra rígida. Google: “The <link> tags must be inside a well-formed <head> section of the HTML.” (tradução) «As tags <link> devem estar dentro de uma seção <head> bem formada do HTML.» E o conselho de solução de problemas deles: “If in doubt, paste code from your rendered page into an HTML validator to ensure that the links are inside the <head> element.” (tradução) «Em caso de dúvida, cole o código da sua página renderizada em um validador HTML para garantir que os links estejam dentro do elemento <head>.»

Isso importa mais do que parece, por causa de um modo de falha que a maioria dos guias escritos ignora: as tags hreflang podem ser forçadas para fora do <head> e para dentro do <body>, onde são inválidas. Na minha apresentação Pubcon Vegas 2019 eu sinalizei isso diretamente — tags não podem legitimamente viver no body (isso permitiria que um site sequestrasse os alternates de outro), mas uma tag <p> malformada ou injetada, ou um iframe, pode fechar prematuramente o <head> para que tudo depois dele — incluindo seu hreflang — seja renderizado dentro do <body>. A tag está tecnicamente presente no código-fonte, mas silenciosamente inválida. A maneira mais rápida de depurar isso é com breakpoints de DOM do navegador: observe onde as tags realmente caem no DOM renderizado e depois volte à marcação que quebrou o <head>.

Quando as tags HTML fazem sentido: sites pequenos a médios com um número gerenciável de locais, onde o bloco <link> por página não infla. Em um site com dezenas de locais, cada página carrega um grande bloco de marcação — que é uma das razões pelas quais os grandes sites dependem do método de sitemap.

Não misture hreflang com outros atributos alternate no mesmo elemento <link>. A orientação do Google é explícita: um <link rel="alternate"> que carrega hreflang não deve também carregar um atributo alternate não relacionado, como media, na mesma tag — se você precisar de um alternate de idioma/região e um alternate de media query para a mesma URL, são dois elementos <link> separados, não um combinado. Misturá-los é uma maneira fácil de acabar com uma tag que o Google não consegue interpretar como nenhum dos dois.

Método 2 — Cabeçalhos Link: HTTP

Mesma informação, enviada na resposta HTTP em vez do HTML. A sintaxe:

Link: <https://example.com/file.pdf>; rel="alternate"; hreflang="en",
      <https://de-ch.example.com/file.pdf>; rel="alternate"; hreflang="de-ch"

Observe os colchetes angulares ao redor de cada URL, os atributos separados por ponto e vírgula e a vírgula separando cada alternate. Cada URL no cabeçalho é acrescentada com vírgula.

Quando você precisa disso: recursos não HTML. Um PDF, um .doc, uma imagem servida diretamente — nenhum deles tem um <head> para conter tags <link>, então o cabeçalho é a única maneira de anexar hreflang a eles.

Considerações de configuração: você define esses cabeçalhos na camada do servidor ou CDN (uma diretiva Header do Apache, um add_header do Nginx, uma regra de cabeçalho de resposta do Cloudflare/Fastly/CloudFront ou a resposta do seu aplicativo). Como o cabeçalho é definido pela infraestrutura em vez de marcação por documento, a regra de reciprocidade é fácil de quebrar aqui — o cabeçalho do PDF em inglês e o cabeçalho do PDF em alemão geralmente são configurados separadamente, então cabe a você garantir que cada um liste o conjunto completo, incluindo a si mesmo. Mantenha a geração do cabeçalho orientada pela mesma tabela de locales que sua abordagem de HTML/sitemap.

O invariante a manter: cada resposta alternate carrega o conjunto completo idêntico, todas as vezes. Não basta que o cabeçalho do PDF em inglês liste o alternate em alemão — a resposta do PDF em alemão tem que carregar exatamente o mesmo conjunto de volta (ele mesmo mais todos os outros alternates), em cada resposta, não apenas na primeira que um crawler encontrar. Trate o cabeçalho como saída gerada, não como algo único que você define e esquece.

Método 3 — Anotações <xhtml:link> no sitemap XML

Em escala, geralmente é a decisão certa: todo o cluster vive em um (ou alguns) arquivos gerados por máquina, nada incha o <head> de cada página e — como todo o grafo de relacionamentos está em um só lugar — é de longe o método mais fácil de fazer QA. A sintaxe:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://www.example.com/english/page.html</loc>
    <xhtml:link rel="alternate" hreflang="de"
                href="https://www.example.de/deutsch/page.html"/>
    <xhtml:link rel="alternate" hreflang="en"
                href="https://www.example.com/english/page.html"/>
  </url>
  <url>
    <loc>https://www.example.de/deutsch/page.html</loc>
    <xhtml:link rel="alternate" hreflang="de"
                href="https://www.example.de/deutsch/page.html"/>
    <xhtml:link rel="alternate" hreflang="en"
                href="https://www.example.com/english/page.html"/>
  </url>
</urlset>

Duas coisas que confundem as pessoas no método de sitemap:

  1. A declaração de namespace é obrigatória. Esse xmlns:xhtml="http://www.w3.org/1999/xhtml" no elemento <urlset> não é decoração opcional — omita-o e cada <xhtml:link> no arquivo será inválido.
  2. Cada bloco <url> deve ser autossuficiente. Observe que ambos os blocos <url> acima listam ambos os alternates, incluindo seu próprio <loc>. Cada entrada <url> carrega o conjunto completo (autorreferência + todos os alternates). Reciprocidade em um sitemap é apenas “o bloco de cada URL lista todas as URLs do cluster, incluindo a si mesma.”

Dois comportamentos que vale a pena conhecer para não superdimensionar o gerador: a ordem dos filhos <xhtml:link> dentro de um bloco <url> não importa para o Google — não perca tempo ordenando-os — e essas anotações <xhtml:link> não contam contra o limite de 50 000 URLs por arquivo do seu sitemap, já que são filhos de uma entrada <url>, não entradas <url> separadas.

Gerando programaticamente. O objetivo do método de sitemap é que ele é um subproduto dos próprios dados de tradução do seu CMS. Se o seu CMS já sabe que /english/page.html e /deutsch/page.html são traduções um do outro, seu gerador de sitemap deve percorrer essa tabela de relacionamentos e emitir os blocos <xhtml:link> no momento da compilação (ou no momento da solicitação do sitemap). Faça isso e hreflang não pode sair de sincronia com a realidade — ele é regenerado a partir da fonte de verdade todas as vezes, e adicionar um locale é uma mudança de dados, não uma edição manual em centenas de páginas.

Para equipes sem recursos de desenvolvimento, criei um modelo leve de Google Sheets no meu guia de hreflang da Ahrefs: uma aba Setup (escolha um idioma padrão e até quatro variantes), uma aba URLs (cole as URLs de cada idioma em colunas) e uma aba Results que gera automaticamente o bloco de XML do sitemap para você. É a ideia de “fonte única de verdade” tornada concreta para sites pequenos demais para justificar uma integração real de CMS.

As regras que se aplicam independentemente do método escolhido

Estas são independentes do método e inegociáveis.

  • Autorreferência. Cada página (ou cada bloco <url>, ou cada cabeçalho) lista a si mesma. Mueller apresenta isso como opcional, mas boa prática; no entanto, sua ausência estava presente em 18,0% dos domínios no meu estudo — automatize e não custa nada.
  • Reciprocidade. “Each language version must list itself as well as all other language versions.” E a aplicação: “If two pages don’t both point to each other, the tags will be ignored. This is so that someone on another site can’t arbitrarily create a tag naming itself as an alternative version of one of your pages.” (tradução) «Cada versão de idioma deve listar a si mesma, bem como todas as outras versões de idioma.» E a aplicação: «Se duas páginas não apontarem uma para a outra, as tags serão ignoradas. Isso é para que alguém em outro site não possa criar arbitrariamente uma tag nomeando a si mesma como uma versão alternativa de uma de suas páginas.» Um link de retorno ausente derruba o par.
  • URLs absolutas e totalmente qualificadas. “Alternate URLs must be fully-qualified, including the transport method (http/https)” — portanto, https://example.com/foo, nunca //example.com/foo ou /foo. E a URL deve corresponder à forma exata que o Google indexa: protocolo, www, barra final e maiúsculas/minúsculas precisam estar alinhados, ou a correspondência do link de retorno falha.

Acertando os códigos

“The first code of the hreflang attribute is the language code (in ISO 639-1 format) followed by an optional second code that represents the region code (in ISO 3166-1 Alpha 2 format).” (tradução) «O primeiro código do atributo hreflang é o código do idioma (no formato ISO 639-1) seguido por um segundo código opcional que representa o código da região (no formato ISO 3166-1 Alpha 2).» Combine-os com um hífen: en-US. Você pode segmentar um idioma isoladamente (es = espanhol em qualquer lugar), mas não pode segmentar uma região isoladamente — sempre há um idioma primeiro.

Os erros que vejo com mais frequência (e vi no conjunto de dados do estudo):

  • en-UK em vez de en-GB — uk é ucraniano, o código de região do Reino Unido é gb.
  • jp em vez de ja para japonês, cn em vez de zh para chinês.
  • Códigos de três letras (ger, eng) onde é necessário o ISO 639-1 de duas letras.
  • Usar EU, UN ou UK como códigos de região — nenhum é um alvo válido ISO 3166-1 alpha-2.

x-default é o valor reservado para o fallback — um seletor de idioma ou uma página inicial com redirecionamento automático que atende usuários que não correspondem a nenhuma das suas localidades explícitas:

<link rel="alternate" href="https://example.com/" hreflang="x-default" />

Não é obrigatório. Foi o elemento mais ausente no meu estudo (56,3% dos domínios o omitiram), mas um x-default ausente não quebra o cluster da mesma forma que uma tag recíproca ausente — o Google simplesmente recorre à própria detecção de idioma/região para usuários sem correspondência. Adicione mesmo assim; é um item de checklist, não um quebrador de cluster. (Há um subtópico dedicado a x-default neste cluster.)

Implementando em escala — abordagens de CMS e plataforma

WordPress. O Yoast SEO não gera hreflang por conta própria. Para realmente emitir tags, você precisa de um plugin multilíngue — WPML ou Polylang. O WPML gera automaticamente hreflang para cada página que tem traduções, adiciona um x-default apontando para a versão no seu idioma padrão e, por padrão, injeta as anotações no sitemap XML; há uma configuração em WPML → Languages → SEO Options (“Display alternative languages in the HEAD section”) se você quiser a saída de tags no cabeçalho em vez de, ou além do, sitemap. (Veja a documentação do WPML sobre como usar com o Yoast.)

Shopify. O Shopify Markets automaticamente gera tags hreflang mutuamente vinculadas depois que você configura mercados/idiomas e o conteúdo é publicado e vinculado na navegação — o que elimina o modo de falha mais comum (links recíprocos ausentes) por design. O problema: as tags automáticas do Markets são frequentemente apenas de idioma (fr, de) em vez de idioma-região (fr-FR, fr-CA), o que atende mal marcas que precisam de especificidade regional — francês para França vs. Canadá vs. Bélgica. Para isso, você recorre a tags <link> manuais em theme.liquid (a documentação de hreflang do tema do próprio Shopify mostra o padrão) ou a um aplicativo — e tenha cuidado, porque misturar tags automáticas do Markets com tags manuais/de aplicativo é uma fonte documentada de conflitos. Escolha um.

Personalizado / headless / enterprise. Gere as anotações a partir da sua tabela de relacionamento de tradução no momento do build ou do serve, conforme descrito na seção de sitemap acima. Este é o mesmo princípio de “fonte única de verdade” — o hreflang se torna uma saída computada de dados que seu CMS já possui, não um artefato mantido manualmente que pode se deteriorar.

Erros de implementação que quebram o cluster

Redirecionamento automático por geo/IP. Esta é uma falha separada dos erros de sintaxe e é pior. Se você redirecionar visitantes — e especialmente rastreadores — para uma versão baseada na localização percebida, você pode desindexar clusters regionais inteiros, porque o Googlebot rastreia principalmente dos EUA. Como eu disse naquela apresentação do Pubcon: um geo-redirecionamento “redirecionaria os mecanismos de busca para onde eles rastreiam. O Google, por exemplo, rastreia principalmente dos EUA, então efetivamente desindexaríamos todas as páginas geo.” Há também um ângulo regulatório — exposição potencial sob as regras da UE contra o bloqueio geográfico. O padrão correto é redirecionar usuários, nunca rastreadores: detecte e (opcionalmente) redirecione visitantes humanos, mas sempre permita que os bots alcancem cada variante de URL diretamente, com o hreflang fornecendo o sinal de roteamento real. A própria orientação multirregional do Google recomenda um banner de sugestão não intrusivo em vez de redirecionamento automático exatamente por esse motivo.

Apontar hreflang para URLs não canônicas, redirecionadas ou com noindex. Se a URL de um locale mudar e o redirecionamento for configurado, mas o hreflang ainda apontar para a URL antiga, seu cluster agora referencia um 301 ou um 404 (16,9 % dos domínios no meu estudo referenciavam páginas quebradas/redirecionadas). Da mesma forma, cada variante deve canonicalizar para si mesma; apontar hreflang para uma URL que foi canonicalizada, ou para uma página com noindex, quebra o link de retorno (8,0 % apontavam para URLs não canônicas).

Formatos de URL inconsistentes. A URL do hreflang e a URL indexada precisam ser idênticas em forma — barra final, www, protocolo e maiúsculas/minúsculas incluídos. Uma incompatibilidade aqui é uma falha silenciosa de reciprocidade.

Validando sua implementação após o lançamento

Veja o código-fonte renderizado, não apenas o código-fonte bruto. Se o seu hreflang for injetado por JavaScript no lado do cliente, curl ou Ctrl+U (“Ver código-fonte da página”) mostrará nada — mas as tags existem no DOM renderizado. Confirme com a Inspeção de URL do GSC → “Testar URL ao vivo” → “Ver página testada”, ou um rastreador com capacidade de renderização. Este é o motivo mais comum para alguém dizer “minhas tags estão ausentes” quando na verdade estão corretas (ou o contrário — presentes no código-fonte, mas quebradas porque renderizam no <body>).

Rastreie o cluster inteiro, não verifique apenas uma URL. A reciprocidade é uma relação entre páginas, então verificar uma página não diz quase nada. Execute um rastreador em todo o cluster — a auditoria de hreflang do Screaming Frog ou o Site Audit da Ahrefs — para detectar tags de retorno ausentes, alvos não canônicos e referências quebradas em escala. A aba Hreflangs do Site Audit da Ahrefs desenha o cluster como um gráfico com links quebrados em vermelho, o que é muito mais fácil de entender do que um CSV.

Verifique as SERPs reais com &hl= e &gl=. Acrescente os parâmetros de idioma do host (&hl=) e geolocalização (&gl=) a uma URL de pesquisa do Google para visualizar o que os resultados de um determinado local realmente mostram, em vez de adivinhar com base na sua própria localização.

A validação não é uma etapa única. Novos locais, mudanças de URL/redirecionamento e configurações de dev/staging que vazam para a produção são as causas recorrentes de problemas pós-lançamento. Incorpore verificações de hreflang em testes de regressão e rastreamentos recorrentes, não apenas em uma verificação de QA no dia do lançamento. Meu enquadramento nas palestras: “qualquer número de coisas pode quebrar, desde mascaramento até coisas que são transferidas de ambientes dev/test/staging.”

Mitos que vale a pena aposentar

  • “Sitemaps processam mais rápido do que tags HTML.” Falso. Ambos são resolvidos no momento do rastreamento — eu já desmascarei isso diretamente. A vantagem do sitemap é a facilidade de manutenção e o QA, não a velocidade.
  • “O Yandex não suporta hreflang em sitemaps.” Falso — a própria documentação do Yandex confirma o suporte a hreflang em sitemaps.
  • “Use todos os três métodos para sinal extra.” Sem benefício segundo o Google, e isso apenas multiplica o risco de inconsistência.
  • “A falta de x-default quebra o cluster.” Falso — é opcional; o Google recorre à própria detecção.
  • “Hreflang errado gera penalização.” Falso — é uma dica, não uma diretiva. Hreflang quebrado é ignorado, não penalizado.

Onde ir a seguir

Este artigo é o aprofundamento prático sob o hub hreflang — o hub cobre o que é hreflang, por que a reciprocidade importa e o que o Bing faz em vez disso. O subtópico x-default aprofunda o valor de fallback. Para a estratégia que isto implementa, veja o pilar International SEO — hreflang é a camada técnica, não um substituto para uma localização genuína.

Add an expert note

Pin an expert quote

New person? Create their unclaimed profile at /admin/experts/ → Pin a quote first.