What hreflang tells search engines
The hreflang attribute marks a set of pages as equivalent versions of the same content for different languages or regions, so that a French speaker in Canada is sent to the right version. Google uses it as a signal for serving the correct URL, not as a ranking boost, and it never replaces translation or localisation of the page itself. There are three equivalent places to declare it: <link> tags in the <head>, HTTP headers (useful for PDFs), or an XML sitemap. This tool produces the first: one <link rel="alternate"> line per row you enter.
Worked example
With the default rows (en to the root, en-GB to /uk/, es to /es/) and the x-default checkbox ticked, the output is:
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />Because each version must list the full set including itself, this exact same block goes into the head of all three pages. Rows with an empty code or URL are skipped (with a note), and special characters in URLs are escaped for you. The x-default line has its own URL field, which is usually the language-selector page or the version for everyone else.
The rules that make it work
- Return links are mandatory. If page A points to page B, page B must point back to page A. One-way annotations are ignored, which is the most common reason hreflang "does nothing". The generator itself never fetches anything, but the "Check a live page" box under the tags does: see the next section.
- Self-reference. Each page's own URL belongs in its own set.
- x-default. It names the fallback for users whose language or region matches none of your versions. It is recommended, not required.
- Absolute URLs. Use fully qualified URLs including the protocol, and point to the canonical, indexable version of each page.
Checking a live page for return links
Once the tags are deployed, enter the address of any one version in "Check a live page". The site's own server fetches that page, reads its hreflang annotations from the <head> and from any HTTP Link header, and then fetches each alternate (up to 24 distinct URLs; any beyond that are neither fetched nor listed, though the result says how many were left out, and alternates the request budget cannot cover are listed as not checked) and reads the set that alternate declares. Each alternate comes back as reciprocal or with the specific problems found:
- No return link. The alternate does not list your page, so the pair is ignored.
- Different set. The alternate omits URLs from your set, lists extra ones, or uses another code for the same URL.
- No self-reference. The alternate does not list its own address.
- Redirect, error status or noindex. An alternate that redirects, returns an error or is set to noindex cannot serve as a target.
- Canonical elsewhere. The alternate's canonical tag points at a different URL.
URLs are compared exactly after the fragment is removed, so a trailing-slash difference counts as a different URL, as it does for Google. The check reads tags and headers only; annotations that live in an XML sitemap are not read, and a page that builds its tags with JavaScript will show none, because nothing is rendered. If the "Load this page's tags" button is used, the found set fills the generator rows so you can correct and re-export it.
Getting the codes right
Use a language code from ISO 639-1, optionally followed by a hyphen and a region code from ISO 3166-1 alpha-2. The language comes first, and a region on its own is not valid. The tool checks the shape of each code (2 to 3 letters, an optional 4-letter script, an optional 2-letter or 3-digit region) or x-default, flags underscores, repeated codes and relative URLs, and shows a warning under the rows. It cannot know whether a well-formed code such as en-UK is a real region, so still check the letters.
| Intent | Correct | Common wrong value |
|---|---|---|
| English, any region | en | eng |
| English, United Kingdom | en-GB | en-UK |
| Spanish, Mexico | es-MX | es_MX (underscore) |
| English, United States | en-US | us (a region alone is invalid) |
Only list regional variants when the content genuinely differs, such as currency, spelling or shipping. Two near-identical English pages for the US and UK are a reasonable case; ten regional copies of the same translation usually are not.
Alternates should also agree with your canonical tags; a page that canonicalises to a different URL can make its hreflang annotations get ignored. After deploying, include the translated URLs in your XML sitemap, check each page with the canonical checker, and see the meta tag generator for the other head tags a localised page needs.