This page explains what the URL Variant Mapper does, how to import page variants for bulk validation and hreflang generation, the step-by-step workflow, import errors that cause invalid hreflang sets, and how this mapper differs from a general hreflang tag generator.
What is a URL variant mapper?
A URL variant mapper is a hreflang tool designed for importing and validating large sets of page variants. You supply a structured data file — CSV, TSV, or JSON — containing your pages and their locale-specific URLs, and the tool parses, validates, and generates hreflang annotations for every entry in the import.
This workflow is built for teams that already maintain a URL mapping in a spreadsheet, a database export, or a CMS report. Instead of re-entering data into a hreflang generator, you export your existing mapping and import it directly. The tool validates every entry against hreflang requirements (reciprocity, self-reference, ISO code validity, HTTPS, trailing-slash consistency) and generates output for the entire import in one pass.
The URL variant mapper handles imports with thousands of rows efficiently, processing data off the main thread to keep the interface responsive. Output formats include HTML <link> tags, HTTP Link: headers, XML sitemap xhtml:link elements, and JSON-LD.
How to use the URL variant mapper
Follow this import-and-validate workflow:
- Prepare your data file. Structure your CSV, TSV, or JSON with columns for page identifier, locale code, and URL. The locale code must be a valid ISO 639-1 language code optionally followed by a hyphen and an ISO 3166-1 alpha-2 region code (for example,
en,es-MX,de-AT). URLs must be absolute and use HTTPS. - Import the file. Upload or paste the file contents. The tool auto-detects the format (CSV, TSV, or JSON) and parses the data. A parsing summary shows the total rows, valid rows, and rows with issues.
- Review validation results. The tool runs a comprehensive validation pass: ISO code validity, URL format, duplicate locales within the same page group, missing self-references, and reciprocity. Issues are displayed in a filterable list grouped by severity (errors vs. warnings).
- Fix issues in the editor. Click any issue to jump to the affected row in an inline table editor. Correct the data directly — update a locale code, fix a URL, or remove a duplicate row. The tool re-validates in real time as you edit.
- Generate and export. Once all errors are resolved, generate the hreflang output for every page group in the import. Download the complete output as an XML sitemap, a ZIP of HTML snippets, or a bulk HTTP header configuration.
Common errors and how to fix them
Importing existing data surfaces errors that were invisible in the source spreadsheet:
-
Malformed locale codes from spreadsheet formatting. If your spreadsheet auto-formats
pt-BRas a date oren-INas text with different casing, the imported locale code may be invalid. The tool shows the raw imported value next to the expected format so you can identify formatting artifacts. -
Relative URLs instead of absolute URLs. Spreadsheet exports often contain relative paths (
/en/about) rather than absolute URLs (https://example.com/en/about). The tool detects relative URLs and offers a bulk-fix option: specify a base domain, and every relative path is prefixed to form an absolute URL. -
Duplicate page-locale pairs. If your spreadsheet has two rows for the same page with the same locale code but different URLs, the hreflang set has a conflict. The tool highlights duplicates and lets you choose which URL to keep or merge the entries.
-
Missing page groups. If your import covers pages A through Z for English and Spanish but only A through M for German, the German entries for pages N through Z are missing. The tool compares locale coverage across page groups and flags asymmetric sets.
-
Encoding issues in non-ASCII URLs. CSV files saved with incorrect encoding may corrupt non-ASCII characters in URLs (for example, Japanese or Arabic path segments). The tool detects encoding issues by checking for common corruption patterns (replacement characters, double-encoding) and warns before processing.
How this tool is different
The URL variant mapper is purpose-built for the import-validate-generate pipeline:
- Multi-format import. CSV, TSV, and JSON are all accepted. The tool auto-detects the format, handles common edge cases (quoted fields, BOM markers, different line endings), and normalizes the data before validation.
- Comprehensive validation suite. Every hreflang requirement is checked in one pass: ISO code validity, URL format, duplicate detection, reciprocity verification, self-reference inclusion, trailing-slash consistency, and protocol uniformity. The result is a single validation report covering the entire import.
- Inline editing. Fix issues directly in the tool without returning to your spreadsheet. Changes are re-validated in real time, so you can clear errors incrementally.
- Bulk fix operations. Common issues like relative URLs, lowercase region codes, and trailing-slash inconsistencies can be fixed across the entire import with one click. This saves significant time compared to correcting rows individually.
For entering hreflang data manually rather than importing it, use the hreflang tag generator. For auto-discovering URL relationships from a flat list, see the alternate mapping generator.