hreflang for translated pages

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# hreflang for translated pages

If the production site has pages in more than one language or for more than one region, search engines need to know which version to show to whom. Wrong hreflang shows people the wrong language or drops pages. Set it up from one helper so every page lists all its versions correctly.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Machine-translate content.
- Change URL structures without a redirect plan.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Map the versions

List the languages and regions the site serves, how URLs are structured (subdirectories, subdomains, separate domains, query parameters) and which pages exist in which versions. Flag pages that exist in only some languages.

### 2. Generate hreflang from one helper

For each page, output a `<link rel="alternate" hreflang="...">` for every version that exists, including the page itself, using valid codes (language like `en`, `de`, or language-region like `en-GB`, `pt-BR`). Add `x-default` for the version shown when no language matches. All URLs absolute and canonical.

### 3. Keep it reciprocal and consistent

Every version must list every other version back. Each version's canonical points at itself, never at another language. Pages that are not translated list only the versions that exist.

### 4. Do not redirect by language

Do not force-redirect visitors or crawlers by browser language or IP; offer a language switcher instead, so crawlers can reach every version.

## Done means

- [ ] Every translated page lists all its versions, including itself, with valid codes and x-default.
- [ ] hreflang links are reciprocal across versions.
- [ ] Each version is self-canonical.
- [ ] Visitors are not force-redirected by language; a switcher lets them choose.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.