International SEO skill for Claude Code

Done well means every searcher lands on the version written for their language and market, each version can be crawled and indexed on its own, and search engines can see how the versions relate. The usual failure is not missing hreflang — it is hreflang that contradicts canonicals, redirects or the content itself.

Ground rules

• Language and region are different decisions. Translate for language; localize for market (currency, units, legal text, shipping, examples, spelling).
• Every indexable variant needs its own crawlable URL. Never serve different languages at one URL based on cookies, Accept-Language or IP.
• Never force-redirect by IP or browser language. Suggest a switch with a dismissible banner and remember the choice; crawlers mostly come from one country and would never see other versions.
• hreflang is a hint, not a ranking boost. It only swaps which equivalent page is shown.

Workflow

- [ ] 1. Decide markets and languages from demand data
- [ ] 2. Choose the URL structure
- [ ] 3. Map equivalent pages across versions
- [ ] 4. Implement hreflang (one method), canonicals and sitemaps
- [ ] 5. Localize, not just translate, high-value pages
- [ ] 6. Build language/region switching without forced redirects
- [ ] 7. Verify in crawls and Search Console; monitor per market

1. Decide markets from evidence

Check Search Console and analytics for impressions and conversions by country and language, and keyword volume in the target language (search terms rarely translate one to one). Launch fewer, fully localized versions rather than many thin machine translations.

2. Choose the URL structure

Structure	Example	Choose when	Costs
Subdirectory	example.com/de/, example.com/en-gb/	Default for most sites; one domain’s authority shared by all versions	Weaker local signal than a ccTLD
ccTLD	example.de	Strong local brand, separate legal entity or local hosting needs	Authority split per domain; more operations
Subdomain	de.example.com	Platform constraints force separate apps	Often treated more like separate sites
URL parameter	?lang=de	Avoid	Easy to break canonicals and crawling

Keep the pattern consistent: either language-only (/de/) or language-region (/de-at/) per version, and only add a region when content genuinely differs for that market.

3. Map equivalent pages

Build a mapping table before writing tags: one row per piece of content, one column per version. Only pages that are true equivalents get linked. If a page exists only in English, it gets no hreflang cluster — do not point the German slot at the German homepage.

content_id | en (x-default)            | de                    | fr-ca
pricing    | /pricing/                 | /de/preise/           | /fr-ca/tarifs/
docs-start | /docs/getting-started/    | /de/docs/einstieg/    | (none)

4. Implement hreflang, canonicals and sitemaps

Pick one delivery method per page type: HTML <link> tags in <head>, HTTP Link headers (useful for PDFs), or XML sitemaps (best at scale). Mixing methods invites contradictions.

HTML example for the pricing cluster above — identical set on every page in the cluster:

<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-CA" href="https://example.com/fr-ca/tarifs/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/" />

Sitemap form (declare xmlns:xhtml="http://www.w3.org/1999/xhtml" on <urlset>):

<url>
  <loc>https://example.com/de/preise/</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="fr-CA" href="https://example.com/fr-ca/tarifs/"/>
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
</url>

Rules that cause most errors:

• Self-reference: every page lists itself in its own cluster.
• Reciprocity: if A points to B, B must point back to A, or the pair is ignored.
• Valid codes: language is ISO 639-1 (de, pt), optional region is ISO 3166-1 alpha-2 (de-AT, pt-BR). Region alone (uk, eu) is invalid; en-uk is wrong (en-GB).
• Absolute URLs that return 200 and are indexable — never redirected, noindexed or blocked.
• Canonicals point to self on each language version. A German page canonicalized to the English page tells search engines to drop the German one, and hreflang to it is ignored.
• x-default names the fallback for unmatched users, usually the language selector or the primary-language page.
• Duplicate-language regional variants (en-US, en-GB, en-AU) need real differences (currency, spelling, offers) or they may be folded together.

5. Localize high-value pages

For money pages, adapt: currency and pricing display, units, date and number formats, payment methods, legal and tax text, local examples and testimonials, and keywords researched in-language. Translate the metadata too — title, description, image alt text, structured data inLanguage, and slugs where the CMS allows. Machine translation without native review is acceptable for low-value long-tail pages only if a human checks it; publish nothing you would not show a native speaker.

6. Switching without forced redirects

• A visible language/region selector on every page, linking to the equivalent page (not the homepage), with each option labeled in its own language (“Deutsch”, not “German”).
• An optional banner suggesting the matching version based on Accept-Language, dismissible and remembered in a cookie.
• Internal links stay within the current version; navigation should not leak users across languages.

7. Verify

1. Crawl each version with a crawler that reports hreflang (Screaming Frog, Sitebulb or a custom script): no missing return links, no non-200 targets, no canonical conflicts.
2. Spot-check rendered HTML, not just templates — JavaScript-injected hreflang must appear in the rendered DOM.
3. Search Console: inspect sample URLs from each version, confirm the Google-selected canonical matches the declared one, and watch performance filtered by country and page path.
4. Search from the target market (or a localized SERP checking tool) for brand and key terms, and confirm the right version shows.

Gotchas

• Templating bugs that output the same hreflang set on every page of the site (all pointing at homepages) are common after a CMS change. Validate per page, not per template.
• Paginated, filtered and parameter URLs should not join clusters unless each has a true equivalent.
• Moving to a new structure is a site migration: map every old URL to its new version with 301s and update hreflang and sitemaps in the same release (see seo-site-migration).
• lang attribute on <html> is for accessibility and browsers; it does not replace hreflang, but it should match the page language.
• Bing relies more on the content-language meta and lang attribute; set them consistently.

Output: international SEO plan or audit

## International SEO — <site>
**Markets & languages:** <list with evidence: impressions, revenue, keyword volume>
**Structure:** <subdirectory/ccTLD/subdomain> because <reason>
**Clusters mapped:** <n> content items × <m> versions (mapping sheet: <link>)
**Implementation:** hreflang via <html|headers|sitemap>; x-default = <url>

### Findings
| Severity | Issue | Example URL | Fix |
|---|---|---|---|
| High | German pages canonicalize to English | /de/preise/ | Self-canonical on each version |
| Medium | Missing return link fr-CA → en | /fr-ca/tarifs/ | Add reciprocal annotation |

**Monitoring:** Search Console by country; crawl hreflang report weekly after launch.