Page Variant Generator

This page explains what the Page Variant Generator does, how to generate hreflang annotations for page variants derived from a master URL, the step-by-step process, the technical underpinnings of page-variant hreflang, common variant generation mistakes, and how this tool differs from a standard hreflang tag generator.

What is a page variant generator?

A page variant generator is a hreflang tool that starts from a single master URL and produces the complete hreflang annotation set for all language and regional variants of that page. You provide the canonical URL of your primary page, define the locales you support, and the tool generates the expected variant URLs based on your site's URL pattern — then outputs the hreflang annotations for the entire set.

This approach is designed for sites with predictable URL structures. If your English page lives at https://example.com/en/pricing and your other languages follow the pattern https://example.com/{locale}/pricing, the page variant generator can derive all variant URLs from the master URL and a list of target locales. You do not need to manually enter every variant URL — the tool calculates them.

How to use the page variant generator

Follow this process to generate page variants:

1. Enter your master URL. Paste the absolute HTTPS URL of the page you want to annotate. This is typically the primary-language version of the page.
2. Define your URL pattern. Tell the tool how your site structures locale-specific URLs. Supported patterns include:
   • Subdirectory: https://example.com/{locale}/page — the locale is a path segment.
   • Subdomain: https://{locale}.example.com/page — the locale is a subdomain.
   • Query parameter: https://example.com/page?lang={locale} — the locale is a URL parameter.
   • Custom pattern: Define your own template with a {locale} placeholder for non-standard structures.
3. Select your target locales. Choose the languages and optional regions you support. The tool provides the full ISO 639-1 language list and ISO 3166-1 alpha-2 region list for selection.
4. Review generated variant URLs. The tool expands the pattern with each locale to produce the full set of variant URLs. Review them to confirm they match your actual site structure. Edit any URLs that deviate from the pattern (translated slugs, for instance).
5. Add x-default and generate. Designate which variant (or a separate URL) serves as x-default. The tool then produces the complete hreflang set in HTML, HTTP header, XML sitemap, or JSON-LD format.

Deep dive: pattern-based variant generation

The core insight behind the page variant generator is that most multilingual sites follow consistent URL patterns. Exploiting this consistency eliminates manual data entry and reduces errors.

Subdirectory patterns. The most common multilingual URL structure uses locale subdirectories: /en/, /es/, /de/, /fr/. Given a master URL like https://example.com/en/blog/seo-guide, the tool extracts the locale segment (en), replaces it with each target locale, and produces https://example.com/es/blog/seo-guide, https://example.com/de/blog/seo-guide, and so on. This works reliably when path segments after the locale are identical across languages.

Handling translated slugs. Some sites translate URL slugs: /en/about-us becomes /de/ueber-uns. In this case, the pattern-based approach produces an incorrect URL (/de/about-us). The tool lets you override individual variant URLs after generation. You keep the pattern-based convenience for the majority of URLs and manually correct the exceptions.

Subdomain and ccTLD patterns. For sites using en.example.com, es.example.com, or example.de, example.fr, the tool replaces the subdomain or TLD component. This is less common but equally supported.

Variant validation. After generating variant URLs, the tool cannot verify that each URL actually resolves to a live page (that would require server-side crawling). However, it flags variant URLs that are structurally suspicious — for example, a locale code that does not match the path segment (/en/page tagged as es). You should verify that the generated URLs return 200 status codes before deploying the hreflang annotations.

For a comprehensive guide on URL structures in multilingual SEO, see the hreflang implementation guide.

Common errors and how to fix them

These mistakes are specific to pattern-based variant generation:

1. Applying the wrong pattern. If your site uses subdirectories for most languages but a ccTLD for one market (example.de instead of example.com/de/), the pattern generates an incorrect URL for that market. Always review the generated variant list and correct any URLs that do not match your actual site structure.

2. Generating variants for locales you do not actually serve. Selecting 15 locales when your site only has content in 8 produces 7 variant URLs that point to 404s or redirect to a fallback page. Only select locales where the page genuinely exists with localized content.

3. Forgetting to handle locale-specific path differences. If your English page is at /en/pricing but your Japanese page is at /ja/kakaku (translated slug), the pattern-generated URL /ja/pricing will be wrong. Edit the generated URL before generating output.

4. Not updating variants after URL structure changes. If you migrate from subdirectories to subdomains, old pattern configurations generate incorrect URLs. Update the pattern definition whenever your site's URL structure changes.

5. Ignoring the x-default in pattern-based generation. The x-default URL may not follow the same locale pattern — it might be a locale selector at the root (https://example.com/) rather than a locale-prefixed page. Always set x-default explicitly rather than relying on the pattern to generate it.

How this tool is different

The page variant generator is optimized for efficiency when your site follows consistent URL patterns:

• One-URL input. Enter a single master URL instead of manually entering every variant. The tool derives the rest from your URL pattern. For a site with 12 locales, this eliminates 11 manual URL entries per page.
• Pattern library. Save and reuse URL patterns. If your site uses the same subdirectory structure across all pages, define the pattern once and apply it to every page you process.
• Batch master URL input. Paste a list of master URLs (one per line) and the tool generates variant sets for all of them simultaneously, using the same pattern. This scales to hundreds of pages in a single operation.
• Override workflow. After pattern expansion, you can edit individual variant URLs without losing the pattern definition. This handles the common case where most URLs follow the pattern but a few have translated slugs or non-standard structures.

For manual URL-by-URL hreflang building, use the hreflang tag generator. For mapping existing URL pairs without pattern assumptions, try the URL language mapper.