Hreflang Guide: Syntax, Mistakes, and Best Practices

Hreflang (also called 'rel=alternate hreflang') is an HTML link attribute that tells search engines which language and region version of a page to show in which searchers' results. It was introduced by Google in 2011 to solve the duplicate-content problem multilingual sites face: if you have an English page and a Spanish page with the same content, Google may treat one as a duplicate of the other and only index one. Hreflang tells Google 'these are intentional alternates for different audiences — index both and route searchers appropriately.'

Without hreflang, a US searcher querying 'plumber near me' might see your Spanish page (because Google thinks it's relevant to their query) — and bounce because they don't read Spanish. With correct hreflang, Google shows your English page to the US searcher and your Spanish page to a Mexico searcher. The result: better engagement, higher conversion, and no cannibalization between locales.

Hreflang matters most for: multilingual service businesses (immigrant communities, cross-border professionals), international ecommerce, and any site publishing the same content in multiple languages. If your site is single-locale, hreflang is unnecessary — Google handles it correctly without the attribute.

Hreflang uses the link rel=alternate attribute with an hreflang value. The value combines an ISO 639-1 language code with an optional ISO 3166-1 alpha-2 region code. Examples: en (English, any region), en-US (English United States), zh-CN (Chinese Simplified, Mainland China), zh-TW (Chinese Traditional, Taiwan), es-MX (Spanish Mexico), fil-PH (Filipino Philippines).

Critical: region codes are case-sensitive. zh-CN is correct; zh-cn or zh-cN are not. Google ignores incorrect casing silently. Always use uppercase region subtags per the ISO standard.

A complete hreflang implementation requires three pieces on every page: (1) a self-referential hreflang tag (the page declaring its own locale), (2) an hreflang tag for every other locale version (the alternates), and (3) an x-default tag pointing to the locale to show when no alternate matches the searcher. Missing any of these breaks the implementation.

Every alternate must be bi-directional. If page A (English) declares page B (Chinese) as its alternate, page B must declare page A as its alternate. Missing return tags is the most common hreflang mistake — Google ignores both directions when one is missing.

Mistake 1 — Wrong locale code casing. zh-cn instead of zh-CN, fil-ph instead of fil-PH. Google ignores incorrectly-cased tags silently. Fix: always uppercase region subtags.

Mistake 2 — Missing return tags. Page A declares page B as alternate, but page B doesn't declare page A. Fix: every alternate must be bi-directional; if you add a new locale, update all existing pages to declare it back.

Mistake 3 — Missing or wrong x-default. Without x-default, Google guesses which locale to show unmatched searchers; usually it picks your most-indexed locale, which may not be what you want. Fix: explicitly declare x-default (usually pointing to your primary business locale).

Mistake 4 — Hreflang URLs that don't match canonical URLs. If /pricing has canonical /pricing, but its hreflang points to /pricing?utm_source=internal, Google ignores the alternate. Fix: hreflang URLs must match canonical URLs character-for-character.

Mistake 5 — Hreflang on noindex or canonicalized-away pages. Pages blocked from indexing should not declare hreflang. Fix: omit hreflang tags on noindex routes, redirected routes, and pages canonicalized to other URLs.

Mistake 6 — Hreflang to soft-404 or 'locale not available' pages. Don't declare an alternate URL that returns a 'sorry, this page isn't available in your language' message — that's a soft 404 and Google penalizes both directions. Fix: only declare alternates that contain real content; if a page doesn't exist in a locale, don't declare that locale as alternate.

Mistake 7 — Inconsistent locale variants across pages. Page A declares locales en, zh-CN, es, but page B declares only en and zh-CN. Inconsistency confuses Google. Fix: every page that exists in multiple locales should declare all locales where it exists — and no locales where it doesn't.

Step 1 — Inspect the rendered HTML. View source on any multilingual page and check the head section for link rel=alternate tags. You should see one self-referential tag, one tag per alternate locale, and one x-default tag. Verify casing, URL matching, and bi-directional tags.

Step 2 — Google Search Console. Under International Targeting > Country, Google reports hreflang errors it finds on your site. Common errors: missing return tags, wrong locale codes, broken alternate URLs. Fix every error Google reports.

Step 3 — Ahrefs or Sitebulb crawl. These tools detect hreflang issues at scale — bi-directional tag mismatches across thousands of pages, broken alternates, incorrect locale codes. Run a full-site crawl quarterly.

Step 4 — Manual SERP test. Search for your brand name from different locale-specific devices (use a VPN or Google's country-specific domains like google.com.hk for Hong Kong) and verify the right locale version shows. If you see locale cannibalization (wrong version ranking in wrong region), hreflang is likely the cause.

Step 5 — Check indexing in Search Console. Use URL Inspection on each locale version of a page to confirm Google has indexed all alternates. If a locale version isn't indexed, hreflang isn't passing the signal correctly.

Best practice 1 — Use language-only codes (en, zh, es) when you don't have region-specific content. Use region codes (en-US, en-GB, zh-CN, zh-TW) only when content genuinely differs by region (currency, legal references, vocabulary). Over-specifying region codes when content is identical creates unnecessary alternates.

Best practice 2 — Set x-default to your primary business locale (usually the locale of your company's home country). For a US business, x-default = en or en-US. For a Chinese business with an English version, x-default = zh-CN if your primary audience is Chinese, en if international.

Best practice 3 — Generate hreflang from a single source of truth (your CMS or website builder). Hand-maintaining hreflang across thousands of pages guarantees drift. Cogo Site, WordPress + WPML, and Shopify's multilingual features all auto-generate hreflang; choose a builder that does.

Best practice 4 — Keep hreflang URLs clean and stable. Don't include query parameters, session IDs, or tracking parameters in hreflang URLs. Once an alternate URL is published, don't change it without a redirect — Google's hreflang cache takes weeks to rebuild.

Best practice 5 — Audit hreflang after every locale launch, locale removal, or major content migration. Drift happens; hreflang is the canary in the coal mine for multilingual site health.

Cogo Site generates hreflang from a single source of truth — the locale-prefixed URL routing. Every page automatically includes self-referential, alternate, and x-default tags with correct ISO casing, bi-directional return tags, and canonical-matching URLs. You don't write the tags; you don't maintain them.

Adding a locale regenerates hreflang across all pages atomically — there's no window where existing pages are missing the new alternate. Removing a locale cleanly strips hreflang to that locale from all pages, preventing soft-404s.

Per-page locale visibility lets you mark a page as English-only or Chinese-only — hreflang only declares alternates where both exist, preventing the 'soft-404 alternate' mistake.

The x-default locale is configurable per site, defaulting to the original publishing locale. Hreflang URLs are derived from the same routing as canonical URLs, so they cannot drift.