Site Alternate Builder

This page covers what the Site Alternate Builder does, how to generate hreflang annotations across an entire site rather than one page at a time, the step-by-step workflow, site-wide errors that break hreflang at scale, and how this builder differs from a general hreflang tag generator.

What is a site alternate builder?

A site alternate builder is a hreflang tool designed for generating alternate-language annotations at the site level rather than the page level. Most hreflang generators work on one page at a time — you enter the URLs for a single page's language variants, generate the tags, and repeat for the next page. That approach works for a 10-page site but becomes impractical for a site with hundreds or thousands of pages, each with multiple language versions.

The site alternate builder takes a different approach. You provide a URL mapping for your entire site — either as a structured CSV, a pattern template, or a sitemap import — and the tool generates the complete hreflang annotation set for every page in one operation. The output can be an XML sitemap with xhtml:link annotations (the most scalable format), a set of HTML snippets keyed by page path, or a bulk HTTP Link: header configuration.

This tool is essential for sites that treat hreflang as infrastructure rather than a per-page task: large e-commerce catalogs, documentation sites with hundreds of articles, and content platforms that publish in many languages.

How to use the site alternate builder

Follow this site-wide workflow:

1. Import your site's URL structure. Provide the tool with a complete list of pages and their language variants. You can paste a CSV with columns for page_id, locale, and URL; upload an existing XML sitemap for parsing; or define a URL pattern template (like https://example.com/{locale}/{path}) with a list of locales and paths.
2. Review the page-locale matrix. The tool displays a grid with pages on the vertical axis and locales on the horizontal axis. Filled cells show the assigned URL; empty cells indicate missing translations. This view immediately reveals coverage gaps across your site.
3. Handle missing translations. For pages that do not have all language versions, decide whether to exclude the missing locale from that page's hreflang set (the safe default) or point to a fallback URL. The tool supports per-page x-default assignment.
4. Set site-wide x-default. Choose a global x-default strategy: same-page English fallback, homepage, or a language selector page. You can override x-default for individual pages if needed.
5. Generate the complete site hreflang package. The tool produces a downloadable XML sitemap covering every page, or a ZIP of per-page HTML snippets, or a server-config file with HTTP headers. For very large sites, output is generated in batches with progress tracking.

Common errors and how to fix them

Site-wide hreflang generation introduces errors that page-level tools never encounter:

1. Broken reciprocity from incomplete imports. If your CSV is missing the French version of page 47 out of 500 pages, that single omission breaks reciprocity for page 47 across every locale. The page-locale matrix view catches these gaps before generation.

2. URL pattern mismatches. If most of your site follows /{locale}/path but a few pages use a different structure (/blog/{locale}/path), a pattern-based import misses the exceptions. The tool flags URLs that do not match the declared pattern and lets you correct them individually.

3. Sitemap size limits. An XML sitemap file can contain at most 50,000 URLs or 50 MB uncompressed. A site with 5,000 pages in 15 languages produces 75,000 hreflang URL entries — exceeding the limit. The tool automatically splits output into multiple sitemap files and generates a sitemap index file that references them.

4. Stale URLs from removed pages. Site-wide generation from an old CSV may include pages that have been deleted or redirected. The tool warns when URLs contain common retirement signals and recommends re-crawling your site before generating hreflang annotations.

5. Inconsistent trailing slashes across the site. One section of your site may use trailing slashes while another does not. At the site level, this inconsistency multiplies — Google treats every trailing-slash mismatch as a potential duplicate URL. The tool normalizes trailing slashes to your chosen convention and warns about entries that required normalization.

How this tool is different

The site alternate builder operates at a level of abstraction above page-level generators:

• Site-wide import. CSV, sitemap, and pattern-template inputs let you load an entire site's URL structure in one step. No page-by-page data entry.
• Page-locale coverage matrix. A visual grid shows exactly which pages have which language versions, making coverage gaps impossible to miss. Filter by locale, by coverage percentage, or by validation status.
• Bulk output formats. The tool generates a complete XML sitemap index (with automatic file splitting), a ZIP of per-page HTML snippets, or a server configuration file — outputs designed for deployment, not one-off copy-pasting.
• Incremental updates. Import a new CSV with additional pages or updated URLs, and the tool merges the changes into the existing site map. You do not have to regenerate from scratch when a few pages change.

For single-page hreflang generation, the hreflang tag generator is faster and simpler. For connecting URLs across language families, try the cross-language tag builder.