Synthetic teaching example. All URLs, observations and results below are fictional. The offline tool sends nothing and does not alter your website.
A language button is not a complete handover test
Before accepting a bilingual website, select two pages that genuinely cover the same topic. Ask the supplier for each page's recorded language references, rather than only a screenshot of a working language button. This resource turns that small acceptance task into a repeatable, four-link test.
A site owner asked about a language annotation error in a Google community question dated 6 August 2021. That is historical problem evidence, not current search volume or a description of today's Search Console interface. The current official documentation, not old forum advice, supplies the requirements used here.
A filled pair with one missing return
Our fictional Australian business has https://example.test/en/proposal/ and https://example.test/zh/proposal/. The reviewer approves them as corresponding English and simplified Chinese pages, labelled en-AU and zh-Hans-AU. Each synthetic observation records 200 and 15 October 2026 at 05:00 UTC. Neither address is a real client site.
| Recorded page | Reference | Broken example | Corrected example |
|---|---|---|---|
| English proposal | en-AU → English proposal | Present | Present |
| English proposal | zh-Hans-AU → Chinese proposal | Present | Present |
| Chinese proposal | en-AU → English proposal | Missing | Present |
| Chinese proposal | zh-Hans-AU → Chinese proposal | Present | Present |
The broken input reports zh-Hans-AU:en-AU:missing-or-duplicate. It identifies one absent return relationship, not a need to create another service page. The corrected input adds that record and returns CONSISTENT. The example does not show any production repair or change to Google results.
Run the same check locally
Download the checker, broken input and corrected input. With Node 22.13 or newer, keep the three files together and run:
node hreflang-edge-check.mjs --test node hreflang-edge-check.mjs broken.json node hreflang-edge-check.mjs corrected.json
Fifteen tests cover self-links, returns, relative addresses, wrong counterparts, duplicates, missing observations, response status, case-insensitive labels and malformed records. MISMATCH means an observation differs from the agreed model; BLOCKED means required evidence or a supported input is missing. The printed state, rather than the shell exit code, is the result: this teaching CLI is not a ready-made CI release gate.
The tool reads supplied JSON, not HTML or DNS. Its two-language model accepts only en-AU and zh-Hans-AU, does not validate a general language-code registry, and does not infer the correct translation. The reviewer must establish the intended pair first. A fully populated but incorrectly approved counterpart map can still pass.
What the official rules support
Google's localized versions guidance, checked 15 October 2026, calls for each version to reference itself and its counterparts with full URLs and return relationships. HTML, HTTP headers and sitemaps are alternative implementations; doing all three is not a bonus. x-default is an optional fallback, not a mandatory third language in this example.
Our exactly-two-page scope, JSON input, 200-response acceptance rule and error names are teaching choices, not Google requirements or an indexing test. Reachability, redirects, canonical choices, robots rules, translated body quality and Google's interpretation require separate evidence. An annotation cannot certify the language of the body or guarantee ranking.
Return a bounded acceptance record
- Approve one same-topic pair and identify the implementation being inspected: HTML, headers or sitemap.
- Keep a timestamped source capture and the four observed relationships. Preserve unknowns rather than inventing a successful response.
- Record the precise failing relationship, its responsible implementation owner and a staging retest. Do not rewrite unrelated pages.
- Review discoverability and the actual bilingual user journey separately. The form acceptance demonstration covers a different task: errors and simulated receiving states, not language annotations.
Bring a redacted counterpart map and original source capture to a bilingual website discussion. No passwords or customer submissions are needed. A passing offline record is not evidence of indexing, AI recommendations, an enquiry or a sale.