URL Variant Generator

This page explains what the URL Variant Generator does, how to produce localized URL variants from a canonical URL, the step-by-step workflow, errors that arise from variant generation, and how this generator differs from a general hreflang tag generator.

What is a URL variant generator?

A URL variant generator is a hreflang tool that creates localized URL candidates from a canonical source URL. You provide one URL — typically your primary-language page — and a list of target locales, and the tool generates the expected URLs for each locale based on your site's URL pattern. It then produces the hreflang annotation set for the entire variant group.

This tool addresses a workflow gap that many international SEO teams encounter: you know what your English page URL looks like, you know your site uses a /{locale}/ subdirectory pattern, and you need to quickly generate the full set of expected alternate URLs and their hreflang tags. Doing this manually for every page is error-prone and slow. The URL variant generator automates the expansion.

The tool supports four URL pattern types: subdirectory (/en/, /es/), subdomain (en.example.com), ccTLD (example.com, example.de), and query parameter (?lang=en). It generates HTML <link> tags, HTTP Link: headers, XML sitemap xhtml:link elements, and JSON-LD.

How to use the URL variant generator

Follow this expansion workflow:

1. Enter your canonical URL. Paste the absolute HTTPS URL of your primary-language page. This is the starting point from which all variants will be derived.
2. Select your URL pattern. Choose how your site structures localized URLs: subdirectory, subdomain, ccTLD, or query parameter. The tool auto-detects the pattern from your canonical URL and lets you confirm or override.
3. Define target locales. Enter the ISO 639-1 language codes (with optional ISO 3166-1 region codes) for every locale you want to generate variants for. The tool pre-fills common locales and lets you add or remove entries.
4. Review generated variants. The tool expands your canonical URL into one variant per locale. For subdirectory patterns, /en/pricing becomes /es/pricing, /de/pricing, /fr/pricing, and so on. Review each generated URL and correct any that do not match your actual site structure — especially pages with translated slugs.
5. Validate and generate hreflang output. The tool validates every variant URL for format correctness, checks for duplicate locales, generates self-references, and produces the hreflang set. Export in your preferred format.

Common errors and how to fix them

URL variant generation can introduce errors when the generated URLs do not match reality:

1. Generated URLs that do not exist. If the tool generates /fr/pricing but your French pricing page is actually at /fr/tarifs (a translated slug), the generated URL points to a 404. Always verify that each generated variant URL matches the actual URL on your server. The tool flags this risk and prompts you to confirm each variant.

2. Incorrect pattern detection. If your canonical URL is https://en.example.com/pricing and the tool detects a subdomain pattern, but your German site is at https://example.de/preise (a ccTLD with a translated path), the subdomain pattern generates incorrect variants. Override the auto-detected pattern and, if needed, manually edit individual variant URLs.

3. Missing locale in the pattern. If your canonical URL is https://example.com/pricing with no locale indicator, the pattern detector cannot determine where the locale belongs. In this case, specify the pattern manually — for example, "subdirectory before the first path segment" — and the tool inserts the locale code accordingly.

4. Duplicate locale codes from overlapping entries. If you enter both en and en-US as target locales and your URL pattern generates /en/pricing and /en-us/pricing, you have two English variants that may or may not represent the same content. The tool warns when locale entries overlap in language without differentiation in region.

5. Protocol mismatches in ccTLD variants. When generating ccTLD variants, the tool assumes HTTPS for all domains. If one of your ccTLD domains does not support HTTPS, the generated variant URL is unreachable. The tool flags all non-HTTPS situations but cannot verify SSL certificate status.

How this tool is different

The URL variant generator automates the expansion from one URL to many:

• Pattern-based expansion. Enter one URL and the tool generates all locale variants automatically. This is faster than entering each variant URL manually, especially for sites with 10-plus locales.
• Four pattern types. Subdirectory, subdomain, ccTLD, and query parameter patterns are all supported, with auto-detection and manual override.
• Variant verification prompts. Because generated URLs may not match actual URLs (due to translated slugs, custom paths, or structural exceptions), the tool prominently prompts you to verify each variant before generating hreflang output.
• Batch page expansion. Enter multiple canonical URLs at once and expand all of them to all locales in a single operation. This batch mode produces the hreflang set for every page in your list without per-page repetition.

For manually entering known URLs rather than generating them from patterns, use the hreflang tag generator. For auto-discovering which URLs are alternates of each other from a flat list, see the alternate mapping generator.