hreflang annotations tell Google which language or regional version of a page to show. Each version must list itself and all other versions, use full URLs, and be linked back by the others. Missing return links are the most common reason annotations are ignored.
Three ways to declare it
Google accepts three equivalent methods, so choose the one easiest to maintain:
- link elements in the HTML head.
- HTTP Link headers, useful for non HTML files such as PDFs.
- XML sitemap entries using xhtml:link children.
<link rel="alternate" hreflang="en" href="https://example.com/docs/install">
<link rel="alternate" hreflang="de" href="https://example.com/de/docs/install">
<link rel="alternate" hreflang="x-default" href="https://example.com/docs/install">
Core rules
- Each page lists itself and every other version, and the set is the same on every page.
- URLs must be fully qualified, with protocol.
- Return links are required. Unreciprocated tags are ignored, which stops other sites claiming your pages.
- Alternates may live on different domains.
- x-default marks a fallback for when no language matches, such as a language selector.
Codes
Use an ISO 639-1 language code, optionally followed by an ISO 3166-1 Alpha 2 region code. Google lists these pitfalls:
- A region code alone, such as US, is invalid.
- be means Belarusian, not Belgium.
- EU, UN and UK have no effect. Use GB for the United Kingdom.
- Unsupported codes such as es-419 are not recognized.
- Script codes such as zh-Hant and zh-Hans are supported.
Other mistakes
Do not mix hreflang with attributes such as media in one link. HTML tags must sit in a well formed head. A sitemap can only list URLs in its own directory or below.
Also keep canonicals consistent. Google says a rel canonical tag carrying hreflang is ignored for canonicalization, and that each language version should be its own canonical with a self reference. See canonical URLs for versioned docs.
Translating technical docs
Machine translation is allowed, but accuracy matters more in commands and warnings than in prose. Do not translate code, flags or file names. Mark untranslated pages honestly rather than publishing a thin copy. Google's spam policies discuss scaled content abuse, so avoid mass producing low value pages.
Quick check
Do I need hreflang if I only have English docs?
No. It matters when you publish multiple language or regional versions.
Can I use only a country code?
No. Google says region only values such as US are invalid. Start with the language code.
Sources
- Localized versions of your pages, Google Search Central
- Consolidate duplicate URLs, Google Search Central
- Spam policies, Google Search Central
Last reviewed: 19 October 2026.
