# Hreflang: connecting language versions

> Connect equivalent Spanish and English pages, check return annotations and distinguish language versions from regional targeting and canonical URLs.


**Hreflang tells Google which URLs are versions of a page for different languages or regions.** A workshop with Spanish and English pages can declare that relationship even when the URL wording differs. Both translations must exist; the annotation does not translate the content.

## One ES/EN pair with different slugs

Suppose these illustrative URLs contain the same workshop offer in two languages:

- `https://www.example.com/es/taller-ceramica/`
- `https://www.example.com/en/pottery-workshop/`

The `head` of **both pages** would contain this same minimum set for the example:

```html
<link rel="alternate" hreflang="es"
  href="https://www.example.com/es/taller-ceramica/" />
<link rel="alternate" hreflang="en"
  href="https://www.example.com/en/pottery-workshop/" />
```

The Spanish page includes itself and points to the English page. The English page does the same. A declaration from only one side lacks a return annotation. Check both published responses, even if the CMS appears to generate them from one template.

Google supports [HTML, HTTP header and sitemap annotations](https://developers.google.com/search/docs/specialty/international/localized-versions). Choose a method you can maintain. Implementing all three introduces more places for the sets to fall out of sync.

## Language and country answer different questions

`es` identifies Spanish without restricting it to a country. `es-CL` adds a region for a version aimed at Chile. A business address alone is not a reason to create that extra version: first establish whether there is distinct regional content to serve.

For UK English, the regional code is `en-GB`. Google does not support `en-UK` as that combination. A country code on its own cannot replace the language. If the two pages serve Spanish and English readers generally, `es` and `en` avoid declaring regional variants that do not exist.

The optional `x-default` value can point to a language selector or a fallback for unspecified languages. Give it an appropriate destination. Adding a homepage as the alternate for every individual article just to populate the value does not establish equivalence.

## Keep hreflang and canonical declarations consistent

A [canonical URL](/en/guides/canonical-url/) expresses a preference among duplicate or very similar pages. Hreflang connects language or regional versions. When the body is fully translated, avoid automatically pointing the Spanish canonical at English merely because English is the site's “main” language.

In this hypothetical pair, each translation can declare its own URL as canonical while sharing the alternate set. If either address redirects or carries `noindex`, resolve that inconsistency before expecting it to serve as a search version.

## Check the destinations as well as the tags

Open each destination and confirm that it describes the same workshop. A translated homepage is not the alternate for a specific class page. Check the complete URLs, language codes and return annotations. Then use the visible language selector to reach the actual counterpart.

Google recommends [separate language URLs and links for switching versions](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites). A language change controlled only by cookies is harder to share and inspect. Automatic location-based redirects can also prevent people from opening the version they need.

Keep a record of the pairs when adding or retiring translations. Removing one version means updating the remaining annotations too. The useful check is whether equivalent, accessible destinations remain connected. Finding a tag in the HTML alone does not guarantee which version Google will display for a particular search.

## Plan your next post in HeyMark.

Keep the idea, review the draft with your team, and see how it performed in the accounts you connected.

[Start free](https://app.heymark.ai) · [See how it works](https://heymark.ai/en/#product)

## Developer and agent resources

- [HeyMark MCP documentation](https://heymark.ai/en/mcp/)
- [llms.txt](https://heymark.ai/llms.txt)
- [Full site content for language models](https://heymark.ai/llms-full.txt)
- MCP protocol endpoint: `POST https://mcp.heymark.ai`
- OAuth protected-resource metadata: [/.well-known/oauth-protected-resource](https://mcp.heymark.ai/.well-known/oauth-protected-resource)
- MCP server card: [/server-card](https://mcp.heymark.ai/server-card)
