Hreflang Cluster Receipts

You know which URL should serve which locale. This checks what your pages actually declare against that matrix and gives you a receipt for every page, every edge and every finding.

What it does

• Takes clusters you supply: an id plus an expected map of locale to public HTTPS URL (up to 100 distinct pages per run). Only those URLs are fetched. Nothing is crawled or discovered.
• Reads hreflang declarations from the HTML head and the HTTP Link header.
• Checks, per page: self-reference, every expected locale present and pointing at the expected URL, unexpected locales, duplicate locale labels with conflicting targets, HTML versus header conflicts, relative hrefs, canonical differences, redirects on supplied URLs, and x-default (advisory, or an error if you turn on Require x-default).
• Checks, per edge: if page A declares page B, whether B was fetched and declares A back. A missing return tag is reported only when B was fetched successfully.
• Cross-domain alternates are valid and are not flagged.

What it does not do

• No JavaScript rendering. Declarations injected by scripts are not seen.
• No sitemap hreflang.
• No language detection, no automatic fixes, no changes to your site.
• A clean result is a structural result. It is not a statement that Google accepts or indexes these annotations.
• Locale codes are checked for the Google-supported shape (language, optional script, optional region; region alone is invalid) against the ISO-style code tables built into the runtime. This is a practical check, not a Google certification.
• Other tools check hreflang reciprocity, some at lower per-page prices. This one is built around your expected locale matrix and explicit "could not verify" cases. If you only need a quick reciprocity check, a cheaper tool may be enough.

Honest unknowns

If a page fails to load, is blocked, is not HTML, or goes over the page cap, the cluster is PARTIAL_UNVERIFIABLE and edges touching it are RECIPROCITY_UNVERIFIABLE. A partial cluster is never graded as passing.

Input

{
  "clusters": [
    { "id": "product-a", "expected": { "en-US": "https://example.com/us/", "en-GB": "https://example.com/gb/", "de": "https://example.de/", "x-default": "https://example.com/" } }
  ],
  "requireXDefault": false,
  "ignoreUnexpectedLocales": false,
  "maxPages": 100
}

Output

Rows in the default dataset: cluster_receipt (COMPLETE_NO_DECLARED_ISSUES, COMPLETE_WITH_ISSUES or PARTIAL_UNVERIFIABLE), page_receipt, edge_receipt and finding. Each has clusterId, sourceUrl, locale, expectedUrl, observedUrl, declarationMethod, reciprocalStatus, canonical, status, issueCode, evidencePointer, checkedAt, billablePage and coverage. Also findings.csv, edges.csv, graph.json and a run summary in the key-value store.

Billing

Pay per successfully fetched distinct page. A page that appears in several clusters is billed once per run. Failed, blocked, invalid and over-cap pages are not charged. A successfully fetched page that declares nothing is charged and reported as missing declarations.

Safety

HTTPS only, no private or loopback addresses (checked at every redirect), 3 redirects, 2 MB and 15 s per page, low concurrency.