How to mark localized versions with hreflang

Hreflang tells Google about localized versions of a page: another language, or the same language aimed at another region. Google’s localized-versions documentation, updated 21 September 2026, says this helps Search send people to the version that fits their language or region. Google might find alternates on its own. Explicit annotations are still the reliable way. The same page says Google does not use hreflang, or the HTML lang attribute, to detect the language. Algorithms do that. Hreflang names the URLs.

What hreflang is

Hreflang is not a ranking boost. The documentation describes it as a way to understand that these URLs are localized variations of the same content, so Google can return the appropriate one. It does not say that adding the tags makes a page rank higher in every country. A checklist that treats the tag as a growth switch is selling a different product from the one Google documents.

It is also not a language detector. You can set lang="de" on a page that is still English, and you can add hreflang="de" pointing at that same English URL. Google’s algorithms still read the words. The tag does not translate them. Browsers and assistive technology can use the lang attribute. Keep it accurate for those readers. Do not treat it as the Search annotation. The Search annotation is rel="alternate" with hreflang and a URL.

The folder or the subdomain is not the annotation either. A host named en-gb.example.com does not tell Google the audience. The documentation says you must map the audience explicitly. People still publish /de/ and skip the tags, or they add the tags and point them at URLs that do not match the language of the page. The path can be whatever your site uses. The tags have to name the pages.

When a localized version exists

Google names three situations where alternate annotations are recommended.

• The article stays in one language and only the template is translated. Navigation and footer change. Forums often work this way. The main content is still the original language.
• The language is the same, with small regional differences. English pages for the United States, Britain, and Ireland, with prices or spelling that differ, are the example.
• The article itself is translated. A German page and an English page, each complete, are the usual blog case.

Localized versions count as duplicates only when the main content remains untranslated. That sentence decides the canonical, which is the next section. It also decides whether you should create the URL at all. A footer in German on an English standup guide is not a German article. Annotating it as de asks Google to treat an English page as the German version. Translating the article is the work. The tag records the work. It does not perform it.

Machine-translating the same thin page into twenty languages, without adding anything a reader in that language needed, is a different problem. Google’s spam policies include translation used to produce many pages without much value. The scaled content abuse guide is that line. A careful German version of a procedure your team uses is a localized page. Forty city-and-language swaps of one outline are not.

If you have only one language, do not add hreflang to look international. A single English URL does not need an alternate list of itself. Skip the tag until a second version exists. An empty annotation, or a tag that points at the same URL with a second language code, creates a cluster you then have to keep true.

Return links and self links

Each language version must list itself and all the other versions. The set of links is the same on every version. Alternate URLs are fully qualified, including https://. A protocol-relative URL or a path is not enough. The alternates may live on another domain. They still have to be absolute. A country domain or a country folder is a URL choice, which the URL structure guide covers. When desktop and mobile are separate URLs, mobile hreflang points at mobile URLs and desktop hreflang at desktop URLs. A responsive site does not need that split. The mobile-first indexing guide is that case.

If two pages do not point at each other, the tags are ignored. Google does this so someone on another site cannot invent a tag that claims to be your translation. A one-way link from the English article to the German article does nothing useful until the German article links back. Each side also lists itself, so the cluster is explicit rather than implied.

If a full mesh of every language pair becomes hard to maintain, Google says you can omit some languages on some pages and it will still process the pairs that point at each other. New languages should still link both ways with the original, dominant language. A site that started in French should connect new Spanish pages back to the French URLs, even if the new Spanish variants are not fully cross-linked to each other yet. For a blog with two languages, do the full pair. The exception is for a large set, not an excuse to publish one-way tags.

Put the link elements in the head. If you are unsure, validate the rendered HTML and confirm they are inside head, not dropped into the body by a broken template. Do not combine hreflang with other attributes such as media on the same link. Alternate representations and language alternates are different tags. The canonical guide already notes that a single element trying to be both canonical and hreflang is not used for canonicalization. Language alternates use rel="alternate".

Language codes and region codes

The value is a language, optionally followed by a region. The language is ISO 639-1. The region, when you add one, is ISO 3166-1 Alpha 2. Codes outside those lists are not supported. es-419 is the example Google gives of a code it does not support. The value is case-insensitive. Writing the region in uppercase, as in en-GB, follows the ISO convention and is easier to check.

You cannot give a country code by itself. Google does not infer the language from the country. be is a bad code for Belgium, because the first code is the language and be is Belarusian. Belgium needs the language named: de-BE, nl-BE, or fr-BE. de alone means German, independent of region. en-GB means English for users in the United Kingdom. de-ES means German for users in Spain.

Reserved codes do not target a region. Google says EU, UN, and UK in hreflang have no effect. The United Kingdom is GB. A generator that emits en-UK because the menu said “UK” is emitting a tag Google ignores. Fix the generator. Do not add a second, correct tag beside the broken one and hope both are read. One correct code per URL.

For Chinese script, the country can imply the script, so zh-TW is treated as Traditional Chinese. You can also name the script with ISO 15924: zh-Hant and zh-Hans. A region can follow the script, as in zh-Hans-US. Use that only when you actually publish that version. A code for a script you do not have is another one-way promise.

x-default is the fallback when no listed language matches the user’s browser settings. It does not need its own language code. Google designed it for language-selector pages, and it works best there. You may point it at another page, including one of the language versions, if that is the honest fallback. A selector that lets people choose English or German is the clean x-default. Do not point it at a URL that redirects away or returns an error. On a pair of articles with no selector, x-default can be the original language version, and both articles must list it.

If several URLs target the same language in different regions, also offer a catch-all for that language. English for Ireland, Canada, and Australia should sit beside a generic en page for other English-speaking readers. One of the specific pages can play that role if you choose it deliberately. Leaving every English reader outside those three countries with no en URL makes the cluster narrower than your audience.

Pick one method

There are three equivalent ways to publish the cluster: link elements in the HTML, a Link HTTP header, and an XML sitemap. Google treats them as the same signal. You can use all three. There is no Search benefit, and three copies are harder to keep identical. Pick the one you will actually update when a translation ships.

HTML is the usual choice for articles, because the template can print the cluster next to the canonical. The HTTP header is useful for non-HTML files, such as a PDF that exists in more than one language. The header lists every version, including the file that is being served, separated by commas. The sitemap method is useful when you generate files and would rather not touch every template. Child alternate entries do not count toward the sitemap URL limit. The general sitemap rules still apply, which is the XML sitemap guide: absolute URLs, the canonical URL you want crawled, and no pile of alternates that 404.

Whichever method you pick, the URLs in the cluster have to return 200 and be the canonical URL of that version. A hreflang target that redirects, or that canonicalizes somewhere else, makes the cluster point at a URL you do not want indexed. Point at the final URL. Then make the tags on that final URL list the same set.

Canonical URLs for a translation

A translated article is not a duplicate of the original, because the main content did not remain untranslated. Its canonical tag should name itself. Hreflang connects it to the other language. The canonical tag page already says that pointing the German article at the English article throws away the language signal. This page is the annotation that replaces that mistake. The German URL canonicalizes to the German URL. The English URL canonicalizes to the English URL. Both list both.

The duplicate case is the one the localized-versions page names: the main content is still the original language. A German header on an English article is that case. Canonical consolidation may treat those URLs as the same document. Hreflang does not turn the English body into German. Either translate the body, or stop claiming a German alternate.

Same-language regional pages are the middle case. An en-US page and an en-GB page with the same procedure and different currency details are alternates, not a translation pair. They can still be near-duplicates if the body barely changes. Give each the version a reader in that region actually needs, canonicalize each to itself if the body is the version you want indexed, and connect them with hreflang. Do not canonicalize the British page to the US page and also annotate them as equal alternates. The canonical says one URL should be dropped. Hreflang says both should be available. Those instructions fight.

Titles follow the language of the page. A German article needs a German title element and a German H1. The title tag guide is that match. Hreflang will not correct a German URL whose title is still the English sentence. Algorithms read the page. The title is part of the page.

The sitemap method

If you choose the sitemap, each URL gets its own url entry. Each entry lists every alternate, including itself, as an xhtml:link with rel="alternate", hreflang, and href. The order of those children does not matter. Keep one order so a person can diff the file. Declare the xhtml namespace. Upload the sitemap where it is allowed to list those URLs. A sitemap can only contain descendant URLs of the directory that hosts it, unless you are following the general exception Google documents for sitemaps submitted in Search Console.

Three versions mean three url entries, and each entry repeats the same three alternates. Forgetting the self-reference on one entry is the same class of mistake as a missing return link in HTML. Generate the set once and write it into every entry. Do not hand-edit one language and leave the others on yesterday’s list.

The sitemap does not replace the article. It does not detect the language. It does not excuse a canonical that points the translation at the original. It is only the carrier for the cluster, if you chose this carrier instead of the HTML.

Mistakes that get the tags ignored

Google names missing return links, incorrect language codes, and incorrect region codes as the common mistakes. Third-party validators can help you see a missing return link. Google does not maintain those tools. The check you can do yourself is smaller: open both URLs, view source, and confirm the same set of absolute alternates, including each page itself. Then confirm each target returns 200 and canonicalizes to itself when it is a real translation.

A hreflang example

Northwind translates the standup guide. The English article stays at https://northwind.example/async-standups. The German article is a full translation at https://northwind.example/de/async-standups, with a German title, a German H1, and the same steps in German. Priya Shah’s byline stays, because she still wrote the procedure. The German page does not canonicalize to the English page.

Both responses include the same three alternates: en for the English URL, de for the German URL, and x-default for the English URL, because there is no separate language selector and English is the fallback they chose. The links sit in the head. They are absolute. There is no en-UK. There is no second cluster in the sitemap, because they picked HTML and stopped. The lang attribute on the German page is de, for the reader, not as a substitute for the alternate links.

They do not emit de for a page that only translates the footer. They do not generate /fr/, /es/, and /it/ by swapping the title and leaving the body in English. If a third language is commissioned later, that URL joins the set on every existing version, including a return link to English, before they expect the cluster to count.

How this shows up on a translated post

When you publish a translation, the new URL needs its own canonical, its own title in that language, and a place in the hreflang set on every version, including the original. BloGoose can draft the translated article. The tags are part of the page you ship, not a plugin checkbox pointed at a URL that does not exist yet. Add the alternate only after the translated URL returns the translated article.

If the site is one language, leave hreflang out. Spend the time on the article, the canonical, and the links between related guides. A cluster of one is not a localization strategy. A cluster that lists languages you do not publish is a set of broken return links waiting to be ignored.

Questions about hreflang