A hreflang generator example shows the full translation from one row list into copy-ready rel=alternate link elements. You list every localized page as a single line containing the locale tag and its fully qualified URL separated by a vertical bar, and the generator returns one escaped HTML link element per row. The output block is identical for every page in the cluster: the current page declares itself, every other alternate points back to it, and an optional x-default entry handles visitors whose language or region is not on the list. Casing is canonicalized so en-us becomes en-US and zh-hant becomes zh-Hant, ampersands and other attribute-sensitive characters are escaped for the HTML output, and the generator refuses any input that would silently corrupt the set, including relative URLs, fragments, credentials, or duplicate locales. The block you receive is what you paste into the head of every page in the language cluster, the same exact block character for character, because Google documents the self and return links as essential signals and treats a one-way declaration as ignorable.
What the Generator Expects on Every Row
The Hreflang Generator accepts one locale and one URL per line. A vertical bar character (|) separates the two values. Each line must contain exactly one separator; the entire set fails on malformed input so a partial output cannot be copied while silently dropping one country or language version.
The locale slot accepts a two-letter language tag, an optional four-letter script, and an optional two-letter region. A country code cannot stand alone in the first position, so the first subtag always identifies language, and regional targeting belongs after a language, as in fr-CA. Generic language pages such as fr can serve as fallbacks when several country-specific French versions exist. Script subtags distinguish writing systems such as zh-Hans and zh-Hant, and case is canonicalized to the form expected by Intl.getCanonicalLocales.
The URL slot accepts only fully qualified HTTP or HTTPS addresses including the host. Relative paths and scheme-relative references are rejected. Credentials and fragments are rejected. The browser URL parser normalizes the address while ampersands and other attribute-sensitive characters are escaped in the generated HTML. The tool requires at least two rows, including the current page, and supports up to 100 rows.
Building a Row Set for a Real Multilingual Site
A typical SaaS landing page targeting eight markets produces a clean, reviewable row set. Imagine a product page translated into US English, British English, French for France, German for Germany, Spanish for Spain, Japanese, simplified Chinese, and traditional Chinese, plus a country selector landing page as the x-default fallback. The row list looks like this before it is pasted into the generator:
| Locale input | Canonicalized tag | Page purpose |
|---|---|---|
| en-us | en-US | US English |
| en-gb | en-GB | British English |
| fr-fr | fr-FR | French (France) |
| de-de | de-DE | German (Germany) |
| es-es | es-ES | Spanish (Spain) |
| ja | ja | Japanese |
| zh-hans | zh-Hans | Simplified Chinese |
| zh-hant | zh-Hant | Traditional Chinese |
| x-default | x-default | Country selector |
For sites with more than a handful of locales, a bulk hreflang tag generator workflow keeps the row list versioned and reviewable before it is pasted into the tool, so changes to one market do not silently drift away from the others.
From Rows to Escaped Link Elements
Paste the nine rows into the generator, one locale-URL pair per line. The tool returns one rel=alternate element per row, escaped for direct placement in the HTML head. A representative output for the SaaS landing set looks like this:
<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/" /><link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/" /><link rel="alternate" hreflang="fr-FR" href="https://example.com/fr-fr/" /><link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/" /><link rel="alternate" hreflang="es-ES" href="https://example.com/es-es/" /><link rel="alternate" hreflang="ja" href="https://example.com/ja/" /><link rel="alternate" hreflang="zh-Hans" href="https://example.com/zh-hans/" /><link rel="alternate" hreflang="zh-Hant" href="https://example.com/zh-hant/" /><link rel="alternate" hreflang="x-default" href="https://example.com/select/" />
Notice the canonicalized casing: en-us becomes en-US, zh-hant becomes zh-Hant, ja stays unchanged because there is no region to capitalize. The URL host and path are passed through the browser URL parser, which normalizes the address but leaves the casing of path segments intact. Ampersands in query strings, if any appear, are escaped as & so the block is safe to paste straight into HTML.
Install the Identical Block in Every Alternate Head
The same nine elements appear in the head of every page in the cluster, including each page itself. The en-US page carries a self-reference with hreflang="en-US" pointing at https://example.com/en-us/, the fr-FR page carries a self-reference with hreflang="fr-FR", and so on. Google documents the self and return links as essential signals; a one-way declaration can be ignored because another site must not be able to claim your page as its alternate unilaterally.
If your publishing system supports partials or includes, store the block as a single template and inject it everywhere it is needed. If your CMS lets each page declare only its own locale, you still need the full set on every page; the rule does not relax for editorial convenience. Do not combine inconsistent hreflang sets across HTML head, HTTP Link headers, and XML sitemaps. Google treats those implementation methods as equivalent, and maintaining several copies can create drift; choose the one your publishing system can keep complete and synchronized.
Confirm Self and Return Links After Deployment
The generator cannot access remote pages or prove reciprocal links. After deployment, crawl a sample from every language cluster and compare sets mechanically. Confirm each alternate returns a useful 200 page; if any page in the hreflang set returns a 404 or 500 error, the entire hreflang group can be ignored. The current hreflang implementation in HTML form is documented by Google Search Central on localized versions, and the head element mechanics are described in the WHATWG HTML alternate links specification.
A practical verification checklist for the example above:
- Each of the nine pages renders exactly nine rel=alternate elements in its head.
- Every element's hreflang attribute matches the canonicalized tag produced by the generator.
- Every element's href is the fully qualified URL of the page it claims.
- Every alternate URL returns a 200 response with localized, substantially equivalent content.
- The same block of nine elements appears character-for-character on each alternate page.
Rules the Generator Enforces So Output Stays Clean
The tool validates a conservative tag shape and casing rather than the complete current ISO language and country registries supported by any particular search engine. A structurally tidy code can still be unsupported or inappropriate, so every intended language and region must be verified against current Google documentation and the actual content audience before deployment. The generator surfaces the following limits and rejections as part of its standards-aligned fixtures:
| Input shape | Outcome |
|---|---|
| Two-letter language only (fr, ja, de) | Accepted; preserved as-is |
| Language plus region, lowercase (en-us, fr-ca) | Accepted; canonicalized (en-US, fr-CA) |
| Language plus script, mixed case (zh-hant) | Accepted; canonicalized (zh-Hant) |
| Language plus script plus region (cmn-Hans-CN) | Accepted; structure preserved |
| Region-only first subtag (US, FR) | Rejected; language subtag required first |
| x-default | Accepted; identifies a fallback page, not a language |
| Duplicate locale rows, case-insensitive | Rejected as a duplicate |
| Relative URL (/en-us/) | Rejected |
| Scheme-relative URL (//example.com/en-us/) | Rejected |
| URL with fragment (#section) | Rejected |
| URL with credentials (user:[email protected]) | Rejected |
| Fewer than two rows | Rejected |
| More than 100 rows | Rejected |
| Row missing the vertical bar | Entire set rejected |
| Row with more than one vertical bar | Entire set rejected |
The eight standards-aligned fixtures shipped with the tool cover generic languages, regional casing, German and French regions, simplified and traditional Chinese script tags, a language-script-region combination, and the x-default fallback. Additional tests assert exact HTML escaping and reject duplicates, relative URLs, fragments, credentials, and incomplete one-row sets. The generator intentionally fails the entire set on malformed input rather than emitting a partial block, so a country or language version can never be silently omitted from the copied output.
This tool specifically produces HTML head elements, not HTTP Link headers or sitemap XML entries. Ongoing quality depends on updating every member of the cluster when a locale is added, removed, redirected, or moved to a new canonical URL, then re-running the same row list to regenerate the block. The escaped output from the Hreflang Generator remains the single source of truth that every alternate page head should mirror.