A quick orientation: this page covers what alternate tags are, how to use the
builder above to generate correct <link> elements for your HTML <head>,
a deep dive into implementation details and syntax, the copy-paste mistakes
that break most setups, and how this tool compares to manual tag writing.
What are alternate tags?
Alternate tags — specifically, <link rel="alternate" hreflang="..." href="..."> elements — are HTML tags placed in a page's <head> section that tell search engines about localized or regionalized versions of that page. When Google encounters an alternate tag on your English page that points to a Spanish page with hreflang="es", it understands that the Spanish page is the same content in a different language and should be shown to Spanish-speaking users instead.
The term "alternate tags" is shorthand in the SEO community for what the HTML specification calls link elements with rel="alternate" and a hreflang attribute. They are one of three methods for declaring hreflang relationships — the other two are HTTP Link: headers and XML sitemap xhtml:link annotations. HTML <link> tags are the most widely used method because they work with any web stack and are easy to inspect in the browser's developer tools.
This builder generates syntactically correct, self-referencing, reciprocity-ready alternate tag sets from a list of localized URLs. It handles the self-closing syntax, attribute ordering, and HTTPS validation that manual tag writing often gets wrong. Everything runs in your browser with no server involved.
How to use this alternate tag builder
Follow these steps to build a complete set of alternate tags for a page:
-
Enter your localized URLs. For each language or regional version of the page, enter the absolute HTTPS URL and select the locale code. Use ISO 639-1 language codes (
en,es,de) and optionally add an ISO 3166-1 alpha-2 region code (en-US,es-MX,de-AT). The autocomplete validates both code lists as you type. -
Add an x-default entry (recommended). The x-default URL is the fallback page shown when none of your declared locales match the user's language preferences. Most sites point x-default to their primary English page or a locale-selection landing page. Add it by selecting "x-default" from the locale dropdown.
-
Review the validation panel. The builder checks your input in real time:
- Every URL must be absolute and use HTTPS.
- Locale codes must be valid ISO format with a hyphen separator (not an underscore).
- No duplicate locales are allowed.
- Trailing-slash consistency is checked across all URLs.
- Self-reference is included automatically — you don't need to add it.
-
Copy the generated tags. The output panel shows the complete
<link>tag block for each page. Every page gets an identical set of alternate tags (each referencing all others plus itself). Copy the block for each page and paste it into that page's<head>section. -
Verify in your browser. After deploying the tags, open each page in your browser, right-click, and select "View Page Source" (not "Inspect Element" — the DOM inspector shows the live DOM, which can differ from the source HTML). Search for
rel="alternate"to confirm the tags are present and correctly formatted.
Deep dive: HTML alternate tag syntax and implementation
Getting the syntax right matters because search engines parse hreflang tags strictly. A malformed tag is silently ignored — no error, no warning, just missing international coverage.
Self-closing syntax. The <link> element is a void element in HTML, meaning it has no closing tag. The correct syntax is:
<link rel="alternate" hreflang="es" href="https://example.com/es/page" />
The trailing /> is optional in HTML5 (you can write > instead), but including it is conventional and makes the tag valid in both HTML5 and XHTML contexts. This builder always includes the self-closing slash for maximum compatibility.
Attribute order. The HTML specification does not require attributes in a specific order. rel, hreflang, and href can appear in any sequence and the tag is equally valid. However, this builder uses a consistent order — rel first, then hreflang, then href — because consistent ordering makes visual inspection and diff-based auditing easier.
Placement in <head>. Alternate tags must appear inside the <head> element, before the closing </head> tag. Placing them in the <body> causes search engines to ignore them. The builder's output is designed to be pasted directly inside <head>, grouped together and clearly commented for maintainability.
Self-reference requirement. Every page must include a <link> tag pointing to itself with its own locale code. A page at https://example.com/en/page must include:
<link rel="alternate" hreflang="en" href="https://example.com/en/page" />
This might seem redundant, but it's required by the specification. Without the self-reference, search engines may not process the rest of the hreflang set correctly. This builder adds the self-reference automatically — you don't need to add your own page to the input list.
Relationship to canonical tags. A common question: how do alternate tags interact with the <link rel="canonical"> tag? They serve different purposes. The canonical tag says "this is the preferred version of this URL" (handling duplicates within one language). The alternate tag says "this is the equivalent page in a different language." Both can and should coexist on the same page. The canonical should point to the page itself (self-canonical), and the alternates should point to sibling pages in other locales. If the canonical points to a different URL, search engines may ignore the hreflang annotations on that page.
Multiple hreflang sets on one page. You should only have one hreflang set per page. If your CMS injects hreflang tags and you also add them manually, you end up with duplicate or conflicting declarations. Before deploying the builder's output, search the page source for any existing rel="alternate" tags and remove them.
Hreflang and JavaScript-rendered pages. If your site renders content via JavaScript (React, Angular, Vue), the alternate tags must be present in the initial HTML served to search engines — either via server-side rendering (SSR) or static generation. Tags injected by client-side JavaScript may not be picked up by Googlebot in time. This builder produces static HTML tags; how you inject them into your SSR pipeline depends on your framework.
Common errors and how to fix them
Here are the five alternate tag mistakes this builder catches that cause the most broken implementations.
-
Using relative URLs. Writing
href="/es/page"instead ofhref="https://example.com/es/page"is the most common copy-paste error. Search engines require absolute URLs in hreflang attributes. Relative URLs are silently ignored. The builder rejects any URL that doesn't start withhttps://. -
Using underscores in locale codes. Writing
hreflang="en_US"instead ofhreflang="en-US"is invalid. The hreflang attribute uses hyphens between language and region codes, following BCP 47 conventions. Underscores are a programming convention (Python locales, POSIX) that doesn't apply to HTML. The builder enforces hyphen-separated codes. -
Forgetting the self-reference. Manually writing alternate tags, it's natural to list only the other language versions. But the spec requires the page to include itself. Missing the self-reference is the second most common hreflang error after non-reciprocity. This builder adds it automatically.
-
Placing tags outside
<head>. If your CMS or template engine injects content before the<head>opens or after it closes, the alternate tags end up in the wrong place. The builder can't control where you paste its output, but the output includes HTML comments marking the hreflang block boundaries (<!-- hreflang start -->...<!-- hreflang end -->), making it easy to verify placement in your source. -
Conflicting canonical and alternate signals. If a page has
<link rel="canonical" href="https://example.com/en/other-page">(pointing to a different URL), the alternate tags on that page are likely ignored by search engines. The builder warns you if any input URL appears to be a non-self-canonical situation based on the URL patterns, though full canonical tag analysis requires inspecting the live pages with a tool like the alternate page connector.
How this tool is different
Four things set this alternate tag builder apart from writing tags by hand or using basic generators:
- Live validation on every keystroke. You see errors and warnings as you type, not after hitting a generate button. The feedback loop is instant, which means you catch problems before they reach production.
- Automatic self-reference. You never forget the self-reference because the builder adds it. This eliminates the second most common hreflang error without requiring you to remember the rule.
- Per-page output with copy buttons. The builder generates a separate tag block for each page in the set, each with its own copy-to-clipboard button. You don't have to manually extract the right subset of tags for each page — the tool does the partitioning for you.
- Browser-verifiable output. The builder produces clean, commented HTML that's easy to find in View Source. The comments and consistent formatting make it practical to verify deployment without specialized crawling tools.
Everything runs in your browser. There is no signup, no server that sees your URLs, and no usage limit. The tool is a premium resource for developers and SEO professionals implementing hreflang via HTML <link> tags — the most common and most inspectable deployment method for international SEO.