The Hreflang Audit tool tells you what's broken. This tool emits the fix.
Hreflang Generator takes a simple locale-to-URL map as input and produces four output formats: HTML <link> tags, sitemap.xml <xhtml:link> entries, HTTP Link headers (for PDFs and non-HTML), and Next.js / Astro alternates.languages framework arrays. Choose the form that matches how your site is built; the logical content is identical.
Why four formats?
Different sites implement hreflang in different places, and each place has constraints.
HTML <link> tags in <head> are the most common. Every page ships the same complete block. Easy to audit visually, but HTML gets noisy if you have 15+ locales.
sitemap.xml <xhtml:link> entries keep HTML lean by moving hreflang out of each page's <head> and into the sitemap. Same cluster, same pages, just declared once in XML instead of once per page. Recommended for sites with 10+ locales.
HTTP Link headers are the only way to declare hreflang for non-HTML resources, PDFs, images, downloadable assets. If you publish a PDF in five languages, each PDF's HTTP response should carry a Link header naming the other four. Google honors it; Bing historically less so but coverage improves year over year.
Framework arrays (Next.js app-router alternates.languages, Astro i18n, Gatsby plugins) let the framework emit the HTML <link> tags on build. The source of truth is a single array; the output is the HTML form. Less manual error surface, harder to audit because the block is generated.
Why the generator is opinionated
A few non-obvious defaults:
-
Auto x-default. If your locale map doesn't include an
x-defaultentry, the tool adds one pointing to the first locale in the list. x-default is Google's recommended fallback for users whose locale doesn't match any entry. You can disable this with the checkbox, but most sites want it. -
Self-reference is mandatory. The generator always emits a self-referencing
<link>tag for every locale. A cluster without self-reference is Google-invalid; no option to skip it. -
Absolute URLs enforced. Relative URLs are silently ignored by Google. The generator validates that every href starts with
http://orhttps://and throws a visible error if not. -
ISO validation on input. Each tag is parsed as
lang+ optionalregion. Unknown language codes, unknown regions (UK instead of GB, etc.), and underscore-separated tags (en_US) are all flagged before generation.
The bidirectional guarantee
The critical property of hreflang is that the same block goes on every page in the cluster. If your cluster has four pages, all four pages ship the same <link> block, including the one that points to themselves.
This is counter-intuitive. Developers often assume "the English page should only declare non-English alternates." That assumption is what kills clusters. Google's validation logic is: "For every hreflang x declared on page A pointing to page B, verify page B also declares hreflang y pointing to page A." If any page is missing any backlink, the whole cluster is discarded.
The generator makes this guarantee structural. The output HTML block is valid for every page in the cluster. Paste it in each one, deploy, and run the Hreflang Audit to confirm.
Specifics worth knowing
-
Language-only tags (
en,de) and language-region tags (en-US,de-AT) can coexist. Google prefers the most specific match. If a user is in Austria, Google picksde-AToverde; if node-ATexists, it falls back todeor tox-default. -
You can have multiple regions per language.
en-US,en-GB,en-AU,en-CA,en-IN, and a genericenare all legal in one cluster. Usually with three or more English regions, ship a genericenas fallback. -
Bidi is a graph, not a tree. Don't think "master page + translations." Think "set of equivalent pages, all declaring the same cluster membership." There is no hierarchy.
-
Canonical is separate from hreflang. Each localized page's canonical points at itself. Hreflang handles the cross-locale relationships. Do not try to consolidate canonical to a single master, that invalidates hreflang.
Common locale-map mistakes
en_US, underscores are not allowed. Useen-USwith a hyphen.en-UK, the ISO region code for the United Kingdom isGB, notUK.pt-BRwhen the content is for Portugal, usept-PT.zhas the only Chinese entry when the content is for both Mainland China and Taiwan, China uses Simplified Chinese, Taiwan uses Traditional. Usezh-CNandzh-TWexplicitly.esfor both Spain and Latin America, Spanish varies by region.es-ES(Spain) andes-MX(Mexico) are usually distinct; addes-419(UN M.49 code for Latin America and the Caribbean) if you're shipping a single pan-Latin variant.
The workflow
- Audit the existing cluster with Hreflang Audit
- Note which pages are missing which backlinks
- Paste the complete locale-to-URL map into Hreflang Generator
- Pick the output form that matches your stack (HTML, sitemap, HTTP, framework)
- Ship the block to every page in the cluster
- Re-run the audit to confirm the backlinks landed
- Submit the updated sitemap to GSC and Bing so the new cluster gets picked up
A four-locale cluster rewrite from broken to fully-validated takes about 15 minutes of work. The ranking recovery in international search takes 2-6 weeks as Google recrawls the cluster and re-establishes locale targeting.
Related reading
- Hreflang Must Be Bidirectional, Why Google Demotes Multilingual Sites
- Hreflang Audit Tool, Bidirectional Cluster Validator
- Index Coverage Delta
- Sitemap Delta: Finding the URLs Your Site Links To That Are Not in Your Sitemap
If you're building an international site from scratch and want the full localization + SEO playbook baked into a launch template, the $97 Launch walks through the SOP: The $97 Launch.
Fact-check notes and sources
- Google hreflang documentation and specification: Google Search Central — "Tell Google about localized versions" (accessed 2026-04-20)
- RFC 5988, Web Linking (basis for HTTP
Linkheaders): IETF RFC 5988 - Next.js App Router alternates/languages API: nextjs.org/docs/app/api-reference/functions/generate-metadata
- UN M.49 region codes (including 419 for Latin America): unstats.un.org/unsd/methodology/m49/
