URL Alternate Mapper

A quick orientation: this page covers what URL alternate mapping is, how to use the bulk mapper above, a deep dive into CSV workflows, the mistakes that break most mapping projects, and how this tool compares to manual spreadsheet work.

What is a URL alternate mapper?

A URL alternate mapper is a tool that takes a structured list of pages across multiple locales and produces the correct rel="alternate" hreflang="..." annotations for every page in the set. Where a hreflang tag generator works one page at a time, a URL alternate mapper works at scale: you feed it a CSV or spreadsheet where each row represents one canonical page and each column holds the localized URL for a specific language-region pair, and it outputs the complete hreflang markup for every page in a single pass.

This distinction matters for sites with hundreds or thousands of localized pages. Manually entering URLs one page at a time is error-prone and slow. A mapping workflow lets you maintain a single source of truth — your URL map — and regenerate all hreflang annotations whenever your site structure changes.

The tool above accepts CSV input (paste or upload), validates every URL and locale code, checks for reciprocity across the entire map, and produces output in HTML <link> tags, HTTP Link: headers, or XML sitemap xhtml:link format. Everything runs in your browser via a Web Worker, so even a 10,000-row spreadsheet processes without locking the UI.

How to use this URL alternate mapper

Follow these steps to map your entire site's localized URLs in one session:

1. Prepare your CSV. Create a spreadsheet where the first column is a page identifier (the canonical path or slug), and subsequent columns are the absolute HTTPS URLs for each locale. Use the locale code as the column header — en, es-ES, de, fr-FR, pt-BR, and so on. Every URL must be absolute (https://example.com/...), not relative.

2. Upload or paste. Click the CSV upload button or paste your spreadsheet data directly into the input area. The tool auto-detects column headers and maps them to ISO 639-1 / ISO 3166-1 locale codes. If a header doesn't match a valid locale, you'll see a warning with suggestions.

3. Review the validation panel. The tool checks every cell: empty cells are flagged as missing translations, malformed URLs are rejected, duplicate locale columns are blocked, and protocol mismatches (HTTP vs HTTPS) are caught. Fix issues row by row or use the bulk-fix suggestions.

4. Handle partial translations. Not every page has a version in every language. The mapper handles this correctly: if a page exists in English, Spanish, and German but not French, the hreflang set for that page includes only those three locales plus an optional x-default. You don't need placeholder rows.

5. Add x-default mappings. Use the dedicated x-default column to specify the fallback URL for each page. If you leave it blank, the tool can auto-assign x-default to a locale you choose (typically en).

6. Generate and download. Pick your output format and download the complete hreflang set. For XML sitemaps, the tool produces a single file with all <url> entries and their xhtml:link sub-elements. For HTML, you get per-page <link> blocks you can inject via your CMS or templating engine.

Deep dive: CSV format and URL pattern strategies

The quality of your hreflang output depends entirely on the quality of your URL map. Here are the patterns that work and the ones that cause problems.

Column structure. The minimum viable CSV has two locale columns — say en and es. There is no upper limit, but keep your locale codes consistent. Don't mix en-US and en for the same content; pick one and use it everywhere. The tool will warn you if two columns resolve to the same effective locale.

URL patterns across locales. Sites use three common URL structures for localized content, and each demands a different mapping approach:

• Subdirectory (example.com/en/page, example.com/es/page): the most common pattern. Your CSV rows will share a domain and differ only in the locale prefix. The tool can auto-expand a base path across locales if you enable pattern mode.
• Subdomain (en.example.com/page, es.example.com/page): each locale lives on its own subdomain. Mapping is straightforward but watch for inconsistent paths — en.example.com/pricing mapping to es.example.com/precios is valid but means your slug column must hold full URLs, not just paths.
• ccTLD (example.com/page, example.es/page, example.de/page): country-code top-level domains. These are the hardest to map because the domains are completely different. Your CSV must use absolute URLs in every cell; there's no pattern to auto-expand.

Handling URL rewrites and redirects. Your mapping should use the final destination URL, not a redirect source. If example.com/en/old-page redirects to example.com/en/new-page, your CSV should contain the new URL. Mapping redirect sources produces hreflang annotations that point to URLs returning 301s, which search engines handle poorly.

Large site strategies. For sites with 5,000+ pages, break your CSV into logical sections (by subdirectory, by content type, or by locale group) and process each section separately. The tool merges output deterministically, so you can concatenate XML sitemap fragments into a single sitemap index later.

Common errors and how to fix them

Here are the five mapping mistakes this tool catches that break most bulk hreflang implementations.

1. Inconsistent row lengths. If row 47 has six locale columns but row 48 has five, the missing cell creates a silent gap in the hreflang set. The tool flags rows with fewer cells than the header expects and highlights the missing locale.

2. Swapped URLs across columns. Accidentally putting the German URL in the French column — and vice versa — is the most common copy-paste error in spreadsheet workflows. The tool can't verify that content language matches the declared locale (that requires a language alternate creator with content inspection), but it does flag URLs whose domain or path contains a different locale hint than the column header.

3. Mixed trailing slashes. Row 1 uses https://example.com/en/page while row 2 uses https://example.com/en/page/. Google treats these as different URLs, so the hreflang set becomes internally inconsistent. The validation panel flags mixed trailing slashes across the entire map and offers a one-click normalization.

4. Duplicate page mappings. Two rows that map the same canonical page to the same set of locales produce conflicting hreflang sets. The tool detects duplicate URL entries across rows and asks you to merge or remove the conflict.

5. Protocol mismatches within a row. If one cell in a row uses http:// while the rest use https://, the hreflang set for that page mixes protocols. Search engines silently discard mixed-protocol hreflang annotations. The tool blocks generation until every URL in every row uses HTTPS.

How this tool is different

Four things set this URL alternate mapper apart from manual spreadsheet work and generic tag generators:

• Bulk-native workflow. This tool was built for CSV-first input, not adapted from a single-page form. Column detection, row validation, and pattern expansion all assume you're working with hundreds of pages, not one.
• Cross-row validation. Unlike single-page tools that validate one hreflang set at a time, this mapper checks reciprocity across your entire URL map. If page A in English references page B in Spanish but page B references page C in English, the tool catches the broken triangle.
• Pattern expansion. Enable pattern mode to generate localized URLs from a base path and a set of locale prefixes. Instead of filling in 8 columns manually, define the pattern once and let the tool expand it.
• Merge-safe output. The XML sitemap output is designed to be split and merged. Process different sections of your site separately and combine the fragments into a sitemap index without worrying about duplicate or conflicting entries.

Everything runs in your browser. There is no server that sees your URLs, no upload to a third party, and no cap on the number of rows you can process. The tool is a premium resource for international SEO professionals managing multilingual sites at scale.