Skip to content
Plumb
Light theme onCheck a URL

DocsInternational SEO

hreflang Tags Tester

Check the hreflang annotations of one page or several, from their HTML and HTTP Link header, or every annotation in your XML sitemaps: codes, return links, self-references, x-default and the whole cluster.
  • HTML, headers or sitemaps
  • Up to 10 pages at once
  • Cluster matrix
  • Sitemap indexes followed
  • JSON API

What it Checks

One page tests a page from its HTML and HTTP headers. The tool reads its <link rel="alternate" hreflang> tags and the hreflang entries of its Link header, then fetches every alternate URL (up to 100) and checks that it answers 200, is not redirected, canonicalised elsewhere or noindex (in a meta tag or the X-Robots-Tag header), and lists the tested page in return, with the same language code.

From those fetches it also builds the cluster: the tested page and its alternates, and for each one which versions of the set it lists, which it leaves out and which extra URLs it lists that the tested page doesn't. Every version should list the same set.

Several pages runs the same test on up to 10 URLs, such as the language versions of one page or a sample of templates. Alternates shared by several pages are fetched once.

XML sitemap(s) reads the xhtml:link annotations of every <url> in your sitemaps and checks the entries against each other: when page A lists B as an alternate, B's entry must list A, and B's entry must give itself the code A gave it.

Both modes check:

  • Codes: an ISO 639-1 language, an optional script (zh-Hant) and an optional ISO 3166-1 alpha-2 region, or x-default. Common mistakes get a specific message: an underscore (en_US), a country in place of the language, or en-UK for en-GB.
  • Duplicates: one language code pointing to several URLs.
  • Self-reference: the page must list itself.
  • x-default: reported as a note when missing; it is optional.

For tested pages, the page itself is also checked: a status other than 200, a redirect, a canonical pointing elsewhere or a noindex means its annotations won't be used.

Run a Test

  1. Choose One page, Several pages or XML sitemaps.
  2. Paste the URL (or URLs, one per line), or the sitemap URLs (one per line) or upload an .xml file. Pick the user agent.
  3. Press Test (Test pages, Test sitemaps). The verdict counts what was found, for example 8 annotations, 2 issues, 1 note., or reads No hreflang. Several pages show their progress, and can be cancelled.
Open the hreflang Tags Tester

Options

  • User agent (every mode). Sent to the pages, to every alternate, and to the sitemaps. Googlebot Smartphone is the default. Some servers refuse a Googlebot user agent that doesn't come from Google's network: when a page answers 202, 401, 403, 429 or 503, try a browser.
  • Fetch sitemaps or Upload a file (sitemap mode). Up to 20 sitemap URLs. Sitemap indexes are followed (an uploaded index too), up to 50 files in all; gzip-compressed sitemaps (.xml.gz) are unpacked. A sitemap that can't be read (an error status, an HTML page, invalid XML) is listed while the others are still tested.
  • Check the HTTP status of every URL (sitemap mode). Requests each URL and alternate, up to 500, following redirects (HEAD, or a short GET when the server refuses HEAD): a redirect is reported with its status and where it ends. Without it, sitemap mode makes no requests to your pages.

Reading the Result

  • Return links: how many alternates list the tested page, out of all alternates other than the page itself.
  • Page issues: problems with the page as a whole, marked issue, or note for a missing x-default. In sitemap mode they are grouped by kind, each with the number of URLs it concerns; open a group for the URLs. Each is counted once per URL, not once per annotation.
  • Annotations: one row per annotation, rows with problems first, with the code, URL, source (html, header or sitemap), status, return link and issues. Hover a code for the language name. not checked marks alternates beyond the first 100. The CSV and Excel exports include where redirecting alternates end.
  • Cluster (one page): up to 30 pages, a matrix with one row per page of the set and one column per URL it should list. A green cell holds the code the page uses, amber means another code than the tested page uses, a cross means the URL is missing. Under it, a table for any size: each page's code, status, number of annotations, Missing (versions of the set it doesn't list) and Extra (URLs it lists outside the set); open a row for the URLs.
  • Pages (several pages): one row per URL with its status, annotations, return links and issues. Details opens that page's full report below the table.

In sitemap mode, a return link can only be checked when the alternate URL has its own entry in the sitemaps you tested; otherwise the row says so as a note and the return link column stays empty.

Good to Know

  • Alternates must point to final, canonical, indexable URLs. A redirecting alternate is reported even when its target is correct.
  • Pages are read as HTML, without running JavaScript: hreflang tags added by scripts are not seen.
  • The full rules are in the hreflang guide; canonicals are covered in the rel="canonical" guide.

API

POST /api/hreflang

One page: send mode: "url", the URL and, optionally, the user-agent id (agent). Sitemap mode: send mode: "sitemap" with urls (sitemap URLs, one per line, up to 20) or content (the sitemap XML), and optionally checkStatus and agent. Several pages: send mode: "bulk" with urls (one per line, up to 10); the answer is a stream of JSON lines (application/x-ndjson): {"type":"progress","done":1,"total":3,"current":"…"} events, then {"type":"done","mode":"bulk","pages":[…]} with one URL-mode result per page (or {"url":…,"error":…}).

Request
curl -X POST https://plumb.reacthive.dev/api/hreflang \
  -H "content-type: application/json" \
  -d '{
    "mode": "url",
    "url": "https://www.hubspot.com/",
    "agent": "googlebot-smartphone"
  }'
Response (Trimmed)
{
  "mode": "url",
  "url": "https://www.hubspot.com/",
  "finalUrl": "https://www.hubspot.com/",
  "status": 200,
  "canonical": "https://www.hubspot.com/",
  "robots": "",
  "pageIssues": [],
  "rows": [
    {
      "hreflang": "x-default",
      "href": "https://www.hubspot.com/",
      "source": "html",
      "valid": true,
      "status": 200,
      "finalUrl": "",
      "returnLink": null,
      "self": true,
      "skipped": false,
      "issues": []
    },
    {
      "hreflang": "es",
      "href": "https://www.hubspot.es/",
      "source": "html",
      "valid": true,
      "status": 200,
      "finalUrl": "",
      "returnLink": true,
      "self": false,
      "skipped": false,
      "issues": []
    }
  ],
  "skipped": 0,
  "cluster": {
    "pages": [
      {
        "url": "https://www.hubspot.es/",
        "codes": "es",
        "status": 200,
        "fetched": true,
        "annotations": 7,
        "listsTested": true,
        "missing": [],
        "missingCount": 0,
        "extra": [],
        "extraCount": 0
      }
    ],
    "matrix": [["x-default, en", "es", "fr-FR"], ["x-default, en", "es", "fr-FR"]]
  }
}

matrix[i][j] is the code page i gives page j of cluster.pages, or null when it doesn't list it; it is null for clusters of more than 30 pages. cluster is null when the page has no annotations.

Sitemap mode answers { "mode": "sitemap", "sitemaps": [...], "sitemapErrors": [{"sitemap", "error"}], "notRead": 0, "urls": 120, "pageIssues": [{"loc", "issue"}], "rows": [...], "statusLimited": 0 }, each row with loc, hreflang, href, valid, inSitemap, returnLink, status (the first response, with checkStatus), finalUrl (where a redirect ends) and issues.