agentleFS
sitetillersitetiller/ai-visibility-skills/skills/hreflang/SKILL.md

hreflang

Skill0 starsChanged 3 days agoMITView on GitHub

Implement and audit hreflang for multi-language and multi-region sites using Google's localized versions rules: self-reference, reciprocal (return) links, fully-qualified URLs, x-default, language codes (ISO 639-1) with optional region codes (ISO 3166-1 Alpha 2), and the three equivalent methods (HTML link tags, HTTP headers, XML sitemap). Use when the user asks 'hreflang', 'multilingual SEO', 'wrong country version shows in Google', 'x-default', 'en-GB vs en-UK', 'hreflang return tag errors', 'international targeting', or 'translated pages compete'. Checks pages with the sitetiller page command (hreflang array) and a bundled script for reciprocity.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are 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.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the annotations on one page:

    line 36
  2. Very specific:

    Run the bundled check, which fetches up to --max alternates one at a time and tests reciprocity:

    line 41
  3. Very specific:

    If the site uses the sitemap method, read the sitemap by eye or with curl.

    line 48
  4. Very specific:

    Make sure each alternate is indexable and in the sitemap (sitemaps skill).

    line 49
  5. Distinctive:

    Do not claim hreflang improves rankings or fixes duplicate content by itself.

    line 75
  6. Distinctive:

    Do not use hreflang for sites with no real alternates.

    line 76
  7. Distinctive:

    Do not guess code validity: cite the two standards (ISO 639-1 and ISO 3166-1 Alpha 2) and have the user check an official list.

    line 77
  8. Distinctive:

    Do not auto-redirect users by language without an x-default or a visible selector.

    line 78
  9. Distinctive:

    Read-only: do not change the user's pages.

    line 79

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

hreflang

Goal: each language or regional version points to all its alternates and to itself, with valid codes and URLs, so Google can show the right version to the right user. hreflang helps Google choose between your own versions. It does not raise rankings by itself, and the Google documentation read here makes no ranking claim.

Inputs

  • The list of localized URLs (or a page from each language), and which method the site uses.
  • For each version: language, optional region, and whether any fallback page exists (language selector or auto-redirect home page).

Rules (from Google's localized versions documentation)

RuleDetail
MethodsHTML <link rel="alternate" hreflang="..." href="..."> in <head>, HTTP Link: header, or XML sitemap. Google calls the three "equivalent". One is enough; using all adds work and no search benefit
Self-referenceeach version lists itself, and the set of tags is the same on every version
Reciprocal links"If two pages don't both point to each other, the tags will be ignored."
URLsfully qualified with protocol (https://example.com/de/); protocol-relative and root-relative URLs are not valid
Domainsalternates need not share a domain
Language codeISO 639-1 (two letters), for example en, de, pt
Region codeoptional, ISO 3166-1 Alpha 2, after the language: en-GB, pt-BR. A country code alone is invalid: GB by itself does nothing
Reserved codesEU, UN and UK have no effect. Use GB for the United Kingdom
Casevalues are case-insensitive; region conventionally uppercase
x-defaultfallback for users who match no listed language or region (a selector page or an auto-redirecting home page)
Several regions of one languageadd a generic language-only version as a catchall
PlacementHTML tags inside <head>; do not combine hreflang with other attributes such as media in the same tag
Duplicateslocalized pages count as duplicates only if the main content is not translated; template-only translations (nav, footer) and regional variants with similar English content are valid hreflang uses
Canonicalrel="canonical" annotations with an hreflang attribute are not used for canonicalization (Google's duplicate URL documentation). Each localized version carries its own self-referencing canonical, as in Google's site move guide. Do not canonicalize all languages to one page

Steps

  1. Read the annotations on one page:
    npx sitetiller page https://example.com/en/ --json
    The hreflang field is an array of { lang, href } taken from the HTML <link rel="alternate" hreflang> tags. It is empty when none exist, or when the site uses only headers or sitemaps (the tool does not read those). Also read lang (the page's <html lang>), canonical, noindex and finalUrl.
  2. Run the bundled check, which fetches up to --max alternates one at a time and tests reciprocity:
    node references/check-hreflang.mjs https://example.com/en/ --max 10
    The script is in this skill's references/ folder. It prints findings[] with level error or review: missing self-reference, relative URLs, reserved region codes, an alternate that redirects, answers 4xx or 5xx, is noindex, or does not link back, duplicate codes pointing to different URLs, and codes that are not two letters (to review, because Google documents ISO 639-1). It does not verify that two-letter codes are real languages.
  3. Compare the result with the rules table. Fix in this order: return links (most common reason annotations are ignored), then wrong codes, then redirecting or erroring alternates, then missing x-default.
  4. For the full set of locales, run step 2 on a page from each language (it checks the alternates of the page you give it). The result of a few pages shows a systematic template bug; a clean sample does not prove all pages are clean, so say how many were checked.
  5. If the site uses the sitemap method, read the sitemap by eye or with curl; each <url> must list all alternates including itself with <xhtml:link rel="alternate" hreflang="..." href="..."/>. Say honestly that the CLI does not parse these.
  6. Make sure each alternate is indexable and in the sitemap (sitemaps skill). An alternate that is noindex, blocked by robots.txt or redirected cannot serve as a localized result.

Common errors

Symptom in the outputCauseFix
"No return link"page B does not list page A, or lists a different URL for A (trailing slash, http vs https, parameters)make both sides list the same exact URLs
"Page does not list itself"self-reference missingadd the tag for the current URL
"Alternate redirects to another URL"tag lists a redirecting URLlist the final URL
en-UKreserved codeen-GB
GB or US alonecountry without languageen-GB, en-US
eng, deu or cebnot ISO 639-1 two-letter code (review: Google documents ISO 639-1)use the two-letter code where one exists; check Google's documentation before using a three-letter code
root-relative /de/not fully qualifiedhttps://example.com/de/
hreflang plus media in one tagnot allowed to combinesplit into separate tags
All languages canonicalized to the English pagecontradicts hreflangeach version self-canonical
Same code to two URLsambiguous annotationone URL per language-region

Real-world example (checked 2026-11-12)

https://wordpress.org/ lists 157 hreflang tags. Running the script flagged ca pointing to both ca.wordpress.org and ca-valencia.wordpress.org (same code, two URLs) and a three-letter code ceb. These are review items, not proof of harm: the tool applies Google's documented rules, and Google does not state what it does in each of those cases.

Output to the user

  1. How many hreflang tags, which method, and how many alternates were tested.
  2. The findings table, errors first, each with the URL.
  3. The corrected tag set for the page (full list, same on every version).
  4. What was not checked: headers, sitemaps, language-code validity beyond the shape, and pages not sampled.

Guardrails

  • Do not claim hreflang improves rankings or fixes duplicate content by itself.
  • Do not use hreflang for sites with no real alternates.
  • Do not guess code validity: cite the two standards (ISO 639-1 and ISO 3166-1 Alpha 2) and have the user check an official list.
  • Do not auto-redirect users by language without an x-default or a visible selector; Google lists a selector page or auto-redirecting home page as x-default uses, and says nothing here about redirect safety, so do not promise it is safe.
  • Read-only: do not change the user's pages.

References

  • references/sources.md: Google documentation, checked 2026-11-12.
  • references/check-hreflang.mjs: the reciprocity checker.

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.