What does the hreflang generator do, and who is it for?
Hreflang tells search engines that several URLs are language or regional versions of the same content, helping Google show the Turkish page to Turkish searchers and the en-GB version to UK users. It does not boost rankings; it only describes which version suits whom.
It is built for developers of multilingual sites, content teams using WordPress translation plugins and technical SEOs on international shops. No URL you enter is ever requested; every check runs in your browser.
How to use it
- Enter one version per line: code, then absolute URL. Spaces, tabs, commas or semicolons separate them; pasted
<link>tags work too. - Put your fallback page for unmatched visitors in the
x-defaultfield. - Enter the page you are editing as the current page to check its self-reference.
- Press Generate and pick HTML, XML sitemap or HTTP header; all three carry exactly the same URL set.
- Optionally paste each live page's hreflang lines to get a reciprocity report below the output.
If anything is invalid, no output is produced and copying stays disabled; messages include line numbers.
Language and region codes
Google accepts an ISO 639-1 two-letter language code, optionally followed by an ISO 3166-1 Alpha-2 region. The tool does not treat every BCP-47 tag as supported: languages or regions outside those lists are rejected. Letter case is normalised for consistency and each change is shown as a notice.
| Input | Result |
|---|---|
TR | Normalised to tr |
en-gb | Normalised to en-GB |
en_UK | Rejected; en-GB suggested |
en-UK | Rejected; UK is not an ISO region code, en-GB suggested |
GB or us | Rejected; a region cannot stand alone |
es-419 | Rejected; numeric regions are not supported |
Two entries that end up with the same code after normalisation are an error. Case mapping uses plain ASCII rules, so Turkish casing can never turn IT into ıt.
Self-reference and x-default
Every language version must list itself alongside the others. The generated set is given to every URL unchanged, so the output always includes the self-reference; if your current page is missing from the set, you get a warning. A mismatch of only a trailing / or www is flagged separately, because those are different URLs.
x-default is the page for users who match none of your languages, typically a language picker or your main version. A set may contain at most one, and it is always written last. It is optional; leaving it out only produces a notice.
Three output formats
HTML output is a list of link tags for the page head. XML output is a sitemap declaring the xmlns:xhtml namespace, repeating the full alternate set in every URL entry. HTTP output is a Link header value, useful for non-HTML files such as PDFs. All carry the same information; pick one method, since mixing methods with different sets sends conflicting signals.
Values are escaped for their context, so a query string's & becomes & in XML. Header values with line breaks are refused, so input like Injected: value can never add an extra header.
Reciprocity
If the Turkish page points to the English one, the English page must point back; one-way annotations may be ignored. A generated set is reciprocal by construction; whether your live site publishes it is not checked in this version.
For pasted per-page sets, the report lists missing return links, missing self-references, codes pointing to different URLs and differences from the generated set. It is based only on the data you provided; targets you didn't paste are marked as not checked.
Worked example
Enter tr https://example.com/tr/ and en https://example.com/en/?a=1&b=2, with https://example.com/ as the x-default. The expected HTML output is:
<link rel="alternate" hreflang="tr" href="https://example.com/tr/" />
<link rel="alternate" hreflang="en" href="https://example.com/en/?a=1&b=2" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />The sitemap contains three url elements, each with the same three xhtml:link lines. If the pasted Turkish set lists English but the English set does not list Turkish, the report shows a missing return link error on the Turkish page's row.
Relationship with canonical tags
Every URL in a hreflang set should be indexable and canonicalise to itself. If the English page declares the Turkish version as its canonical, the two signals contradict each other. Keep redirected URLs, noindex pages and URLs blocked in robots.txt out of the set.
Limits and common mistakes
- Up to 100 alternates and 100 pasted pages; more is an explicit error, never a silent cut.
- URLs with a
#fragment, relative paths and schemes other thanhttp/httpsare rejected. - Pointing every language at the home page is a classic mistake; you get a warning when different languages share one URL.
- If you only have
en-GBanden-US, a genericenversion or anx-defaultis usually worth adding. - The tool never reads live pages; paste the published tags yourself.
Frequently asked questions
Should I use all three methods together?
No. Any one method works on its own. If you combine them, the sets must be identical.
Why is `en-UK` rejected?
Regions come from ISO 3166-1 Alpha-2, and the code for the United Kingdom is GB. That is why the tool rejects en-UK and en_UK and suggests en-GB.
Is x-default required?
No. Add it when you have a page for unmatched users, such as a language picker. A set can contain at most one.
Did the reciprocity report crawl my site?
No. The tool never requests any URL. The report compares only the sets you pasted, with each other and with the generated set.
How are URLs with Turkish characters written?
The URL parser writes non-ASCII letters with UTF-8 percent-encoding; the path ışık becomes %C4%B1%C5%9F%C4%B1k. Decomposed Unicode input can produce a different address, so the tool warns you when it sees it.