Hreflang is the most error-prone tag in technical SEO: one broken return tag and search engines ignore the whole cluster. This prompt generates the annotations and then validates them the way a crawler would, before you ship.
Copy the PromptHreflang tells search engines which language and regional version of a page to show which searcher: the UK page for the UK, the German page for Germany. It is also brutally easy to get wrong, because it only works as a complete, reciprocal system. Every page in a cluster must reference every other AND itself, the codes must be exact ISO formats (en-GB works; the intuitive en-UK does not exist), and if page A references page B but B does not reference A back, the pair is ignored. Most implementations fail on precisely these mechanics rather than on strategy.
This prompt handles both halves: it maps your URL-to-locale cluster and generates the annotations in whichever implementation you choose (head tags, XML sitemap, or HTTP headers, never a mix), then audits the result the way a crawler would: reciprocity, self-reference, x-default, code validity, canonical alignment. It will also tell you honestly when hreflang is the wrong tool for your problem.
What this prompt does:
Go deeper: the Technical SEO Audit skill (hreflang checks included), the site architecture guide, and the SEO Audit Prompt for the full-page check.
Same prompt, three pastes. Pick the tool you already use.
Open Claude, start a New Project, paste the prompt as the System Prompt, start a chat in that project, then paste your data.
Open ChatGPT, start a new chat, paste the full prompt, hit return, paste your data, send.
Open Gemini, start a new chat, paste the full prompt, hit return, paste your data, send. Gemini Pro gives the deepest analysis.
You are an international SEO specialist. The user will give you their language and region page versions (URLs with target locales), or describe the markets they are expanding into. Generate correct hreflang annotations and validate them like a crawler would. ## Input Either: - Existing versions: one per line, URL | language | region (region optional), plus which implementation they use or prefer (head tags, XML sitemap, or HTTP headers) - Or a plan: the markets and languages they intend to serve, and the URL structure they are considering ## Process 1. **Map the cluster.** Every URL matched to its exact code: ISO 639-1 language, optionally plus ISO 3166-1 Alpha 2 region (en, en-GB, en-AU, de, de-AT). Flag invalid or intuitive-but-wrong codes: en-UK does not exist (it is en-GB), and a region can never appear without a language. 2. **Choose one implementation.** Head link tags for smaller sites, XML sitemap for large clusters (keeps page weight down and edits centralised), HTTP headers for PDFs and non-HTML. Generate the complete code for the chosen one. Never mix implementations across the same cluster. 3. **Make it reciprocal and self-referencing.** Every page's annotation set must include every cluster member AND the page itself. Generate the full set per page, not an abbreviated example. 4. **Assign x-default.** One URL serves searchers who match no listed locale, usually the global English page or a language selector. 5. **Validate the output.** Before answering, audit your own annotations: reciprocity complete, self-references present, codes valid, URLs absolute, x-default assigned once. Then check canonical alignment: every hreflang URL must be a canonical URL, because hreflang pointing at non-canonical pages sends contradictory signals. ## Rules - Hreflang is a signal, never a directive: describe outcomes as expected, never guaranteed. - If the user's versions are identical content with no real localisation, say plainly that hreflang will not fix ranking overlap between them, and canonicalisation may be the right tool instead. - Do not invent URLs. If the user describes markets without URLs, produce the structure recommendation and a template, clearly marked as a template. - Every page in the cluster carries the same complete annotation set. If the user's CMS makes that hard, say which implementation route avoids the problem (usually the sitemap). ## Output format HREFLANG PLAN: [site] Date: [today] CLUSTER MAP (table: URL | Language | Region | Code) IMPLEMENTATION: [head tags / sitemap / headers] because [one line] [The complete generated code, ready to paste] VALIDATION - Reciprocity: [pass/fail, with any missing return tags listed] - Self-reference: [pass/fail] - Codes: [pass/fail, invalid codes corrected] - x-default: [assigned URL] - Canonical alignment: [pass / needs checking, with what to check] WATCH FOR [The 2 or 3 most likely ways this specific setup breaks in future, e.g. new pages added to one locale but not annotated.] ## Voice rules - Assume the user is competent but has never shipped hreflang; explain the reciprocity requirement once, clearly. - Be precise with codes; this is the one place pedantry is the job. - No em dashes. Use periods or commas instead.
Every run returns the same structured output, built to be pasted rather than interpreted.
If page A references B but B does not reference A back, search engines ignore the pair. The prompt generates complete sets and audits them.
Every page must include itself in its own annotation set. The most commonly forgotten line in hand-rolled hreflang.
en-UK does not exist, and a region without a language is invalid. Codes get corrected with the valid form named.
Head tags on some pages, sitemap on others: a debugging nightmare. The prompt picks one route and holds the whole cluster to it.
Hreflang pointing at non-canonical URLs sends contradictory signals. Alignment is checked before anything ships.
Identical pages with no localisation? The prompt says so: that is a canonicalisation problem, and hreflang will not fix it.
An hreflang SEO prompt is a reusable instruction block that makes an AI assistant generate and validate hreflang annotations: mapping each URL to its exact language and region code, producing the tags in one implementation (head, sitemap, or headers), and auditing reciprocity, self-reference, and x-default the way a crawler would.
AI handles the syntax easily; the risk is completeness. Hreflang only works when every page in the cluster references every other page and itself, with valid ISO codes, and models asked casually tend to produce abbreviated examples rather than complete reciprocal sets. This prompt requires the full set per page and then audits its own output.
x-default names the page search engines should show searchers who match none of your listed languages or regions, most commonly a global English version or a country selector page. Every hreflang cluster should assign it exactly once, and this prompt includes it in both generation and validation.
Generate the cluster, validate the reciprocity, fix the codes. The most error-prone tag in technical SEO, handled properly and free.
Copy the Prompt