The Hreflang Generator turns two to 100 rows of locale|URL pairs into one escaped HTML alternate-link block, with canonical casing and an optional x-default fallback. A cheat sheet is the right shape for this task because the tool's contract is precise: one literal separator per line, fully qualified HTTP(S) URLs, structurally correct locale tags, and an identical block installed in every page head. The tool does not crawl your site, validate against the full registry of languages and regions a search engine currently supports, or prove reciprocal links — its job is to produce one consistent, HTML-escaped rel=alternate block you can copy into each alternate page. This cheat sheet compresses that contract into the input format, the locale tag shapes, the validation rules, and a three-step generation workflow, so the same block lands correctly across every localized page in your cluster.
Hreflang Generator Quick Rules at a Glance
Nine rules cover almost every input the tool will accept, reject, or transform. Keep them visible while you type rows.
- Row count: minimum 2, maximum 100. A one-row set always fails so the tool never returns a partial block.
- Separator: exactly one literal pipe character (|) per line.
- URL form: fully qualified http:// or https:// address including host. Relative paths, scheme-relative references, embedded credentials, and fragment identifiers are all rejected.
- Locale shape: a two-letter language, optional four-letter script, and optional two-letter region, joined by single hyphens.
- Casing: subtags are normalized through Intl.getCanonicalLocales, so en-us becomes en-US and zh-hant becomes zh-Hant before the row is accepted.
- x-default: one row tagged x-default is allowed and serves as a fallback when no listed alternate matches the user; a second x-default row is rejected.
- Duplicates: locale values are compared case-insensitively after normalization, so en and EN count as the same row.
- Self-reference: every page's own URL must appear once in the block so it can point to itself.
- Reciprocity: every alternate must publish the identical block. A one-way declaration can be ignored because another site must not be able to claim your page as its alternate unilaterally.
Input Format: Locale | URL Row by Row
Each line is a single locale-to-URL mapping. The format is intentionally narrow so the tool can fail the entire set on a malformed row rather than silently omitting one country or language version. A typical input set for an English, Spanish, French, and German cluster with an x-default landing page reads as five rows: en | https://example.com/, es-ES | https://example.com/es/, fr-CA | https://example.com/fr-ca/, de-DE | https://example.com/de/, and x-default | https://example.com/.
Five notes worth pinning next to the input box. First, the row for the page you are currently editing must appear once in the set so it points to itself. Second, fully qualified means the scheme and host are spelled out — protocol-relative //example.com/page and root-relative /page are rejected. Third, fragments after the URL, such as #section, are rejected. Fourth, generic language tags such as fr or en work well as fallbacks when several country-specific versions exist, but a regional tag like fr-CA still needs the language subtag first. Fifth, x-default is not a language; it identifies a page intended for users whose settings do not match a listed alternate, usually a country selector or generic landing page.
Locale Tag Cheat Sheet
Locale tags follow the structure language[-script][-region], where the script and region subtags are optional but must appear in that order when both are used. The generator canonicalizes casing, so the table below shows the form you should expect after normalization.
| Tag shape | Input example | Canonical output | Use when |
|---|---|---|---|
| language | en or EN | en | Generic English page serving all regions |
| language-region | en-us or en-US | en-US | Targeted English for one country, here the United States |
| language-script | zh-hans or zh-Hans | zh-Hans | Distinguish writing systems such as Simplified Chinese |
| language-script-region | zh-hant-tw or zh-Hant-TW | zh-Hant-TW | Traditional Chinese targeted at Taiwan |
| fallback | x-default | x-default | Page intended for users whose language does not match a listed alternate |
How to Generate Hreflang Tags in Three Steps
The generator is built around three operating steps. Working through them in order keeps the resulting block consistent across every alternate page in the cluster.
- List every localized page as locale | fully qualified URL, including the current page and an optional x-default fallback. Two rows is the minimum, 100 is the cap.
- Generate the complete escaped link block and verify each locale against current supported language and region guidance. Casing is normalized for you; what you must check yourself is whether each language and region is one your content actually targets.
- Install the identical set in every alternate page head, then crawl the live pages to confirm self and reciprocal links. The tool cannot prove reciprocity remotely, so the crawl is your confirmation step.
Open the Hreflang Generator, paste the row list, and copy the resulting link block. Paste the same block into the head of every page listed, then sample-crawl each URL and compare the head sections mechanically.
What the Tool Rejects
Input validation fails the entire set rather than producing a partial output. These are the cases the generator explicitly rejects, with the reason recorded so you can fix the row and re-run.
| Input pattern | Outcome | Reason |
|---|---|---|
| example.com/page | Rejected | Host missing; relative and scheme-relative URLs are not accepted |
| //example.com/page | Rejected | Scheme-relative form is not accepted |
| https://example.com/page#intro | Rejected | URLs containing fragment identifiers are rejected |
| https://user:[email protected]/page | Rejected | Embedded credentials are not accepted |
| en-US on row 3, en-us on row 7 | Rejected | Duplicate locale after case-insensitive normalization |
| x-default on row 2 and row 9 | Rejected | Only one x-default row is allowed per set |
| Single row total | Rejected | Two rows is the minimum, including the current page |
| DE-de without a language subtag first | Rejected | A country code cannot stand alone in the first position |
Eight standards-aligned fixtures in the generator cover generic languages, regional casing, German and French regions, simplified and traditional Chinese script tags, a language-script-region combination, and x-default. Additional tests assert exact HTML escaping and the rejections above. Because the entire set fails on malformed input, the block you copy is the block you can deploy.
After You Paste the Tags: Verification Checklist
The generator produces HTML head elements only; HTTP header and XML sitemap implementations are out of scope. Pick the method your publishing system can keep complete and synchronized, because Google treats the three methods as equivalent and mixing them invites drift. Once deployed, run a short verification pass on a sample from every language cluster.
- Open each localized URL and confirm the head block is character-identical across the cluster, including x-default and the self-reference.
- Confirm every alternate returns a useful 200 page and that redirected or moved locales are updated in the same block on every other page.
- Confirm each page points to itself and that every alternate returns the link, which you can verify with a focused crawl or with the hreflang tag accuracy guide.
- Verify intended language and region against current Google Search Central guidance on localized versions; the tool validates tag shape, not whether the language or region is currently supported.
- Update every page in the cluster when a locale is added, removed, redirected, or moved to a new canonical URL, and re-run the generator rather than hand-editing the head.
The generator cannot fetch remote pages or prove reciprocal links, so ongoing quality depends on your deployment process. Treat the resulting block as the source of truth for the cluster: one input list, one output block, one head section per page, and a verification crawl after every change.