Hreflang Tag Generator

Hreflang tags are HTML link elements that tell search engines about the relationship between pages in different languages or targeting different regions. They signal that multiple versions of a page exist and specify which version is appropriate for which audience. The tag uses a standardized format: <link rel="alternate" hreflang="x" href="url" /> where "x" is a language code, optionally combined with a region code.

The system was introduced by Google in 2011 to solve a problem that was growing alongside the multilingual web. Before hreflang, a French-language page on a Canadian website might rank in France, while the French-language page intended for French users might rank in Canada. Search engines had no reliable way to distinguish between pages that were identical in language but intended for different geographic audiences, or between pages that covered the same topic in different languages.

Hreflang annotations create an explicit map of these relationships. They tell Google: "These five URLs are all versions of the same content. This one is for English speakers in the US. This one is for English speakers in the UK. This one is for French speakers in France. This one is for French speakers in Canada. And this one is the default for everyone else." Google uses this map to serve the most appropriate version in each user's search results.

Bing does not use hreflang tags. It relies on the content-language meta tag and its own language detection systems. Yandex supports hreflang. If your multilingual strategy needs to cover Bing, you'll need additional signals beyond hreflang alone.

Not every multilingual site needs hreflang, and implementing it when it's not necessary adds complexity without benefit. The tags solve specific problems, and understanding which problem you have determines whether you need them.

• Same language, different regions. A site with separate English pages for the US, UK, and Australia needs hreflang. The content might be nearly identical with minor spelling, currency, and terminology differences. Without hreflang, Google may pick one version and suppress the others as duplicates. Hreflang tells Google each version targets a specific market and should rank in that market's search results.
• Different languages, same market. A Canadian site with English and French versions serves two language communities within the same country. Hreflang ensures French-speaking Canadians see the French version and English-speaking Canadians see the English version, rather than Google guessing based on the user's browser settings or IP location.
• Fully translated sites. A site available in English, Spanish, German, Japanese, and Portuguese where every page has been translated into all five languages needs hreflang on every page to connect the translated versions. Without it, Google may index multiple language versions for the same country and show the wrong one.
• Partial translations. A site where some pages are translated and others aren't still benefits from hreflang on the pages that have multiple versions. An x-default tag handles the fallback for users whose language or region doesn't match any specific version.

You probably don't need hreflang if your site exists in only one language with no regional variations, or if your different language versions live on completely separate domains with no overlapping audience. A .de domain serving only German content and a .com domain serving only English content with no shared market may not need hreflang if there's no risk of Google confusing them.

Hreflang uses ISO 639-1 language codes optionally combined with ISO 3166-1 Alpha-2 country codes. The syntax is language or language-region, and getting these codes right is the foundation of a correct implementation.

• Language-only codes. Use a bare language code when your content targets all speakers of that language regardless of where they are. hreflang="fr" means "this page is for French speakers everywhere." hreflang="de" means "this page is for German speakers everywhere." Use this when you haven't created region-specific versions.
• Language-region combinations. Add a country code when your content targets a specific language-region combination. hreflang="en-US" means "English for the United States." hreflang="en-GB" means "English for the United Kingdom." hreflang="fr-CA" means "French for Canada." hreflang="pt-BR" means "Portuguese for Brazil." Use this when the same language has different versions for different countries.
• The x-default tag. This special value designates a fallback page for users who don't match any of your specified language-region combinations. hreflang="x-default" typically points to your main page, your language selector page, or your most universal version. Every hreflang implementation should include an x-default to handle unmatched users gracefully.

Common code pairs. English: en, en-US, en-GB, en-AU, en-CA. Spanish: es, es-ES, es-MX, es-AR. French: fr, fr-FR, fr-CA, fr-BE. Portuguese: pt, pt-BR, pt-PT. Chinese: zh, zh-CN (Simplified), zh-TW (Traditional). German: de, de-DE, de-AT, de-CH.

What you cannot do. You cannot target a region without specifying a language. hreflang="US" is invalid. You cannot use non-standard codes. hreflang="en-UK" is invalid because the UK's ISO country code is "GB," not "UK." You cannot target a city or state, only countries. These are common mistakes that silently invalidate your implementation.

Hreflang tags can be implemented in three different ways. Each achieves the same result, and you only need one method per page, not all three.

• HTML link elements in the head. The most common method. You place <link rel="alternate" hreflang="..." href="..." /> tags in the <head> section of each page. Every language version of the page gets its own link element, and the page must also include a self-referencing hreflang tag pointing to itself. This method is straightforward for sites with a moderate number of language versions.
• XML sitemap. Instead of adding tags to every page's HTML, you declare hreflang relationships in your XML sitemap using <xhtml:link> elements within each <url> entry. This is the preferred method for large sites with many pages and many language versions because it doesn't add markup weight to every page load and is easier to maintain through automated generation.
• HTTP headers. For non-HTML resources like PDFs, you can specify hreflang through the HTTP response header using Link: headers with rel="alternate" and hreflang attributes. This method is rarely used for regular web pages but is the only option for files where you can't modify the HTML head.

The generator produces output for all three methods. Choose HTML tags if you want the implementation visible in your page source and manageable through your CMS. Choose XML sitemap if you have a large site or many language versions. Choose HTTP headers if you're working with non-HTML documents.

The mechanics of hreflang require every version of a page to reference every other version, including itself. This bidirectional confirmation is what makes hreflang work and what makes incomplete implementation the most common source of errors.

Imagine a page that exists in three versions: English for the US, Spanish for Mexico, and a French default. Each of those three pages must contain the following three hreflang tags in its head:

<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page" />
<link rel="alternate" hreflang="es-MX" href="https://example.com/es-mx/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/fr/page" />

All three pages carry identical sets of tags. The English page references itself, the Spanish page, and the French page. The Spanish page does the same. The French page does the same. This mutual confirmation is what Google requires to trust the relationship. If the English page references the Spanish page but the Spanish page doesn't reference the English page back, Google ignores the annotation.

This is why hreflang gets complicated at scale. A site with pages in ten languages means every page needs ten hreflang tags. A thousand pages times ten languages means ten thousand annotations that all need to be correct, bidirectional, and maintained as pages are added, removed, or restructured. Automation through CMS plugins or sitemap generation is essential for anything beyond a small handful of pages.

Google processes hreflang as a signal, not a directive. This distinction matters because it means Google can and does override your hreflang annotations when its own data suggests a different result would be better.

• Language matching in search results. When a user searches in French from France, Google's results should show French-language pages. If your site has a French version annotated with hreflang="fr-FR", Google is more likely to surface that version for French users instead of your English version. The hreflang tag doesn't guarantee this outcome, but it's one of the strongest signals available.
• Canonicalization across language versions. Google treats each hreflang-annotated version as a separate URL with its own ranking potential. Unlike duplicate content, which Google consolidates to a single canonical, language versions are treated as distinct pages that each deserve their own index entry. Hreflang is what prevents Google from treating your French page as a duplicate of your English page.
• Swapping URLs in search results. When Google determines that a different language version would be more appropriate for a user, it can swap the URL in the search result. A user in Mexico who searches in Spanish might see your Spanish-Mexico URL in the results even though the English-US version technically ranks for that query. This URL swapping is one of hreflang's most valuable functions.
• Handling conflicts. When hreflang annotations conflict with canonical tags, Google makes a judgment call. If your French page has a canonical tag pointing to the English page, Google receives contradictory signals: the hreflang says they're equivalent language versions, but the canonical says the English page is the primary one. In most cases, the canonical wins and the French version gets suppressed. Never point canonical tags across language versions. Each language version should be self-canonicalizing.

Yes. Your URL structure, whether you use subdirectories (/en/, /fr/, /es/), subdomains (en.example.com, fr.example.com), or separate country-code domains (example.com, example.fr, example.de), doesn't eliminate the need for hreflang. The URL structure tells search engines where your content lives. Hreflang tells them who it's for.

• Subdirectories. The most common structure for multilingual sites. example.com/en/page, example.com/fr/page, example.com/es/page. All versions share the same domain authority. Hreflang connects them as language alternatives.
• Subdomains. en.example.com, fr.example.com, es.example.com. Each subdomain may build somewhat independent authority. Hreflang bridges them so Google understands they're language versions of the same content.
• Country-code top-level domains. example.com, example.fr, example.de. Each domain carries an inherent geographic signal (ccTLDs target their associated country). Hreflang is still valuable for clarifying language targeting and connecting versions across domains, especially when a ccTLD serves multiple languages (like a .ch domain serving German, French, and Italian content for Switzerland).

Google doesn't prefer one URL structure over another for multilingual sites. The choice depends on your infrastructure, your budget for maintaining separate properties, and whether you need independent geographic targeting at the domain level. Whichever structure you choose, hreflang is the annotation layer that makes the language relationships explicit.

Hreflang is notoriously error-prone because the bidirectional requirement means a mistake on one page can break the annotation for every page in the set. Regular auditing is essential.

• Check for return links. Every hreflang annotation must be reciprocated. If page A says it has a French alternate at page B, page B must say it has an English alternate at page A. Crawl your site and verify that every hreflang relationship has its corresponding return link. Missing return links are the single most common hreflang error.
• Validate language and region codes. Check every tag for valid ISO 639-1 language codes and ISO 3166-1 country codes. "en-UK" (invalid), "esp" (invalid three-letter code), and "zh-hans" (incorrect format for simplified Chinese) are common mistakes that silently invalidate the tag.
• Verify URLs are accessible. Every URL referenced in an hreflang tag should return a 200 status code. Tags pointing to redirected, blocked, or 404 URLs are ignored by Google. If you've restructured URLs without updating your hreflang annotations, the tags are broken.
• Check canonical and hreflang alignment. Each page referenced in hreflang should have a self-referencing canonical tag. Cross-language canonicals (where the French page canonicals to the English page) contradict the hreflang and cause Google to ignore the language annotation.
• Confirm x-default is present. Every hreflang set should include an x-default. Missing x-default means users who don't match any specified language-region have no designated fallback, and Google decides for them.
• Use Google Search Console. The International Targeting report in Search Console surfaces hreflang errors Google has detected during crawling. Check this report regularly for issues you haven't caught through manual auditing.

• Missing self-referencing tags. Every page must include an hreflang tag pointing to itself. The English page must include hreflang="en-US" pointing to its own URL alongside the tags for other language versions. This self-reference is required for Google to process the annotation set. Omitting it is one of the most frequent errors and one of the easiest to prevent.
• Using the wrong country code for the UK. The ISO country code for the United Kingdom is "GB," not "UK." hreflang="en-GB" is correct. hreflang="en-UK" is invalid and gets ignored. This trips up an enormous number of implementations because "UK" is the common abbreviation everyone uses in conversation.
• Pointing hreflang tags at redirected URLs. If your English page redirects from HTTP to HTTPS, or from a non-www to www version, and your hreflang tag points to the pre-redirect URL, Google encounters a redirect chain before reaching the actual page. Use the final, canonical URL in every hreflang tag, not an intermediate URL that redirects.
• Mixing implementation methods. Using HTML tags on some pages and XML sitemap annotations on others for the same site creates confusion and increases the chance of inconsistency. Pick one method and apply it consistently. If you need both methods for different sections of your site, make sure they don't contradict each other.
• Forgetting to update hreflang when adding new languages. When you add a Portuguese version to a site that already has English, Spanish, and French, every existing page in all three languages needs to be updated to include the new Portuguese hreflang tag. The Portuguese pages need tags for all four languages. Missing this cascading update requirement is how partial, broken implementations happen.
• Using hreflang to fix duplicate content problems. Hreflang isn't a duplicate content solution. If your English-US and English-UK pages are virtually identical, hreflang prevents them from competing in the same market, but it doesn't solve the broader duplicate content issue. If two pages are truly identical with no regional differences, consider whether you actually need separate versions or whether one page with a broader language target would serve both audiences.
• Not testing after deployment. Hreflang errors are silent. No browser shows a warning. No visible element breaks. The only way to know your implementation is correct is to validate it with a testing tool, crawl the site to check return links, and monitor Search Console for errors. Test immediately after launch and after every structural change to the site.