Multi-Region Hreflang XML Generator & Geotargeting Matrix
XML sitemap generator and validation script for multi-region websites. Validates bidirectional reciprocal tags, ISO 639-1 languages, and x-default fallbacks.
Multi-Region Bidirectional Hreflang Architecture
Validates bidirectional hreflang return links, ISO 639-1 language codes, ISO 3166-1 alpha-2 country codes, and x-default fallbacks across multi-locale international setups.
Multi-Region Hreflang XML Generator & Geotargeting Matrix Configurator
Multi-Region Geotargeting — 6-Locale Hreflang Matrix with Bidirectional Validation
International SEO hreflang configuration with XML sitemap and HTML link tags across 6 regional endpoints.
1 Input Parameters & Assumptions
| Parameter | Value | Context & Provenance |
|---|---|---|
| Global Fallback (x-default) | https://gordongeraghty.com/ x-default | Default global routing URL |
| United States (en-us) | https://gordongeraghty.com/us/ en-us | Targeted US English locale |
| United Kingdom (en-gb) | https://gordongeraghty.com/uk/ en-gb | Targeted UK English locale |
| Australia (en-au) | https://gordongeraghty.com/au/ en-au | Targeted Australian English locale |
| France (fr-fr) | https://gordongeraghty.com/fr/ fr-fr | Targeted French locale |
| Germany (de-de) | https://gordongeraghty.com/de/ de-de | Targeted German locale |
2 Explicit Mathematical Formula
Reciprocal Return Pairs = N × (N - 1) = 6 × 5 = 30 bidirectional validation checks
Self-Referencing Tag Requirement = 1 per document (6/6 present)
XML Sitemap Tag Volume = 6 <loc> blocks × 6 <xhtml:link> entries each = 36 total XML link entries
Configured Locales: x-default, en-us, en-gb, en-au, fr-fr, de-de3 Computed Output Metrics
| Computed Metric | Result | Interpretation & Threshold |
|---|---|---|
| Configured Regional Locales | 6 Locales | Total international market endpoints defined in matrix |
| Bidirectional Tag Validation | PASS (30/30) Validation | All target pages contain valid reciprocal hreflang links pointing back to source |
| Export Formats Supported | XML / HTML / HTTP Protocols | Sitemap XML urlset, HTML <head> tags, and HTTP response headers generated |
Multi-Region Hreflang XML Generator & Geotargeting Matrix — Scope & Limitations
Explicit operational boundaries and constraints defining target use cases and out-of-scope scenarios.
Built For (Target Use Cases)
- Generating bidirectional hreflang tags as XML sitemap entries, HTML link tags, or HTTP headers.
- Modelling one shared locale-to-URL matrix across several regional page variants.
- Flagging missing x-default or reciprocal locale entries within that shared list.
Not Built For (Limitations & Out-of-Scope)
- Validating hreflang tags that actually live on separate real pages across a site.
- Checking ISO language or country code validity; codes are accepted as typed.
- Auditing an existing site's hreflang setup; entries are typed in manually, not crawled.
Operational Assumptions & Defaults
- Reciprocity validation assumes every listed URL shares the identical set of locale entries.
- New locale codes are lowercased automatically but not checked against ISO code lists.
- The first entry in the list is used as the XML sitemap's <loc> value.
Multi-Region Hreflang XML Generator & Geotargeting Matrix
International SEO & GeotargetingGenerate bidirectional hreflang tags for XML sitemaps, HTML head tags, and HTTP response headers with automated reciprocity validation and x-default fallback.
Locale URL Mappings (6)
Bidirectional Reciprocity Status
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://gordongeraghty.com/</loc>
<xhtml:link rel="alternate" hreflang="x-default" href="https://gordongeraghty.com/" />
<xhtml:link rel="alternate" hreflang="en-us" href="https://gordongeraghty.com/us/" />
<xhtml:link rel="alternate" hreflang="en-gb" href="https://gordongeraghty.com/uk/" />
<xhtml:link rel="alternate" hreflang="en-au" href="https://gordongeraghty.com/au/" />
<xhtml:link rel="alternate" hreflang="fr-fr" href="https://gordongeraghty.com/fr/" />
<xhtml:link rel="alternate" hreflang="de-de" href="https://gordongeraghty.com/de/" />
</url>
</urlset>Deploy Hreflang XML Sitemap & Head Tags
Deploy the generated <xhtml:link> sitemap XML block or paste the HTML <link rel="alternate"> tags into your locale layout templates.
Common Hreflang Pitfalls in Multi-Region Stores
The most frequent hreflang defect is missing reciprocal confirmation links. If page A points to page B as its Australian variant, page B must return a reciprocal link pointing back to page A. Storing hreflang in XML sitemaps reduces HTML payload weight and streamlines maintenance.
Implementation Code & Script
Generates valid XML sitemap nodes with reciprocal alternate links and an x-default fallback.
interface HreflangEntry {
lang: string;
url: string;
}
export function buildHreflangUrlNode(loc: string, alternates: HreflangEntry[], xDefaultUrl: string): string {
const links = alternates
.map((a) => ` <xhtml:link rel="alternate" hreflang="${a.lang}" href="${a.url}" />`)
.join('\n');
const xDefault = ` <xhtml:link rel="alternate" hreflang="x-default" href="${xDefaultUrl}" />`;
return ` <url>
<loc>${loc}</loc>
${links}
${xDefault}
</url>`;
}Hreflang Bidirectional Return Link QA
Verify that all regional pages cross-reference each other with self-referencing and matching return tags.
Pre-Production Verification Checklist
Confirm /en-au/ page includes an explicit hreflang="en-au" tag pointing to itself.
Verify that if /en-us/ links to /en-gb/, /en-gb/ links back to /en-us/ with identical target URL.
Ensure x-default tag points to international landing or default IP redirect router page.
Terminal Diagnostic & Debug Commands
Extracts all hreflang alternate link tags from rendered HTML head.
curl -s https://example.com/en-au/ | grep -i "rel=\"alternate\""Failure Remediation & Troubleshooting
Cause: Page A declared Page B as alternate, but Page B omitted Page A from its hreflang list.
Fix: Use centralized XML sitemap generation to enforce identical link arrays across all regional variants.
Cause: ISO 3166-1 country code for United Kingdom is "gb", not "uk".
Fix: Always use ISO 639-1 for language and ISO 3166-1 alpha-2 for country codes (e.g. en-gb).
How to cite and attribute this tool
MIT LicenceThis resource is free, open and un-gated under the MIT Open Source Licence. You are encouraged to use, integrate and cite it with attribution:
@misc{geraghty_hreflang_configuration_matrix,
author = {Geraghty, Gordon},
title = {Multi-Region Hreflang XML Generator & Geotargeting Matrix},
year = {2026},
url = {https://gordongeraghty.com/resources/technical-seo/hreflang-configuration-matrix},
note = {Head of Performance Media, Empire Amplify}
}Changelog & Version History
v1.0.0Initial release of multi-region hreflang generator with reciprocal tag checking.
Strategic Takeaway & Operational Guidelines
Missing reciprocal tags are the #1 cause of Google ignoring hreflang annotations. Defining the complete 6-locale matrix in XML sitemaps eliminates HTML payload bloat while guaranteeing 100% bidirectional compliance.