Hreflang audit

hreflang-audit — discovery skill (GAP-T1, FREE)

hreflang / i18n governance per rules/tech-seo-governance.md R-125 (Cluster Reciprocity), R-126 (Code & x-default Validity), R-127 (Locale Consistency, config ↔ site). Computes the reciprocity graph from hreflang_all.csv, validates codes + x-default, and joins return targets against internal_all indexability + canonicals_all — deeper, computed findings than SF's Issues-Overview "you have hreflang issues" (which already routes to the same robots_txt sheet via sf_issue_taxonomy keyword hreflang; no taxonomy change).

Single-language portfolio reality. The entire current portfolio is single-language (tr-TR / en-CA / en-NG). With zero hreflang annotations the audit returns verdict: NOT_APPLICABLE with empty findings and a rendered report — absence of hreflang is correct, not a defect. The skill fully validates clusters the moment a multi-language client signs.

Recommendation-only. The engine emits findings (master.xlsx#robots_txt, HF- prefix) + a report; the operator fixes the site (the engine has no <head>/sitemap write access and ships no hreflang generator — there is no multi-language client yet). The Excel write is behind the standard request_approval gate. No paid MCP (GSC index_inspect is optional spot-check only; there is no GSC hreflang surface).

Outputs

• master.xlsx#robots_txt — HF-NNN findings (5-col: id/level/issue/detail/ resolution; level is severityEnum). Written via scripts/util/sheet_merge.merge_prefixed_rows(..., id_prefix="HF-") — idempotent re-runs, preserves sf_projection R-NNN and facet-nav FN- / robots-policy RP- rows. sf-import's transaction.replace wipes the sheet → re-run hreflang-audit after every sf-import (it is free and reads the same export dir).
• outputs/reports/{date}-hreflang-audit.md — verdict + cluster count + findings table (+ a NOT_APPLICABLE note on single-language sites).
• events.jsonl — append_provenance(source.kind="sf_csv", operation="project_excel", target_excel_sheet="robots_txt").

Body protocol

Mirrors tech-audit's shape minus the budget pre-flight (this skill is free).

1. create_run — workflow_runner.create_run(skill="hreflang-audit", ...).
2. read inputs — resolve latest sf-exports/{date}/raw/; read hreflang_all.csv (page Address + HTML hreflang N / HTML hreflang N URL columns), canonicals_all.csv, internal_all.csv (Indexability + Status + Canonical); read project.config.json[language.content_locale].
3. transform (pure) —

   from scripts.discovery import hreflang_audit_transform as hat
   out = hat.transform(hreflang_rows, canonical_rows, internal_rows, content_locale)
   

   Computes reciprocity (R-125), validates codes + x-default (R-126), checks config↔site locale consistency (R-127); joins return targets against indexability/canonical/status. Zero annotations + single locale → verdict: NOT_APPLICABLE, empty rows. The code validator is permissive (never RED on an exotic-but-valid code like zh-Hant-TW) but flags the documented uk→gb region mistake.
4. request_approval — request_approval(...) ("N hreflang finding'i master.xlsx#robots_txt'ye yazalım mı?"); skill EXIT awaiting_approval.
5. write_excel — on approve, sheet_merge.merge_prefixed_rows(master_xlsx, "robots_txt", out["robots_txt_rows"], id_prefix="HF-", run_id=..., project_slug=..., writer="hreflang-audit") (single idempotent committer.commit path).
6. render_report — render_template.py templates/reports/hreflang-audit.template.md → outputs/reports/{date}-hreflang-audit.md.
7. provenance event — append_provenance(source.kind="sf_csv", operation="project_excel", target_excel_sheet="robots_txt", rows_written=len(rows)).
8. complete — workflow_runner.complete(...) with string-typed outputs.

Optional live SF mode

Mirror tech-audit's use_sf_mcp_live branch (mcp__sf__sf_list_crawls → sf_load_crawl → sf_export_seo_element_urls for the Hreflang element) to source hreflang_all live; AMBER fallback to file-based on any SF MCP error (never hard fail). Default: file-based.

DURUR conditions

Stop and flag the manager — do not patch, do not fabricate.

1. hreflang_all.csv missing — run sf-import first (or use live SF mode).
2. hreflang_all.csv has rows but no recognisable HTML hreflang N columns (HreflangSchemaDriftError) — re-export with default data_fields or use live mode.
3. master.xlsx#robots_txt row schema mismatch on write (RowSchemaError).
4. PSEO_WORKSPACE_ROOT unset and no workspace_root arg.

NOT a DURUR: zero hreflang on a single-language site → NOT_APPLICABLE verdict with an empty finding set and a rendered report (the designed portfolio-wide hygiene pass).

Cross-references

• Rules: rules/tech-seo-governance.md (R-125 / R-126 / R-127).
• Transform: scripts/discovery/hreflang_audit_transform.py (transform, HreflangAuditError, HreflangSchemaDriftError).
• Write path: scripts/util/sheet_merge.py (merge_prefixed_rows, prefix HF-).
• Schemas: schemas/master-excel.schema.json#robots_txt (5-col + severityEnum), schemas/events.schema.json.
• Template: templates/reports/hreflang-audit.template.md.
• Command: commands/pseo-hreflang-audit.md.
• Open question (report it, do not build): no language.alternates array exists in project-config.schema.json yet — defer until a real multi-language client signs.

Discipline checklist

• Recommendation-only — engine never deploys; ships no hreflang generator (R-125).
• Free — budget.uses_paid_mcp=false; no DFS; GSC index_inspect optional spot-check only.
• Single-language PASS-trivial — zero hreflang + single locale → NOT_APPLICABLE (R-126).
• Permissive codes — never RED on exotic-but-valid (zh-Hant-TW); flags documented uk→gb mistake (R-126).
• Schema-first — frontmatter validates; HF- rows validate against master-excel.schema.json#robots_txt.
• Plugin-agnostik — no slug literals; pure transform.
• Idempotent write — merge_prefixed_rows re-lands the HF- namespace; foreign R-/FN-/RP- rows preserved.
• Append-only — provenance via events_writer.