{{ summaryTitle }}
{{ summaryValue }}

{{ summaryLine }}

Method{{ methodShortLabel }} Self{{ computation.ok && values.has_self_reference ? 'present' : 'review' }} Warnings{{ computation.ok ? values.warning_count : '—' }}
Columns: locale, absolute URL, optional label. Locale-only country codes and relative URLs are not valid hreflang targets.
{{ sourceStatus || 'Drop one CSV, TSV, or TXT file onto the textarea.' }}
Auto detect resolves each non-empty row independently and reports the resolved formats in the audit.
Use one maintained method for the complete reciprocal cluster.
Use the language, language-region, or language-script tag of the page receiving this cluster.
Use a selector, global landing page, or accepted fallback for unmatched language settings.
{{ include_x_default ? 'Enabled' : 'Disabled' }}
Include the full http:// or https:// URL.
Converts underscores to hyphens and applies conventional language, script, and region casing.
{{ normalize_locale_case ? 'Enabled' : 'Disabled' }}
Ordering never changes which valid locale wins a duplicate.
Keep first protects earlier spreadsheet rows from accidental later overrides.
{{ values.artifact_text }}
{{ bar.shortLabel }}{{ bar.count }}

The chart renderer is unavailable. The same locale classifications remain in the alternate ledger.

LocaleURLLabelTypeStatusNoteCopy
{{ row.locale }}{{ row.url || '—' }}{{ row.label || '—' }}{{ row.type }}{{ row.status }}{{ row.note }}
LevelCheckDetailNext actionCopy
{{ row.level }}{{ row.check }}{{ row.detail }}{{ row.recommendation }}
Meta Tag Generator Build search and social meta tags from page facts with canonical and robots checks, preview-image warnings, and escaped copy-ready HTML.
Open Graph Tag Generator Generate Open Graph and X card tags for a public page with useful image hints, article fields, and crawler-focused review warnings.
Sitemap XML Generator Turn same-host URLs or paths into sitemap XML with normalization and exclusion checks, then review protocol limits before publishing.
Robots.txt Generator Generate a robots.txt policy with crawler-specific path rules and sitemap declarations plus import checks and warnings before publication.

Localized pages often cover the same subject for different languages, scripts, or regions. Search engines need an explicit map to understand that those URLs are alternatives rather than unrelated pages. The hreflang annotation supplies that map by pairing each destination URL with the audience it is intended to serve.

The map belongs to an equivalent-page group, not to a whole site in the abstract. A product page should point to localized versions of that product page, and an article should point to translations or regional versions of that article. Sending a locale to a homepage while the other entries point to a detailed page weakens the equivalence the cluster is meant to express.

  • Language-wide targets such as en cover a language without selecting a region.
  • Language-region targets such as en-GB distinguish a regional version when the content or offer truly differs.
  • Language-script targets such as zh-Hant distinguish writing systems.
  • x-default identifies a fallback, selector, or neutral destination for users whose language and region do not match another entry.

Every URL must be absolute, including http:// or https://. Cross-domain alternatives are allowed, but each member still needs reciprocal annotations. For HTML, every localized page should publish the same complete set and include itself. A one-way link from page A to page B is not enough if page B does not return the relationship.

Google supports three publication methods: link elements in the HTML head, Link response headers, and XML sitemap annotations. They express the same relationship, so maintaining one complete method is usually safer than maintaining several copies that can drift apart. HTTP headers are particularly useful for non-HTML resources, while sitemap annotations centralize large collections outside individual page templates.

Language tags are built from subtags separated by hyphens. Casing conventions improve readability, but case alone does not make a tag valid. The language, script, region, variants, and extensions need to be appropriate for the content and supported by the search engine consuming the annotation.

Hreflang is a targeting hint, not a redirect, translation detector, canonical declaration, or guarantee of search placement. Each destination still needs crawlable content, coherent canonical signals, and a live response at the declared URL. A tidy generated cluster can therefore be structurally useful while still failing on the published pages.

How to Use This Tool:

Prepare one row for every equivalent localized URL, choose one publication method, and use the audit to catch structural gaps before installation.

  1. Paste Locale and URL rows with a locale, absolute URL, and optional label. Choose CSV, TSV, pipe, or whitespace parsing when the delimiter is known; use automatic detection only when each row is unambiguous.
  2. Choose Publication method. Use HTML head tags for ordinary pages, XML sitemap entries for a maintained sitemap workflow, or an HTTP Link header when response headers are the chosen source.
  3. Set Current page locale to the locale of the page that will receive the cluster. The self-reference audit checks whether that exact locale remains in the emitted set.
  4. Add x-default when the site has a real selector or fallback URL. If the source rows already contain x-default, the extra value is not added.
  5. Choose whether to normalize locale casing, sort the output, and keep the first or last duplicate locale. Sorting changes presentation only; the duplicate policy decides which URL survives.
  6. Fix blocking row errors such as a missing locale, relative URL, unsupported source format, or more than 500 non-empty rows. Then review duplicate, self-reference, fallback, catchall, and unusual-locale warnings.
  7. Publish the generated set through one maintained method, install the same reciprocal mapping on every equivalent page, and run a live check after deployment.

Interpreting Results:

Cluster ready means the rows produced an artifact without the built-in audit warnings. Cluster review means the artifact exists but at least one relationship deserves attention. A ready result does not prove reciprocity, live HTTP status, indexability, canonical agreement, or language-tag validity against the current registries.

Audit cue What it establishes What to do next
Self-reference present The emitted locale set contains the selected current locale. Confirm its URL is the final URL of the page receiving the annotations.
Duplicate locale The selected first-or-last policy kept one row and skipped another. Remove the duplicate so one locale maps unambiguously to one destination.
Missing language catchall Several regional variants share a language without a language-only entry. Add a language-wide URL only when a real catchall page exists.
Unusual locale shape The value fell outside the narrow common patterns recognized by the local audit. Check the tag against Google guidance and the IANA Language Subtag Registry.
Absolute URLs passed Every emitted URL begins with HTTP or HTTPS and has a host. Still check redirects, canonical targets, HTTP status, and crawlability after publication.

Technical Details:

An hreflang cluster is a set of locale-to-URL pairs. The same logical set can be serialized as HTML link elements, a comma-separated HTTP Link header, or sitemap xhtml:link children. The serialization changes, but the destinations, audience tags, self-reference, and reciprocal relationships should not.

BCP 47 language tags can contain more than a language and two-letter region. They may include script, region, variant, extension, private-use, or registered legacy forms. The local structural audit intentionally recognizes a narrower set of common two-letter language, script, and region shapes, so a Review label is not proof that an extended tag is invalid.

Transformation Core:

Each source row follows the same parse, normalize, select, sort, and serialize path. Keeping these stages explicit makes it clear where a duplicate or malformed value changes the output.

  1. Resolve the row delimiter, then read locale, absolute URL, and any remaining text as the optional label.
  2. Optionally replace underscores with hyphens and apply conventional lowercase language, title-case script, and uppercase two-letter region casing.
  3. Add one generated x-default row only when requested and not already present.
  4. Group rows case-insensitively by locale and retain the first or last row according to the duplicate policy.
  5. Sort retained rows by input position, locale, or URL without changing which duplicate won.
  6. Escape the selected values for HTML or XML when required, then serialize the complete set through the selected publication method.

Rule Core:

Rule Exact behavior Limit
Source rows Requires at least one and accepts no more than 500 non-empty rows. Large sites should generate smaller equivalent-page clusters, not one site-wide locale list.
URL check Requires a fully qualified HTTP or HTTPS URL without whitespace. It does not fetch the URL or detect redirects, errors, canonical conflicts, or blocked indexing.
Self-reference Compares the current locale case-insensitively with retained locale rows. It does not confirm that the matching row's URL is the current page's final URL.
Duplicates Keeps one URL per locale according to the first-or-last policy and warns whenever a locale repeats. Labels do not distinguish duplicate locale targets.
Language catchall Warns when more than one regional or scripted target shares a language and no language-only row exists. A warning is guidance, not a requirement to invent a page that the site does not have.
Reciprocity Appears as a publication checklist item. No localized page is fetched, so reciprocal installation must be verified separately.

Publishing Methods:

HTML output emits one <link rel="alternate" hreflang="…" href="…" /> element per retained locale. HTTP output emits the same pairs in one Link header. Sitemap output creates one <url> entry for every retained destination and repeats the complete alternate set inside each entry, which supplies reciprocal relationships within that sitemap artifact.

Accuracy Notes:

The audit checks row structure and a focused set of common hreflang mistakes. It does not perform registry lookup or live-page validation.

  • Confirm every language, script, and region subtag against current Google support and the IANA registry. Normalized casing is not semantic validation.
  • Keep canonical URLs aligned with hreflang destinations. Each destination should resolve directly, remain crawlable, and represent equivalent content.
  • Verify the complete reciprocal set on every published page or in the maintained sitemap or header source. Mixing methods adds maintenance risk without a Google Search benefit.

Worked Examples:

Regional English pages with a fallback

Rows for en, en-GB, and ms-MY use their final absolute URLs, while x-default points to the language selector. On the en-GB page, set Current page locale to en-GB. The emitted set should contain all four destinations, the self-reference and fallback checks should pass, and the same four-pair set should appear on the other equivalent pages.

References: