agentleFS
keuperakeupera/seo-skills/skills/hreflang-international-seo/SKILL.md

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.

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
  1. Distinctive:

    2. It must be reciprocal: If the English page points at the German one, the German one must point back.

    line 41
  2. Distinctive:

    4. Point at canonical, indexable, 200-status URLs: Never at a redirect, a noindexed page or a 404.

    line 45
  3. Very specific:

    Always include x-default. It's the version served to everyone who doesn't match, and without it Google guesses.

    line 74
  4. Distinctive:

    Don't declare it in two places at once.

    line 93
  5. Distinctive:

    Check every target returns 200 and self-canonicalises.

    line 106
  6. Distinctive:

    Search Console's International Targeting report shows what Google has actually parsed, which is the only opinion that matters.

    line 108
  7. Distinctive:

    Do the canonicals agree with the hreflang?

    line 126

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

StructureExampleProsCons
Subdirectoryexample.com/de/Inherits domain authority, one property to manage, cheapestWeaker geo signal than a ccTLD
Subdomainde.example.comSeparable infrastructureAuthority sharing is less certain, more config
ccTLDexample.deStrongest country signal, best local trustEach domain builds authority from zero. Expensive
Parameterexample.com?lang=deNothingDon'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 matched

Errors that appear in most audits:

WrongRightWhy
en-UKen-GBUK isn't the ISO code
zh-CN for all Chinesezh-Hans / zh-HantScript matters more than country here
es-LATAMes or per-countryNot a real region code
jpjaLanguage code is ja, country is jp
en-EUenEU 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 back

Check 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:

  1. Is hreflang present on both pages, pointing at each other? Most cases end here.
  2. Do the canonicals agree with the hreflang?
  3. Are the codes valid?
  4. Are all targets 200 and indexable?
  5. Is Search Console reporting hreflang errors?
  6. Is the content actually different? Two pages that are 95% identical may be consolidated regardless.
  7. 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.