hreflang tag generator

How to generate hreflang tags

One pattern, one list, two copy buttons. The generator derives every URL from the pattern, so the set is complete and reciprocal by construction — nothing to cross-check by hand.

1. Enter the URL pattern. Write one version's URL with {locale} where the language segment sits: https://example.com/{locale}/pricing/. The code is inserted in lowercase; an empty segment collapses to the site root.
2. List the language codes. One per line: en, de, ja, pt-BR, zh-Hant. If a version does not follow the pattern — English at the root, say — add its path after the code: en /pricing/. A full URL or a custom segment works the same way.
3. Choose the x-default. Pick which version searchers get when none of the languages matches. It is normally the root or the English page. Skipping it is allowed but the generator warns, because a set without x-default leaves that decision to the search engine.
4. Copy both blocks. Paste the head block, unchanged, into the head of every version — each page must list all versions including itself. Paste the sitemap block into sitemap.xml, inside a urlset that declares the xhtml namespace. Either channel is enough on its own; keeping both is fine as long as they agree.

Why hreflang matters — and why the set must be reciprocal

hreflang is an attribute on a link element that tells search engines which language, and optionally which region, each alternate version of a page is written for. Without it, a German searcher can land on your English page while the German one sits unindexed as a near-duplicate; with it, Google swaps in the right version and consolidates signals across the group instead of splitting them.

The rule that trips most sites is reciprocity. Every version must list every other version and itself. If page A points to page B but B does not point back to A, Google treats the annotation as untrusted and drops it — for that pair, not just for one side. Hand-maintained sets drift the moment a language is added, which is why this generator writes the full set from one pattern and gives you one block to paste everywhere, rather than a per-page snippet you would have to keep aligned.

The same derivation builds the hreflang sets on clize.ai itself: the sitemap and every language page are generated from one inventory of locale prefixes, so a page cannot claim an alternate that the sitemap disagrees with.

Canonical tags and hreflang together

Each language version must carry a self-referencing canonical: <link rel="canonical" href="https://example.com/de/pricing/"> on the German page, pointing at the German page. The canonical is the one tag in the head that differs per version, which is why it is not part of the shared block above — write it per page, and never point it at another language version. A German page whose canonical says the English URL is telling Google to index the English one instead, and the hreflang set is then ignored for that page.

The other two requirements are equally mechanical: every URL in the set must return 200 and be indexable — no redirects, no noindex — and the URLs must be absolute, including scheme and host. The generator only ever emits absolute URLs; the redirect and index status you can check with a crawl or, for your own domain, with clize seo check, which lists each page's live HTTP status and Google index state at no cost.

Language and region codes

hreflang values are ISO 639-1 language codes (two letters: en, de, ja), optionally followed by an ISO 15924 script (zh-Hant, zh-Hans) and an ISO 3166-1 Alpha-2 region (en-GB, pt-BR, es-MX). The language part is mandatory; a region on its own (gb) is invalid, and a common trap is uk, which means Ukrainian, not the United Kingdom. Regions may also be UN M.49 numeric areas, so es-419 for Latin-American Spanish is valid.

The generator normalizes what it can — pt_br becomes pt-BR, zh-hant becomes zh-Hant — and warns rather than blocks on a language it does not recognize, because the list of accepted codes is finite and yours might be a typo or a genuinely rare language. Read the warning before you publish. Codes and URLs are two different things: the URL segment is lowercase by default (/pt-br/), and you can override it per line if your site uses something else.

Common hreflang mistakes

• Missing return links. A points to B, B does not point to A. The pair is discarded. Paste the same complete block into every version.
• No self-reference. Each page must include itself in the set. The generated block already does.
• Canonical pointing at another language. That page drops out of the set. Self-referencing canonical on every version.
• Relative URLs. hreflang needs absolute URLs with scheme and host. The generator emits nothing else.
• Country code instead of language code. gb, us or uk — write en-GB, en-US, and remember uk is Ukrainian.
• Redirected or noindexed members. Every URL in the set must be a live, indexable 200.
• Tags in the head and a different set in the sitemap. Pick one channel, or generate both from the same source — as here.

If the pages you are linking also carry an FAQ, the same one-source rule applies to its markup: the FAQ schema generator writes the JSON-LD and the visible HTML from one list. And if you publish an llms.txt for agents, run it through the llms.txt validator — a relative link there is the same class of mistake as a relative hreflang here.

$ npm i -g @clize/clize && clize install
$ clize seo check --domain yourdomain.com