Global URL Mapper

This page explains what the Global URL Mapper does, how to create a centralized table connecting regional URLs across your international site, the step-by-step workflow, common mapping failures, and how this mapper differs from a general hreflang tag generator.

What is a global URL mapper?

A global URL mapper is a hreflang tool that takes a URL-table approach to international SEO. Instead of building hreflang tags one page at a time, you construct a global mapping table where every row represents a page and every column represents a locale. The intersection of a row and column contains the URL that serves that page in that locale. From this table, the tool generates the complete hreflang annotation set for every page in every locale.

This approach treats your international URL structure as a relational dataset. Each page has a canonical identity (the content topic) and multiple localized expressions (the URLs). The global URL mapper makes this relationship explicit, which is critical for sites with complex URL architectures — different domains per country (example.de, example.fr, example.co.uk), different subdirectory patterns, or mixed structures where some markets use subdomains and others use subdirectories.

The output covers HTML <link> tags, HTTP Link: headers, XML sitemap xhtml:link elements, and JSON-LD, generated from the global table for every page simultaneously.

How to use the global URL mapper

Follow this table-based workflow:

1. Define your locale columns. Start by listing every locale your site supports — en-US, de-DE, fr-FR, es-ES, ja, and so on. Each locale becomes a column in the mapping table.
2. Add page rows. Each row represents one piece of content that exists in multiple languages. Give it a page identifier (like homepage, pricing, about) for your reference. The identifier is not included in the output; it is purely organizational.
3. Fill in URLs. For each page-locale intersection, paste the absolute HTTPS URL. Leave cells empty for locales where a translation does not exist. The tool generates hreflang sets only for the locales that have URLs.
4. Set x-default per row. For each page, designate which locale URL serves as x-default. You can also set a global x-default locale that applies to all rows unless overridden.
5. Validate the entire table. The tool checks every cell for URL validity, every row for reciprocity, every column for consistency, and the overall table for duplicate URLs or locale codes. Fix issues in the table editor, then generate output.

Common errors and how to fix them

Table-based mapping introduces specific error patterns:

1. Empty cells that should not be empty. If your German column has URLs for 48 of 50 pages, the two empty cells might be intentional (those pages are not translated) or accidental (someone forgot to paste the URL). The tool highlights incomplete rows and asks you to confirm the omission is intentional.

2. Same URL in multiple cells. If example.com/en/pricing appears in both the en-US and en-GB columns, Google sees the same URL tagged as two different locales. This is only valid if the page genuinely serves both markets (in which case, consider using a single en tag instead). The tool warns on duplicate URLs across columns.

3. Cross-domain inconsistencies. If your US site is on example.com and your German site is on example.de, every row must consistently use the correct domain for each locale. A single row where the German URL accidentally points to example.com/de/ instead of example.de/ breaks the pattern. The tool detects domain inconsistencies within each locale column.

4. Row-level reciprocity failures. The global table guarantees reciprocity by design — if a cell has a URL, the generated tags for that page include all filled cells in the row. But if you manually edit the output and remove one entry, reciprocity breaks for that pair. The tool's output is always complete; the risk is in post-generation editing.

5. Locale column ordering confusion. The order of locale columns does not affect the generated output, but it affects usability. If en-US is column 2 and en-GB is column 15, it is easy to paste a URL in the wrong English column. The tool lets you reorder columns and groups same-language locales together by default.

How this tool is different

The global URL mapper takes a structured-data approach to hreflang:

• Table-based input. A spreadsheet-like grid where rows are pages and columns are locales. This mirrors how international SEO teams track URL mappings in spreadsheets — but with built-in validation.
• Cross-domain support. The tool expects that different locales may live on different domains, subdomains, or subdirectories. It validates each cell independently and checks domain consistency within each locale column.
• Bulk table operations. Sort rows, filter by completion status, search for specific URLs, and batch-assign x-default. These operations make it practical to manage tables with hundreds of rows.
• Full-site export. Generate the complete hreflang package for every page in the table in one operation. The output is organized by page, so you can deploy each page's tags to the correct location in your CMS or server configuration.

For single-page hreflang work, use the hreflang tag generator. For auto-discovering URL counterparts from a single starting URL, try the url language mapper.