Hreflang: como configurar corretamente versões por idioma e país

Resumo: o hreflang diz ao Google qual versão de idioma ou país de uma página mostrar para cada pessoa que pesquisa. Cada versão lista todas as versões, inclusive a si mesma, com um código de idioma ISO 639-1 e uma região ISO 3166-1 alpha-2 opcional (en, de, en-GB, pt-BR), além de um fallback x-default opcional. Os links precisam ser absolutos e apontar nos dois sentidos, ou o Google os ignora. Cada versão precisa de um canonical autorreferente; um canonical que aponta para outro idioma cancela toda a configuração. O Google detecta o idioma da página pelo conteúdo, então a tradução precisa ser real.

Sites internacionais perdem tráfego de um jeito silencioso. A página em inglês ranqueia na Alemanha, a página em espanhol aparece no México quando você criou uma versão mexicana, ou a loja do Reino Unido aparece para buscadores americanos com preços em libras. Nada está quebrado no site; o Google simplesmente chutou qual versão mostrar. O hreflang é o jeito de impedir esse chute.

Este guia explica como o hreflang funciona segundo a documentação do Google, as regras de código que fazem a maioria dos sites tropeçar, como os canonicals interagem com ele, o que nosso verificador de hreflang gratuito testa e como corrigir cada problema.

O que o hreflang faz e o que não faz

As anotações hreflang descrevem um conjunto de páginas que são versões umas das outras: o mesmo conteúdo em outro idioma, ou o mesmo idioma adaptado para outro país. O Google as usa para mostrar a versão correspondente nos resultados.

O que ele não faz:

• Não detecta idioma. O Google afirma que "doesn't use hreflang or the HTML lang attribute to detect the language of a page"; ele usa o conteúdo visível (sites multirregionais). Uma página marcada como de com texto em inglês é uma página em inglês.
• Não transforma traduções fracas em duplicatas ou originais. O Google diz que versões localizadas "are only considered duplicates if the main content of the page remains untranslated." Uma página com menu traduzido e corpo de texto em inglês é uma duplicata.
• Não redireciona ninguém. Ele apenas muda qual URL aparece nos resultados. Os visitantes ainda podem abrir qualquer versão.

Os três jeitos de adicionar hreflang

O Google diz que os três métodos "are equivalent from Google's perspective." Use um por página; misturá-los só cria mais lugares para erros.

1. Elementos link em HTML no <head>, a escolha mais comum. Em https://example.com/en/pricing:

<link rel="alternate" hreflang="en" href="https://example.com/en/pricing" />
<link rel="alternate" hreflang="de" href="https://example.com/de/preise" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/tarifs" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing" />

As páginas em alemão e francês trazem exatamente as mesmas quatro linhas. O Google exige que as tags estejam "inside a well-formed <head> section"; um elemento solto que o navegador move para o body, como uma imagem ou uma tag não fechada acima dos links, pode encerrar o head antes da hora.

2. Cabeçalhos HTTP Link, a única opção para arquivos que não são HTML, como PDFs:

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

O Google diz que o cabeçalho deve ser idêntico em todas as versões.

3. Sitemap XML, prático para sites grandes porque não exige mudanças nos templates:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/en/pricing</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise"/>
  </url>
  <url>
    <loc>https://example.com/de/preise</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise"/>
  </url>
</urlset>

Cada <url> lista todas as versões, inclusive a si mesma.

As regras que o Google aplica

Links de retorno e autorreferência

"If two pages don't both point to each other, the tags will be ignored." Essa é a regra por trás da maioria das configurações quebradas. Se a página em inglês lista a página em alemão, mas a página em alemão não lista a em inglês, o Google descarta o par. O Google também diz que "each language version must list itself."

Códigos de idioma e região

"Only language codes listed in ISO 639-1 and region codes listed in ISO 3166-1 Alpha 2 are supported." O idioma vem primeiro; a região é opcional. O Google também aceita subtags de escrita (script) para idiomas escritos em mais de um sistema, como zh-Hant e zh-Hans, e combinações como zh-Hans-US.

Para o espanhol na América Latina, use es para uma única versão compartilhada em espanhol, ou liste os países específicos que você atende (es-MX, es-AR, es-CO) apontando para a mesma URL.

x-default

"The reserved x-default value is used when no other language/region matches the user's browser setting." Aponte-o para uma página de seleção de idioma ou para a sua versão internacional principal. É opcional, mas útil: sem ele, quem pesquisa em um idioma que você não oferece recebe a versão que o Google escolher.

URLs absolutas

"Alternate URLs must be fully-qualified, including the transport method." https://example.com/de/ funciona; /de/ e //example.com/de/ não.

Hreflang e tags canonical

Os dois precisam concordar. Cada versão deve ter um canonical apontando para si mesma, não para a versão em inglês ou principal. O guia de canonicalização do Google diz para "specify a canonical page in the same language," ou "the best possible substitute language if a canonical page doesn't exist for the same language," e observa que os clusters de hreflang influenciam a escolha do canonical, favorecendo URLs que se linkam reciprocamente.

O erro clássico: toda versão de idioma traz <link rel="canonical" href="https://example.com/en/...">. Isso diz ao Google que as outras versões são duplicatas da página em inglês, e elas saem do índice junto com suas anotações hreflang.

Dois outros conflitos a evitar: URLs de hreflang que redirecionam (liste a URL final) e URLs de hreflang com noindex (uma versão que o Google não pode indexar não pode ser exibida).

Estrutura do site e redirecionamentos automáticos

O guia multirregional do Google compara as estruturas de URL:

Qualquer que seja a escolha, não redirecione visitantes automaticamente por IP ou idioma do navegador. O Google diz que isso "could prevent users (and search engines) from viewing all the versions of your site" e que o Googlebot "usually originates from the USA." Mostre um banner de sugestão e deixe o hreflang cuidar dos resultados de busca.

Como funciona o verificador de hreflang da Searvia

O verificador de hreflang usa o mesmo motor do nosso verificador de SEO de sites: você informa um domínio ou o endereço de uma página, ele audita essa página (sua home, se você informar só o domínio) e os arquivos do site ao redor com 38 verificações em cerca de 20 segundos, e coloca em primeiro lugar as três verificações de que esta ferramenta trata. É exatamente isto que elas testam.

Versões de idioma, hreflang (prioridade baixa). O verificador lê todo elemento <link rel="alternate" hreflang="..." href="..."> no HTML dessa página, depois de seguir os redirecionamentos até o endereço final.

• Se não houver nenhum, o resultado é informativo: "No language versions are declared (fine for a single-language site)." Isso não afeta sua nota.
• Cada código é conferido com os códigos aceitos pelo Google: x-default, ou um idioma ISO 639-1 de duas letras, opcionalmente seguido de uma escrita de quatro letras (zh-Hant) e de um país ISO 3166-1 alpha-2 de duas letras (pt-BR, en-GB). Um erro comum como en-UK é marcado com a correção (→ en-GB); es-419, idiomas de três letras e outros códigos que o Google não aceita são marcados como inválidos. Cada linha do relatório mostra o código, sua URL, um check ou uma cruz e essa observação. São exibidas até 20 linhas.
• Ele verifica a autorreferência: uma das URLs listadas precisa ser a própria página. A comparação ignora http versus https, um www. inicial, query strings e a barra final.
• Aprovado quando todos os códigos são válidos e a página lista a si mesma; se não houver x-default, a mensagem acrescenta que esse fallback opcional está ausente. Caso contrário, um aviso com "The language versions do not include this page itself" ou "Some language codes are not valid."

Idioma da página (prioridade baixa). Aprovado quando o elemento <html> tem um atributo lang e mostra o idioma; avisa quando ele está ausente.

URL canonical (prioridade média). Aprovado quando a tag canonical aponta para a própria página; avisa quando ela está ausente ou aponta para outro endereço, mostrando esse endereço.

O que ele não testa

• Links de retorno. O verificador lê uma página e não busca as outras versões, então não consegue confirmar que elas linkam de volta. Abra o código-fonte de cada versão, ou use um crawler, para checar a reciprocidade.
• Cabeçalhos HTTP e sitemaps. Só são lidos os elementos HTML <link>. Se você declara o hreflang em um sitemap, o verificador informa que não há versões.
• URLs absolutas e duplicatas. URLs relativas são resolvidas em vez de sinalizadas, e, se o mesmo código aparece duas vezes, só um é mantido.
• Outras páginas. Uma página é verificada por execução. Informe o endereço de cada versão que quiser checar (example.com/de/pricing, de.example.com), ou use um crawler para o site inteiro.

Como ler o resultado

A nota geral de A+ a F abrange todas as 38 verificações, ponderadas por prioridade (alta 10, média 5, baixa 2; avisos valem metade), com uma lista "Fix these first" e um relatório compartilhável.

Como corrigir cada problema de hreflang

1. Nenhuma versão de idioma declarada, mas elas existem

1. Liste todas as versões da página e sua URL completa, por exemplo /en/, /de/, /fr/.
2. Escolha um método: tags HTML para a maioria dos sites, o sitemap se os templates forem difíceis de alterar.
3. Gere as tags a partir de uma única fonte no seu código ou CMS, para que toda versão exiba o mesmo conjunto completo. Tags escritas à mão se desencontram.
4. Se você usa um plugin multilíngue ou o recurso nativo de mercados da sua plataforma, ele normalmente gera o hreflang para você; confira se cada tradução está vinculada ao seu original e publicada, porque traduções sem vínculo não recebem tags.
5. Rode o verificador de hreflang de novo.

2. As versões de idioma não incluem a própria página

Adicione uma linha para a página atual com o código dela. Em um template, isso geralmente significa que o loop pelos idiomas pula o idioma atual; remova essa condição. Garanta que a URL de autorreferência seja a URL canonical, com o mesmo protocolo, host e convenção de barra final.

3. Alguns códigos de idioma não são válidos

1. Encontre no relatório as linhas com cruz.
2. Corrija o formato: hífen e não underscore, idioma primeiro, região depois (en-GB, não GB-en).
3. Substitua os códigos não aceitos: en-UK vira en-GB (o relatório sugere), es-419 vira es ou uma lista de códigos de países, códigos de três letras viram códigos de duas letras.
4. Confira se o código é o idioma que você quer: be é bielorrusso, cz não é código de idioma (tcheco é cs), jp não é código de idioma (japonês é ja), dk não é um (dinamarquês é da).

4. A página não declara seu idioma

Adicione o idioma ao elemento raiz, por exemplo <html lang="en"> ou <html lang="pt-BR">. O Google não o usa para detectar o idioma, mas navegadores, ferramentas de tradução e leitores de tela usam, como descreve o MDN.

5. O canonical aponta para outro endereço

Em um site multilíngue, costuma ser o problema do canonical entre idiomas. Mude o canonical de cada versão para a URL dela mesma. Se o canonical aponta para a mesma página em outra forma (http em vez de https, ou sem www), faça-o coincidir exatamente com o seu endereço final.

6. Faltam links de retorno (não testado pelo verificador)

Abra duas versões lado a lado e compare as listas de hreflang: elas precisam ser conjuntos idênticos. Se forem diferentes, a causa quase sempre é o template ou plugin que as gera, então corrigir o gerador uma vez corrige todas as páginas.

Exemplo prático (hipotético)

O exemplo a seguir é hipotético, não são dados reais. A Kestrel Gear, uma marca de outdoor inventada, mantém example.com em inglês com versões /de/, /fr/ e /es/. Quem pesquisa na Alemanha continua caindo em páginas em inglês. O verificador de hreflang informa:

Canonical: "The canonical URL points to the page itself." Idioma da página: en.

A cruz em es_ES é um erro de formato. A cruz em en-UK vem com a nota "→ en-GB": o Google não aceita UK como região, então a página em inglês ficou sem anotação utilizável. Ao ver o código-fonte da página em alemão, aparece um terceiro problema: o canonical dela aponta para a home em inglês, então o Google tratou /de/ como duplicata. As correções:

1. Os códigos foram trocados para en, de, fr, es (uma versão por idioma, sem necessidade de regiões) e foi adicionado x-default apontando para a home em inglês.
2. A saída do hreflang foi movida para um template compartilhado, para que toda versão imprima o mesmo conjunto, inclusive a si mesma.
3. Cada versão ganhou um canonical autorreferente.
4. Foi removido um redirecionamento por IP que enviava automaticamente visitantes da Alemanha para /de/, substituído por um banner de sugestão.

Um checklist de hreflang de 20 minutos

1. Rode o verificador de hreflang gratuito na sua home e em cada versão de idioma.
2. Compare cada código com a ISO 639-1 e a ISO 3166-1 alpha-2.
3. Confirme que cada versão lista a si mesma e todas as outras versões.
4. Abra duas versões e confirme que os conjuntos são idênticos.
5. Verifique se o canonical de cada versão aponta para ela mesma.
6. Adicione x-default (opcional, mas útil).
7. Garanta que nenhum redirecionamento automático esconda versões do Googlebot.

Como a Searvia ajuda

O verificador de hreflang gratuito valida os links hreflang, o idioma da página e o canonical da página que você informa em um único relatório compartilhável, junto com as outras verificações do verificador de SEO de sites. Em uma conta Searvia, conecte o Search Console para ver cliques e posições por país de cada versão de idioma, e rode a auditoria do site toda semana para pegar canonicals apontando para outro lugar, títulos duplicados entre versões de idioma e páginas quebradas. Se você publica apps além de sites, nosso guia de localização na App Store trata do mesmo problema do lado das lojas. Para o checklist técnico completo, veja o guia de auditoria de SEO técnico.