What Hreflang Does
Hreflang is an annotation that pairs a language, an optional region and a URL. When a site publishes the same page in several languages or for several countries, each version can list the others. Search engines read that list and use it to choose which version to show a given searcher, so a visitor who reads Hindi and lives in India is more likely to land on the Hindi page than on an English page that happens to rank higher.
Hreflang works alongside the canonical link. A canonical tag names the preferred address of one page. In a multilingual set, each page's canonical should point to that page itself, and the same address should appear among the alternates. That way the canonical and the hreflang list describe the same page from two angles.
The generator writes the same set in three formats. The HTML head output is what most sites need. The HTTP header output carries the same information in response headers, which is the only option for files such as PDFs. The XML sitemap output is an xhtml:link block for sites that keep their alternates in the sitemap rather than in every page.
Control-by-Control Walkthrough
Work through the tool from top to bottom. Each control below is listed by the label you see on the page.
Canonical URL and "Use first row URL"
Type the full address of the page you are annotating into the canonical field, starting with https://. The button beside it copies the URL of the first alternate row that has a value, which saves retyping when the first row is the page itself. Only absolute addresses are accepted, so a path such as /pricing/ is flagged in red.
Alternate pages list
Each row describes one version of the page and has four parts. The number on the left is the row position. The Alternate page URL box takes the full address of that version. The Language dropdown shows a placeholder until you choose a code, then lists common ISO 639-1 languages. Choose Custom code at the bottom of that list to reveal a free-text box for values such as zh-Hant or pt-BR, which also accept a script or region. When a standard language is selected, the Any region dropdown appears beside it so you can add a country code. The red-cross button removes the row.
The Add row button appends an empty row and moves the focus to its URL box. The list holds up to 60 rows, after which the button is disabled.
Load sample and Clear all
Load sample restores a four-row example and returns the output tab to HTML head. Clear all empties the canonical field and rows, leaves one blank row, and resets the x-default URL. Both act on the saved settings in this browser, so the change is kept when you come back.
x-default checkbox and URL
Leave Include an x-default entry ticked and enter the fallback address in the field that appears below it. Untick the box to remove the entry. A warning explains the consequence: without a fallback, visitors whose language and region match no row receive whichever page the search engine chooses.
Checks panel
The checks panel lists everything the generator found. A green line means every check passed. Red lines are errors, and the row or entry they describe is left out of the output until it is fixed. Amber lines are warnings, such as an unusual region, and the output is still produced. If some rows are excluded, a final line states how many of the rows made it into the output.
Return-links reminder
Once there are at least two alternate pages, a blue box appears that explains the return-link rule. It reminds you that the whole block must be copied to every alternate page, and that each page's canonical changes to point to its own address.
Output tabs, Copy and Download
The three tabs switch between the HTML head, HTTP header and XML sitemap formats. A note under the box explains where that format goes. Copy places the visible block on the clipboard. Download saves it as hreflang-head-tags.html, hreflang-link-headers.txt or hreflang-sitemap-entry.xml, depending on the tab. The line under the output summarises how many alternates, languages and regions were detected.
Worked Example
When the page opens, the sample is already loaded: four alternate rows, a canonical URL of https://example.com/pricing/ and an x-default entry pointing to the same address. The rows are English, English for India, Hindi and German. Because the canonical address is also the first row, the canonical check passes. The HTML head output is:
<link rel="canonical" href="https://example.com/pricing/">
<link rel="alternate" hreflang="en" href="https://example.com/pricing/">
<link rel="alternate" hreflang="en-IN" href="https://example.com/en-in/pricing/">
<link rel="alternate" hreflang="hi" href="https://example.com/hi/pricing/">
<link rel="alternate" hreflang="de" href="https://example.com/de/preise/">
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/">
The summary line reads 4 alternates + x-default - 3 languages, 1 region, canonical set. The count says three languages rather than four because English appears in two rows, and languages are counted once each. The return-link reminder says the block contains 5 entries for 4 alternate pages, because the x-default entry is counted in the block but not as an alternate.
Now type zh-hant into the custom code box of a new row. The generator rewrites it as zh-Hant, the language in lower case, the script with an initial capital and any region in upper case, and adds an amber note saying so. Typing en-UK instead produces a different amber note: UK is not an ISO country code, and the code for the United Kingdom is GB. In both cases the row is still included, because these are advice rather than errors.
For an error, set two rows to English with no region. The second row turns red, the message says that en is already used in row 1, and that row is left out of every output until you change it.
Tips and Common Mistakes
- Include the page itself. Every page should appear in its own list, with the canonical address matching its own row.
- Keep the sets identical. Copy the same block to every alternate page. Only the canonical line changes from page to page.
- Use real codes. Language codes come from ISO 639-1 and regions from ISO 3166-1 alpha-2. Check the spelling of anything not in the built-in list.
- Do not use a region alone.
INis not a valid value. Pair it with a language, as inen-IN. - Give each language one URL. Two different addresses with the same code on one page confuse the search engine. Choose one version per combination.
- Check that the pages exist. The generator validates the text you enter, not the live site. Each alternate must return a working page, and each must list the others back.
- Remember the x-default. It is the fallback for unmatched visitors, not an extra language, so point it at a language selector or your default version.
- Use the header output for files. A PDF cannot hold a head element, so send its alternates as a Link header instead.
Frequently Asked Questions
The canonical link is left out of all three outputs and a warning appears. The hreflang entries are still generated. Normally you should fill in the address of the page you are pasting the tags into.
UK is not an ISO 3166-1 alpha-2 code; the code for the United Kingdom is GB. EU is a union rather than a country, so hreflang does not recognise it as a region. Use a language-only value or a specific country code instead.
You can, but head tags are simpler for HTML pages. The header output is mainly for files such as PDFs, where a head element is not possible. Send one Link header per line, or join them with commas into a single header.
Each language and region pair may appear only once per page, and the comparison ignores capitalisation. Two rows that both use English with no region are duplicates. If the wording differs, give one of them a region such as en-GB or en-US, or remove the extra row.