Hreflang Audit Template

SEO Migration Toolkit, template 6 of 6

Hreflang Audit Template

Validate every hreflang relationship: alternate status, self-reference, return tags, canonical match and locale codes.

Which hreflang relationships pass every check and which need fixing, with the number of failed checks per alternate.

  • Excel workbook (.xlsx), opens in Google Sheets
  • PDF field guide, 9 to 11 pages
  • Blank and worked CSV templates
  • DataForSEO import script

Free, no email required. Version 3.0, updated November 2026.

Hreflang Audit Template.xlsx
M13fx=IF(K13="","",IF(K13<>"Ready","n.a.",IF(L13=0,"Meets listed checks","Fix relationship")))

Start HereDashboardWorkspaceDelivery QAField Guide

The formula above is the real one from cell M13. Scroll it sideways to read the whole rule.

Connected to the DataForSEO API

This template is designed around one DataForSEO endpoint. Pull the data, convert it with one command, and the workbook does the rest.

Setup steps

DataForSEO On-Page APIA crawl of your site: URLs, status codes, canonicals, inlinks and sitemap membershipon_page/task_post

Save the JSON responseThe full API response, kept as your source of truth.response.json

Run the import scriptOffline. No API calls, no credentials.dataforseo_import.py import --template 12 --csv

Paste at A13Dashboard, checks and action list update instantly.Hreflang Audit Template.xlsx

Column map for this template:Filled by the APIAudit trail (automatic)You add

Page URLLocale codeAlternate URLAlternate statusSelf-reference verifiedReciprocal verifiedCanonical alignedLocale validEvidenceSource reference
2 of 10 input columns come straight from DataForSEO

What the hreflang audit template decides

Hreflang has a reputation for being fragile, and it earns it. One missing return tag, one alternate that 404s, or one 'en-uk' instead of 'en-gb' and Google ignores the annotation for that pair. Large international sites can have thousands of these relationships, and they break quietly.

This hreflang audit template checks each URL and alternate pair for five conditions: the alternate returns 200, the page references itself, the alternate links back (reciprocal), the canonicals agree, and the locale code is valid. It counts failed checks and marks each relationship Meets listed checks or Fix relationship.

Who it's for

  • International SEOs managing multiple locales
  • Developers implementing hreflang in templates or sitemaps
  • Teams launching a new market or language
  • Migrations that change international URL structure

Where it fits in your workflow

The hreflang audit template answers one question. These three templates answer the questions around it:

  • Indexability Audit Template: which pages that should be indexed have a technical conflict, which are technically fine but still not indexed, and which were never meant to be indexed.
  • XML Sitemap Audit Template: which URLs should be removed from your XML sitemap (or fixed), which eligible URLs are missing from it, and which are fine.
  • Redirect Mapping Template: whether each planned redirect actually reaches the approved destination in one permanent hop, on an indexable page whose canonical agrees, with a human sign-off.

What's inside the download

One ZIP with the workbook, a 10-column input template (blank and filled), the PDF field guide and an offline script that converts saved DataForSEO responses into the input CSV. The workbook has five tabs.

Workspace. The working table. 10 input columns, 3 calculated columns, room for 250 rows. Dropdowns, Yes/No fields and range checks catch bad inputs as you paste.
Start Here. What it decides, a four-step setup and the colour key.
Dashboard. KPI cards, charts, a ranked Top 10 and an automatic action list.
Delivery QA. Pass, fail or exclude each validation step with evidence, owner and date.
Field Guide. Every field explained, plus each formula in plain English.

How the hreflang checker calculation works

Failed checks = 1 if the alternate isn't 200, plus 1 for each of: missing self-reference, missing return tag, canonical mismatch, invalid locale. Zero failures = Meets listed checks.

The key formula, exactly as it appears in the workbook

=IF(K13="","",IF(K13<>"Ready","n.a.",IF(L13=0,"Meets listed checks","Fix relationship")))
Result column Plain-English formula What it tells you
Failed checks IF(Alternate status=200,0,1)+(1-Self-reference verified)+(1-Reciprocal verified)+(1-Canonical aligned)+(1-Locale valid) Count of the five reviewed acceptance checks that fail.
Hreflang review IF(Failed checks=0,"Meets listed checks","Fix relationship") Evidence-backed QA status for this directed page pair.

The results you will see

Meets listed checksFix relationship

Green meets the checks, red needs fixing first, amber needs a human decision and blue marks an opportunity. Rows with missing or out-of-range inputs are held back in the Input check column until they're fixed, so a half-filled row never sneaks into a total.

How to use the hreflang audit template

  1. Export hreflang annotationsCrawl your site and export each page with its declared alternates and locale codes, from HTML, headers or sitemaps.
  2. Add one row per relationshipEach row is one page and one alternate, with the alternate's status code.
  3. Score the five checksMark self-reference, reciprocal, canonical match and locale valid as 1 or 0. Use the dropdown for common codes.
  4. Fix by patternFailures usually repeat by template or locale. Fix the template, then re-crawl.

The worked example in the Workspace tab. Clear the lime input cells, paste your CSV at A13 (values only) and every result recalculates.

Fill the hreflang audit template with DataForSEO

Every template in this library is built to run on DataForSEO data. This one uses DataForSEO On-Page API: a crawl of your site: URLs, status codes, canonicals, inlinks and sitemap membership.

This is a sign-off workflow. DataForSEO responses are the evidence you attach; the human checks stay manual by design.

  1. Request the dataSend this request with your DataForSEO API login (HTTP Basic auth).
    POST https://api.dataforseo.com/v3/on_page/task_post [ { "target": "yourdomain.com", "max_crawl_pages": 1000 } ]

    Post the crawl task, wait for it to finish, then request on_page/pages with {"id": "<task id>", "limit": 1000} and save that response.

  2. Save the full JSON responseSave the complete response, not just the task ID, next to the template folder.
  3. Convert it with the included scriptIt runs offline, makes no API calls and never sees your credentials.
    python3 Automation/dataforseo_import.py import --template 12 --csv --input my-filled.csv --output my-inputs.csv
  4. Add what the API can't knowLocale code, Alternate URL, Alternate status, Self-reference verified, Reciprocal verified, Canonical aligned, Locale valid, Evidence
  5. Paste at A13Clear the demo rows, paste the CSV values at Workspace cell A13 and the dashboard updates.
Fills automatically from DataForSEO You add
Page URL Locale code, Alternate URL, Alternate status, Self-reference verified, Reciprocal verified, Canonical aligned, Locale valid, Evidence

Source reference fills automatically with the task ID, endpoint, location, language, device and snapshot time, so every row is traceable. Before a big pull, estimate the cost with the DataForSEO pricing calculator. The same steps, plus an example request file, are in the download's Automation folder.

Worked example: Northbeam Outdoor

Every template ships filled with data from Northbeam Outdoor, a fictional outdoor-gear retailer that appears across all 40 workbooks, so you can see what useful output looks like before you add your own. This workbook has 15 example rows.

15Records
0Rows with input issues
5Failed relationship checks
10Relationships passing

Five of 15 example relationships fail, and they fail in the classic ways: a German page missing its return tag, a UK URL that was renamed and now 404s, a French canonical pointing to English, and the invalid code en-uk.

Top 10 by failed checks

# Page URL Failed checks
1 https://www.northbeam.example/jackets/rain/womens/ 1
2 https://www.northbeam.example/jackets/rain/womens/ 1
3 https://www.northbeam.example/tents/backpacking/ 1
4 https://www.northbeam.example/tents/backpacking/ 1
5 https://www.northbeam.example/hiking-boots/womens/ 1

Input fields

Keep the columns in this order when you prepare a CSV. A missing observation stays blank; use 0 only for a measured zero or a verified No. Fields marked DataForSEO can be filled automatically by the included script.

CSV field Column Meaning and rule Source
url Page URL Exact absolute URL. Keep case and query parameters unless a documented normalization rule applies. DataForSEO: url
locale Locale code Language or language-region code reviewed against the implementation spec. Your records
alternate_url Alternate URL Absolute alternate URL extracted from hreflang markup. Your records
alternate_status Alternate status HTTP response at the alternate URL. Your records
self_reference Self-reference verified 1 when the page includes the required self-reference. 1 = Yes, 0 = No. Your records
reciprocal Reciprocal verified 1 after checking the alternate links back to this page. 1 = Yes, 0 = No. Your records
canonical_match Canonical aligned 1 after verifying canonical choices do not conflict with the hreflang relationship. 1 = Yes, 0 = No. Your records
locale_valid Locale valid 1 only after validating the actual locale code and page language. 1 = Yes, 0 = No. Your records
evidence Evidence Link to a dated crawl, screenshot, ticket or source that another reviewer can inspect. Your records
source_ref Source reference Task ID, export filename and observation scope. Retain the untouched source response separately. Optional. DataForSEO: source_ref

Reading the result honestly

Use one row per directed alternate relationship. Validate every member of a locale cluster.

Limits. The starter importer enriches page URLs. It does not extract or infer hreflang tags, return links or language correctness.

Hreflang checker mistakes to avoid

Using en-ukThe ISO region code for the United Kingdom is GB. en-uk is invalid and ignored.
Canonicalizing every locale to one versionIf the French page canonicals to English, Google drops the French page and its hreflang.
Forgetting x-defaultx-default tells Google which page to show when no locale matches. It's optional but recommended.

Tips from practice

  • Pick one implementation method (HTML, header or sitemap) per page type; mixing causes conflicts.
  • Validate after every locale launch, not just once.
  • Include hreflang checks in the migration checklist.

Frequently asked questions

What are hreflang return tags?

Each page in a hreflang set must link to every alternate, and each alternate must link back. Without the return link, Google may ignore the pair.

What is the correct hreflang code for the UK?

en-gb. Language codes are ISO 639-1 and region codes are ISO 3166-1 Alpha 2.

Does hreflang need a self-referencing tag?

Yes. Each page should include itself in its own hreflang set.

Is hreflang a ranking factor?

No. It helps Google show the right language or regional version; it doesn't boost rankings on its own.

Part of the SEO Migration Toolkit

Get all 6 SEO Migration templates in one ZIP, or the complete set of 40 SEO and GEO templates with the 401-page field handbook.

Download the SEO Migration Toolkit

See the complete SEO & GEO toolkit

Jourdan Rombough

Built by Jourdan Rombough, technical SEO and GEO consultant with 15+ years in search. About Jourdan or get an SEO plan.

More on digital marketing in our blog

See all posts