The Hreflang Generator does not validate every language code that a search engine recognizes; it validates the structural shape, casing, and combinatoric rules of a language tag, then leaves registry coverage and content fit to the publisher. That distinction matters because a tag produced by the tool can still reference an unsupported, deprecated, or audience-mismatched locale even when it is perfectly formatted HTML. The tool calls Intl.getCanonicalLocales to canonicalize casing, rejects duplicate locale values case-insensitively after normalization, and treats x-default as a fallback token instead of a language. It accepts a two-letter language, an optional four-letter script, and an optional two-letter region, but it never reaches out to a registry like ISO 639 or to a search engine's current locale table to confirm that a given code is actually served. Confirming that last layer, registry support plus audience fit, is a job that lives with the publisher, which is why the tool's own FAQ entry on supported codes is a clear "no, verify separately." Once you cross-check on your side, the generator's structural checks are usually enough to keep your hreflang set tidy, internally consistent, and ready to paste into every localized page head.
Shape and Casing: The Generator's Validation Layer
At its core, the Hreflang Generator performs six categories of structural check on every locale row you paste in. Understanding these checks explains what kind of validity you can trust from the output and what you still have to verify on your side.
First, it tests the language tag against a conservative BCP 47 shape: a two-letter language subtag, an optional four-letter script subtag, and an optional two-letter region subtag. A country code such as US or CA cannot stand alone in the first position; the leading subtag must always identify a language, with regional targeting attached after it (for example, fr-CA). Generic-language rows such as fr remain valid as fallbacks when several country-specific French versions exist.
Second, it canonicalizes casing through Intl.getCanonicalLocales, which means en-us becomes en-US and zh-hant becomes zh-Hant. This mirrors how browsers read accept-language signals, so your head tags stay aligned with the casing crawlers expect in HTTP requests.
Third, duplicate locale values are rejected case-insensitively after normalization. Two rows that differ only in casing, en-US and en-us, collapse to the same canonical form and are reported as a single conflict, forcing you to remove the duplicate rather than ship two entries that describe the same target.
Fourth, x-default is handled explicitly as a fallback token rather than as a language. Only one x-default row is allowed per set, and the value is never rewritten, never lowercased, and never paired with a script or region subtag. It points at a page that should serve users whose settings match no other alternate, such as a country selector or generic landing page.
Fifth, each URL is normalized by the browser's URL parser: fragments are stripped, credentials are rejected, and only fully qualified HTTP or HTTPS addresses with an explicit host pass the input stage. Scheme-relative strings like //example.com/en/ and relative paths like /en/about are refused outright, alongside any URL that includes user:pass@ or a #fragment tail.
Sixth, attribute-sensitive characters in the generated HTML are escaped so the block parses cleanly when pasted into a head element. Ampersands in URLs become &, and quotes inside attribute values are entity-encoded, which is why the tool's tests assert exact HTML escaping alongside locale and URL rules.
What the Generator Does Not Check for You
Equally important is what the generator does not pretend to do. It does not look up the canonical ISO list of languages, it does not query Google or Bing's current "supported languages" documentation, and it does not connect to your site to fetch any live page. The tool's own FAQ entry puts this plainly:
"No. It validates a conservative tag shape and casing; verify registry support and content targeting separately."
Three layers of meaning remain entirely outside the validation step:
- Registry coverage. Search engines maintain their own evolving list of supported language and region codes. BCP 47 grammar accepts many more codes than any one search engine actively serves, so a tag the tool accepts can still be unused, deprecated, or absent from a particular engine's locale table.
- Audience fit. The tag tells crawlers which user the page is for, but the page itself has to be written, translated, and structured for that audience. A pt-BR tag pointing at Portuguese-from-Portugal content will look structurally perfect and audience-mismatched at the same time.
- Live equivalence. The generator cannot prove that two URLs actually host equivalent content, nor that the alternate pages return a 200 status. Reciprocal verification and crawl-time checks stay as deployment tasks, not generator tasks.
Tag Shape Rules the Generator Enforces
The standards-aligned fixtures inside the generator map cleanly onto common real-world locale forms. The table below summarizes each pattern, the input row that triggers it, the canonical output, and the most common pitfall that the structural check cannot catch for you.
| Locale form | Example input row | Canonical output subtag | What it targets | Most common pitfall |
|---|---|---|---|---|
| Generic language | fr | https://example.com/fr/ | fr | French-speaking users regardless of country | Picking a generic tag when country-specific French versions already exist in the set |
| Language plus region | en-us | https://example.com/en-us/ | en-US | English in the United States after casing fix | Lowercasing US in head tags by hand breaks canonical form |
| Script subtag | zh-hant | https://example.com/zh-hant/ | zh-Hant | Traditional Chinese characters | Mixing zh-Hant with simplified-Chinese pages |
| Language-script-region | sr-latn-rs | https://example.com/sr-latn-rs/ | sr-Latn-RS | Serbian written in Latin script, Serbia region | Wrong script subtag for a Cyrillic audience |
| Fallback token | x-default | https://example.com/ | x-default | Users whose settings match no other alternate | Adding x-default as a second language by mistake |
Each row above represents a shape the generator will accept. What it cannot tell you from these rows is whether your audience actually fits the targeted language and region, which is the registry-and-content gap covered in the next section.
How to Confirm Each Locale Beyond the Tool
Because the generator deliberately stops at shape and casing, you need a short, repeatable workflow on your side to confirm that every locale you ship is both supported and appropriate for your audience. The steps below sit on top of the generator; you produce your tag block with it and then run these checks before deployment.
- Inventory every localized page first. List each locale you genuinely publish, including the page you are currently editing, and decide whether a single x-default fallback exists. Single-language sites do not need hreflang at all, and there is no value in introducing an alternate set you cannot keep complete and synchronized.
- Open the current Google localized versions documentation. Search engines publish and update their supported language and region lists. Per the Google localized versions guide, cross-reference every locale in your set against that list and remove any code that does not appear there or is marked deprecated.
- Check audience analytics for the actual country and language mix. Real user data beats regional assumptions. If your analytics show that Brazilian users land on a Portugal-Portuguese template, the tag mismatch is structural, not just cosmetic, and the row needs to be revised before the generator ever sees it.
- Spot-check rarer codes against ISO and UN registries. Less common language tags (sr-Latn-RS, zh-Hant, regional African codes) benefit from a second pass against an external registry, because some search engines list only a subset and you want to know which codes are real before relying on them.
- Re-enter the audited rows into the generator. Once each code has cleared the support and audience checks, paste the cleaned list back into the tool, regenerate the tag block, and treat that regenerated block as the canonical source for every page head in the cluster.
Where Valid-Shaped Tags Still Fail in Practice
Even after the generator's structural checks pass, several failure modes remain common in production hreflang deployments. Spotting them early saves the time of a full re-roll and re-crawl once the cluster is already live.
- Unsupported or invented codes. Codes that pass BCP 47 shape can still be deprecated, made up, or simply absent from a search engine's served list. A structurally correct subtag is not, by itself, evidence that any engine will use it as a target language.
- Audience mismatch despite perfect casing. A French-from-France page tagged fr-CA is syntactically valid and semantically wrong. The tag block does not translate content, detect language, or guarantee that any particular result will appear; Google may still algorithmically identify the page and override the declared relationship.
- x-default used as a language. Adding two x-default rows, or tagging one page x-default and another as a regular language with identical content, breaks the fallback contract search engines document. x-default identifies a page intended for unmatched users, never a language.
- Mixing implementation methods. Keeping hreflang in HTML head, HTTP headers, and the XML sitemap at the same time is allowed, but only if the sets stay identical. Drift across those three places is one of the most common reasons a structurally valid tag block silently stops being trusted.
Build the Tag Set and Cross-Check It
Once every locale row has cleared the audience and registry checks, run them through the Hreflang Generator one final time and treat the output as the canonical block. Two follow-up habits keep the set honest after deployment: keep the row format consistent against a written cheat sheet so each re-roll matches the prior set, and audit the live HTML for accuracy with a separate post-deploy check that crawls a sample from every language cluster. The generator gives you a structurally valid, head-ready block; the surrounding workflow is what makes that block correct in the broader sense of registry support, audience fit, and reciprocal return links.