Hreflang Tag Generator
Note: The annotation only counts if it is reciprocal. Every page in the group needs the same complete block, including a tag pointing at itself, and each version must be canonical to itself — a canonical pointing at another language discards that page's hreflang along with the page.
Most hreflang implementations are broken in the same three ways, and this generator is built around avoiding them. First, the annotation has to be reciprocal: if the English page points at the German one, the German page must point back at the English one, and both must point at themselves. Anything else is ignored outright. That is why the output here is a full block per URL rather than a single tag — you paste the whole set into every page in the group. Second, the value is a language code, optionally followed by a region, and the region is a country, not a language. en-UK is wrong; the code for the United Kingdom is GB. Third, x-default is not a language. It marks the page a visitor lands on when none of the other versions match them — usually a language selector or the international English version.
You can output the same set as HTML link elements for the head, as HTTP Link headers for PDFs and other non-HTML files, or as XML for a sitemap. The sitemap form is worth considering when the group is large: the head version costs you one tag per language on every page load, and with forty locales that is real weight on every request for no user-facing benefit.
Frequently Asked Questions
Do I need to list the page itself?
Yes. Every page in the group must include a self-referencing hreflang pointing at its own canonical URL. Omitting it is the single most common reason a correct-looking set is ignored entirely.
What is the difference between x-default and my main language?
x-default is the fallback for visitors none of your other annotations match — someone browsing in Japanese when you only publish English, German and French. It is often the same URL as your international English page, and listing that URL under both en and x-default is valid.
Can hreflang and canonical conflict?
They can and it silently breaks everything. Each language version must be canonical to itself. If the German page carries a canonical pointing at the English URL, you have told the search engine the German page should not be indexed at all, and its hreflang annotations are discarded with it.
Should I put the tags in the head or the sitemap?
Either works and neither is preferred by search engines. The head is easier to verify by viewing source; the sitemap keeps page weight down and is much easier to maintain when you have many locales, because the mapping lives in one file rather than duplicated across every template.
Does the order of the tags matter?
No. The set is read as a group, so the order is purely a matter of readability. Sorting by language code keeps diffs small when locales are added later.
