## TL;DR

hreflang tells Google which language version of a page to show which searcher, and it only works when every translated page links to all its alternates, including itself. For agent tools, translate the docs and landing pages that get international traffic first, not the whole site at once. The common failure is half-implemented hreflang: tags on some pages, missing return links, and Google ignoring the whole cluster.

```text
hreflang and international SEO for agent tools
```

## Use this when

- Your tool or docs get meaningful traffic from non-English queries
- You are translating pages and want each language to rank in its market
- Search Console shows the wrong language version ranking in a country
- You need to choose between subdirectories, subdomains, or ccTLDs

## Not for this skill when

- Your audience is effectively English-only (skip hreflang entirely)
- You machine-translate everything with no review (quality problems dwarf hreflang)
- You need general translation workflow advice (different topic)

## Steps

1. Decide what to translate first. Check GSC by country: which non-English queries already bring impressions. Expected: a short list of high-demand pages worth translating.

```
Priority: landing pages and core docs with existing international impressions.
Dont start with the changelog.
```

2. Pick a URL structure. Subdirectories (example.com/es/) are simplest to maintain and consolidate authority; ccTLDs are strongest per-country signals but multiply operational cost. Expected: one consistent structure for all languages.

```
Default: subdirectories per language.
Use ccTLDs only with a real local presence and budget.
```

3. Implement hreflang with return links. Every language version lists all versions including itself, with correct language-region codes. Expected: a bidirectional cluster Google can trust.

```
Each page links: itself + every alternate, hreflang codes like es, pt-BR.
Also declare an x-default for unmatched searchers.
```

4. Keep content genuinely equivalent. Translated pages should cover the same topic fully; thin or partial translations rank poorly regardless of hreflang. Expected: each language version stands alone as a good page.

```
Checklist: full translation, local examples where it matters,
no machine-translated boilerplate left unreviewed.
```

5. Validate and monitor. Check hreflang with a validator on deploy, then watch GSC's international targeting and per-country performance. Expected: zero hreflang errors and the right version ranking per market.

```
Validate: bidirectional links present, codes valid, x-default set.
Monitor: per-country clicks and the correct URL served per market.
```

## Variant phrasings

### hreflang implementation checklist

Self-referencing tags, all alternates listed, valid codes, x-default, validated on deploy.

### Should I translate my docs for SEO

If GSC shows international demand for specific pages, translate those pages first.

### Subdirectory vs subdomain for international SEO

Subdirectories consolidate authority and are simpler; subdomains and ccTLDs only with good reason.

## Why it happens

Without hreflang, Google sees translated pages as duplicate content and picks one version to rank everywhere, usually the English one, which serves Spanish searchers an English page. hreflang fixes the matching problem, but only as a cluster: one missing return link breaks Google's trust in the whole set. The implementation fails most often because it is done page-by-page by hand instead of generated from the translation map.

## Edge cases / pitfalls

- Language-only codes (es) vs language-region (es-MX): use region only when the content truly differs by region.
- hreflang doesnt guarantee the right version ranks; it is a hint, and relevance still rules.
- Dont hreflang pages that 404 in some languages; every listed alternate must be live.
- Sitemap hreflang and header hreflang must agree; pick one method per site.
- Auto-redirecting users by IP breaks Google's crawling; let hreflang and the user choose.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_BaZktaQ_PYsMXSrrlgXGUw