Skip to main content
Premium Tool

Site Variant Mapper

Map your entire site structure across locale variants with a drag-and-drop interface that builds validated hreflang annotations for every URL pair.

Loading tool…

This page explains what the Site Variant Mapper does, how to map entire site variants across locales, the step-by-step process, the technical considerations for site-wide hreflang deployment, common site-level mapping errors, and how this mapper differs from a page-level hreflang tag generator.

What is a site variant mapper?

A site variant mapper is a hreflang tool designed for mapping relationships between entire site variants — not just individual pages. If your organization runs example.com for the US, example.co.uk for the UK, example.de for Germany, and example.fr for France, the site variant mapper helps you define the page-to-page correspondence across all four sites and generate hreflang annotations for every page simultaneously.

Most hreflang tools work one page at a time: you enter URLs for a single page's language variants and generate that page's hreflang set. The site variant mapper works at the site level: you define how URL structures map between site variants, and the tool produces hreflang sets for your entire URL inventory. This is the difference between annotating one page and annotating a thousand pages in a single operation.

How to use the site variant mapper

Follow this workflow to map site variants:

  1. Define your site variants. Enter the base URL for each variant of your site: https://example.com, https://example.co.uk, https://example.de, etc. For each variant, specify the ISO language code and optional region code.
  2. Establish the URL mapping pattern. Tell the tool how URLs correspond between variants. Common patterns include:
    • Identical paths: example.com/product-a maps to example.co.uk/product-a maps to example.de/product-a.
    • Translated paths: example.com/about-us maps to example.de/ueber-uns. For translated paths, you provide an explicit mapping table or CSV.
    • Mixed patterns: Some paths are identical, some are translated. The tool handles both in the same mapping set.
  3. Import your URL list. Paste or upload a list of URLs from your primary site. The tool uses the mapping pattern to generate the expected counterpart URLs on each variant. For identical-path sites, this is automatic. For translated paths, you supply the mapping table.
  4. Review the generated mappings. The tool displays every page with its mapped counterparts across all variants. Pages with missing counterparts are flagged — you can mark them as intentionally absent (the page does not exist in that language) or as needing attention.
  5. Generate site-wide hreflang output. Export the complete hreflang set for all pages in XML sitemap format (recommended for site-wide deployment), or as per-page HTML <link> blocks that your CMS or templating system can inject.

Deep dive: site-wide hreflang architecture

Deploying hreflang across an entire site introduces architectural decisions that page-level tools do not address.

XML sitemap vs. HTML implementation. For site-wide deployment, Google recommends the XML sitemap approach. Instead of adding <link> elements to every page's <head>, you declare all hreflang relationships in your XML sitemap using xhtml:link entries. This centralizes annotation management, reduces page weight, and makes updates easier — you change one file instead of every template. The site variant mapper generates sitemap output with proper xhtml:link namespace declarations.

Handling pages that exist in some variants but not others. Not every page on your English site will have a German counterpart. Product pages for region-specific products, legal pages tied to specific jurisdictions, or blog posts not yet translated will have gaps. The correct approach is to simply omit the missing variant from that page's hreflang set — do not link to a 404 or a generic fallback page. The tool lets you mark variants as absent, and it excludes them from the generated output.

Cross-domain hreflang. When your site variants live on different domains (ccTLDs or different subdomains), the hreflang sets must cross domain boundaries. This is technically valid and well-supported by search engines, but it means your XML sitemap on example.de references URLs on example.com and vice versa. Each domain's sitemap must contain the complete hreflang set for its pages, including references to all other domains' equivalent pages.

Keeping hreflang in sync during deployments. Site-wide hreflang breaks most often during partial deployments — when new pages are added to one variant but not yet reflected in the hreflang annotations. The site variant mapper can be re-run after content changes to regenerate the full annotation set, ensuring consistency.

For more on XML sitemap hreflang implementation, see the hreflang implementation guide.

Common errors and how to fix them

These errors are specific to site-wide hreflang mapping:

  1. Assuming all paths are identical across variants. Many sites have translated URL slugs: /en/about-us becomes /de/ueber-uns. If you apply an identical-path mapping, the tool generates a reference to example.de/about-us, which may 404. Always verify whether your site uses translated slugs and provide an explicit mapping table if it does.

  2. Mapping to soft-404 pages. If example.de/product-x returns a 200 status but displays a "product not available in your region" message, it is a soft 404. Linking to it via hreflang sends users to a dead-end page. Exclude pages that are not genuinely available in a variant.

  3. Forgetting to update sitemaps after content changes. Adding 50 new product pages to your English site without adding them to the hreflang sitemap means those pages have no international annotations. Integrate the mapper into your content deployment pipeline so hreflang stays current.

  4. Generating HTML hreflang for thousands of pages. If each page has 10 hreflang entries, that is 10 <link> elements added to every page's <head>. At scale, this is measurable bloat. Use XML sitemap format for sites with hundreds or thousands of pages.

  5. Orphaned variants after site restructuring. If you redesign your German site's URL structure but do not update the hreflang mappings, every English page points to old German URLs that now redirect or 404. The tool's re-mapping workflow catches these orphans when you re-import the updated URL list.

How this tool is different

The site variant mapper operates at site scale, which sets it apart from page-level tools:

For mapping individual pages, use the URL language mapper. For general hreflang generation, start with the hreflang tag generator.

Frequently asked questions

  • ›What is a site variant mapper?
    A site variant mapper lets you visually pair every page of your site with its localized counterparts using a drag-and-drop interface, then generates hreflang tags for all pairs.
  • ›How does the drag-and-drop interface work?
    Each locale appears as a column with its page list. Drag a page from one column onto its equivalent in another column to create a mapping. The tool validates reciprocity in real time.
  • ›Can I import page lists instead of entering URLs manually?
    Yes. Upload a CSV or paste a list of URLs per locale. The mapper populates each column automatically and suggests matches based on URL pattern similarity.
  • ›What happens when the mapper cannot auto-match a page?
    Unmatched pages are listed in a sidebar so you can manually drag them into the correct group or mark them as locale-exclusive (no alternate needed).
  • ›Does the mapper support partial site mappings?
    Yes. You can map a subset of pages — such as product pages only — and the tool generates hreflang tags just for that subset without requiring the full site.
  • ›How does validation work during mapping?
    Every pair is checked for reciprocal consistency, valid locale codes, and self-reference inclusion. Warnings appear inline next to any problematic pair.
  • ›Can I add a new locale to an existing mapping?
    Yes. Add a new locale column, import the new URLs, and drag them onto existing page groups. The mapper regenerates all hreflang sets to include the new locale.
  • ›What export formats does the tool support?
    HTML link tags, HTTP Link headers, XML sitemap entries, JSON for CI/CD integration, and a printable CSV mapping summary for documentation.
  • ›Can multiple team members work on the same mapping?
    Export the current state as a JSON snapshot and share it. A teammate can import it, make changes, and re-export for review.
  • ›How does the tool handle redirected or deprecated URLs?
    It flags URLs that return 3xx or 4xx status codes during optional live checks, so you can update or remove them before generating final hreflang output.

Related tools