Page Relationship Builder

A quick orientation: this page explains how the page relationship builder constructs page-to-page hreflang relationships, walks through the relationship-building process, covers the reciprocity errors that cause search engines to ignore hreflang annotations, and describes how this tool differs from tag generators and URL mappers.

What is a page relationship builder?

A page relationship builder creates explicit, validated connections between localized versions of the same page. In the hreflang specification, every relationship is a pair: page A declares page B as its alternate, and page B must declare page A as its alternate. This bidirectional requirement — called reciprocity — is the single most violated rule in hreflang implementations. The page relationship builder makes reciprocity its core function.

The tool models hreflang as a relationship graph. Each page is a node. Each hreflang annotation is a directed edge from one page to another. For the annotation to be valid, the reverse edge must also exist. The builder visualizes this graph, highlights missing reverse edges, and generates the complete set of annotations for every node — ensuring that every relationship is reciprocal by construction.

This graph-based approach catches problems that linear tools miss. A tag generator produces correct markup for one page, but it can't verify that the target page contains the reciprocal entry. A URL mapper produces URL lists, but doesn't track relationship directionality. The page relationship builder operates at the relationship level, where reciprocity violations actually occur, and prevents them structurally.

All processing runs in the browser. Your page URLs and relationship data are not sent to any server.

How to use this page relationship builder

Follow these steps to build validated page-to-page hreflang relationships:

1. Add your first page. Enter the absolute HTTPS URL and locale code of any page in the localized set. This becomes the first node in the relationship graph.

2. Add related pages. For each additional localized version, enter the URL and locale code. As you add pages, the builder creates bidirectional relationships between the new page and all existing pages in the set. You can see the relationship graph update in real time.

3. Review the relationship graph. The visual graph shows every page as a node and every hreflang relationship as a line. Green lines indicate reciprocal relationships (both directions declared). Red lines indicate one-way relationships that would be invalid. In normal builder operation, all lines should be green because the builder creates both directions simultaneously.

4. Import existing relationships (optional). If you have an existing hreflang implementation and want to check it, paste the current <link rel="alternate"> tags from any page. The builder parses them, builds the graph from one direction, and highlights which reverse relationships are missing — giving you an audit of your current implementation.

5. Export relationship data. The builder exports the complete relationship set in multiple formats:

   • Per-page <link> tag blocks (the tags each page needs).
   • A relationship matrix (CSV showing all page-to-page connections).
   • JSON for programmatic use with the hreflang tag generator or other automation tools.

Common errors and how to fix them

These are the five relationship-level errors that cause the most hreflang implementation failures.

1. One-way relationships. The English page declares the Spanish page as an alternate, but the Spanish page doesn't declare the English page. This is the most common hreflang error globally. When search engines detect a one-way relationship, they typically ignore the annotation entirely. The builder creates both directions simultaneously, making one-way relationships impossible during initial setup.

2. Partial relationship sets. A site with 5 locales should have every page referencing all 5 versions (including itself). If the German page references English and Spanish but not French and Italian, the relationships with French and Italian are missing — even if those pages reference the German page. The builder ensures every node connects to every other node in the set.

3. Stale relationships after page deletion. When a localized page is removed but its hreflang entries remain on other pages, those entries point to 404 pages. The builder's import-and-audit feature identifies entries that may point to non-existent pages (based on URL pattern analysis).

4. Relationship sets that span different page concepts. Connecting the English pricing page to the Spanish about page creates a nonsensical relationship. Hreflang relationships must connect equivalent content in different languages. The builder groups pages by concept (based on URL path similarity) and warns when a relationship crosses conceptual boundaries.

5. Self-reference omission. Every page must include itself in its hreflang annotations. The builder adds self-references automatically for every node in the graph, eliminating this common oversight.

How this tool is different

Four things set this page relationship builder apart from tag generators and URL mapping tools:

• Graph-based modeling. Hreflang relationships are modeled as a graph with nodes and bidirectional edges, making reciprocity visible and enforceable rather than implicit and easily forgotten.
• Visual relationship audit. The graph visualization shows the complete relationship topology at a glance, making it easy to spot gaps, orphans, and one-way connections that text-based tools obscure.
• Import-and-audit mode. You can paste existing hreflang tags to diagnose reciprocity problems in your current implementation, not just build new relationships from scratch.
• Structural reciprocity guarantee. By creating both directions of every relationship simultaneously, the builder makes non-reciprocal annotations impossible during initial setup — the most common hreflang error is eliminated by design.

Everything runs in your browser with no server involvement. For a full explanation of hreflang reciprocity requirements, see the what is hreflang guide.