hreflang-international-seo
Skill0 starsChanged 2 months agoMITView on GitHub
Set up and debug multi-language or multi-country sites — hreflang, URL structure, canonicals, geotargeting and localisation. Use whenever the user mentions hreflang, international SEO, multilingual site, multi-region, ccTLD versus subdirectory, x-default, language targeting, country targeting, translated pages, or reports that the wrong language version ranks in a market. Also use when planning to launch a site in additional languages or countries.
In this repository29 other files it gives its agents.
- ai-bot-log-analysisSkill
- ai-crawler-policySkill
- ai-visibility-auditSkill
- best-of-listicle-pagesSkill
- canonical-duplicate-contentSkill
- comparison-alternatives-pagesSkill
- content-refreshSkill
- core-web-vitalsSkill
- ecommerce-seoSkill
- eeat-author-pagesSkill
- entity-brand-consistencySkill
- featured-snippet-passagesSkill
- glossary-definition-hubSkill
- image-seoSkill
- internal-linking-architectureSkill
- keyword-cannibalizationSkill
- keyword-research-briefsSkill
- link-building-outreachSkill
- local-seoSkill
- nextjs-seoSkill
- programmatic-seoSkill
- redirect-migration-planSkill
- schema-markupSkill
- search-console-analysisSkill
- shopify-seoSkill
- technical-seo-auditSkill
- topical-authority-mapSkill
- video-seoSkill
- wordpress-seoSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 41
2. It must be reciprocal: If the English page points at the German one, the German one must point back.
- Distinctive: line 45
4. Point at canonical, indexable, 200-status URLs: Never at a redirect, a noindexed page or a 404.
- Very specific: line 74
Always include x-default. It's the version served to everyone who doesn't match, and without it Google guesses.
- Distinctive: line 93
Don't declare it in two places at once.
- Distinctive: line 106
Check every target returns 200 and self-canonicalises.
- Distinctive: line 108
Search Console's International Targeting report shows what Google has actually parsed, which is the only opinion that matters.
- Distinctive: line 126
Do the canonicals agree with the hreflang?
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
International and Hreflang
Hreflang doesn't improve rankings. It tells Google which version of a page to show to which user, and it consolidates ranking signals across versions so the set competes as one rather than as duplicates.
That's a smaller promise than it's usually sold with, and getting it wrong is worse than not having it. Broken hreflang is very common because the rules are unforgiving and nothing visibly breaks when they're violated.
Step 1: Choose the URL structure
Decide this first. Changing it later is a full migration.
| Structure | Example | Pros | Cons |
| Subdirectory | example.com/de/ | Inherits domain authority, one property to manage, cheapest | Weaker geo signal than a ccTLD |
| Subdomain | de.example.com | Separable infrastructure | Authority sharing is less certain, more config |
| ccTLD | example.de | Strongest country signal, best local trust | Each domain builds authority from zero. Expensive |
| Parameter | example.com?lang=de | Nothing | Don't |
Subdirectories are the right default for almost everyone. Use ccTLDs when there's a genuine local entity, local trust matters commercially, or the market demands it. The authority cost of ccTLDs is real and consistently underestimated.
Separate language from country only when the content actually differs. de-DE and de-AT need separate pages if prices, shipping, tax or law differ. If they'd be identical, ship one de version.
Step 2: The hreflang rules
Five rules. Violating any one silently disables the whole set.
1. Every version lists every version, including itself. Self-referencing is not optional.
<!-- On EVERY page in the group, identical block -->
<link rel="alternate" hreflang="en" href="https://example.com/pricing" />
<link rel="alternate" hreflang="de" href="https://example.com/de/preise" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/tarifs" />
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing" />2. It must be reciprocal. If the English page points at the German one, the German one must point back. Google discards one-way declarations.
3. Absolute URLs, with protocol. Relative hrefs don't work.
4. Point at canonical, indexable, 200-status URLs. Never at a redirect, a noindexed page or a 404.
5. Canonical and hreflang must agree. Each page self-canonicalises. A page canonicalising to a different language version cancels the hreflang for that page.
Step 3: The code format
Language is ISO 639-1, region is ISO 3166-1 alpha-2. Region is optional; language is not. hreflang="de" is valid. hreflang="DE" alone is not — that reads as a language code, and de for German happens to collide with the country code for Germany, which is exactly why this error survives review.
en English, any region
en-GB English, United Kingdom
en-US English, United States
de German, any region
de-AT German, Austria
pt-BR Portuguese, Brazil
zh-Hans Chinese, Simplified script
x-default The fallback for anyone not matchedErrors that appear in most audits:
| Wrong | Right | Why |
en-UK | en-GB | UK isn't the ISO code |
zh-CN for all Chinese | zh-Hans / zh-Hant | Script matters more than country here |
es-LATAM | es or per-country | Not a real region code |
jp | ja | Language code is ja, country is jp |
en-EU | en | EU isn't a country |
Always include x-default. It's the version served to everyone who doesn't match, and without it Google guesses.
Step 4: Where to put it
Three options, pick one and use it consistently.
- HTML head. Fine up to roughly 10 language versions. Beyond that the head gets heavy.
- XML sitemap. The right choice at scale. Keeps pages light and is easier to generate correctly from a single source.
- HTTP header. For non-HTML files like PDFs.
<url>
<loc>https://example.com/pricing</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing"/>
<xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise"/>
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing"/>
</url>Don't declare it in two places at once. Conflicts between the head and the sitemap are resolved unpredictably.
Step 5: Verify
# Pull the declared alternates for a page
curl -s https://example.com/de/preise \
| grep -oP '<link[^>]*hreflang[^>]*>' \
| sed -E 's/.*hreflang="([^"]+)".*href="([^"]+)".*/\1\t\2/'
# Then confirm reciprocity: each target must list this page backCheck every target returns 200 and self-canonicalises. The two failure modes that account for most broken implementations are non-reciprocal declarations and hreflang pointing at redirects.
Search Console's International Targeting report shows what Google has actually parsed, which is the only opinion that matters.
Step 6: The parts that aren't hreflang
Hreflang is the smallest part of doing this well.
- Actually translate, don't machine-translate and publish. Machine translation with no review is thin content in another language, and it's obvious to a native speaker within a sentence. Translate the important pages properly and leave the rest.
- Localise, don't just translate. Currency, date format, units, payment methods, phone format, address format, legal requirements, examples that make sense locally, and the terms people in that market actually search for.
- Research keywords per market. Direct translation of a keyword is frequently not what people search. The German for "car insurance" is not what Germans type.
- Never auto-redirect by IP. It stops Googlebot, which crawls mostly from the US, ever seeing the other versions, and it traps users in the wrong version. Offer a dismissible banner instead and let people choose.
- Localise the metadata. Translated body copy with an English title tag is very common and it costs the click.
- Don't split thin. Six half-finished language versions perform worse than two complete ones.
Debugging "the wrong version ranks"
Work through in this order:
- Is hreflang present on both pages, pointing at each other? Most cases end here.
- Do the canonicals agree with the hreflang?
- Are the codes valid?
- Are all targets 200 and indexable?
- Is Search Console reporting hreflang errors?
- Is the content actually different? Two pages that are 95% identical may be consolidated regardless.
- Is the "wrong" version simply much stronger? Hreflang expresses a preference; it can't overcome a large authority gap on its own.
Related skills
canonical-duplicate-content, technical-seo-audit, keyword-research-briefs, redirect-migration-plan, nextjs-seo
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

