International hreflang: Multi-Language Multi-Region Site Configuration Guide

When a website has multiple language or region versions, search engines need to know: show Chinese users the Chinese version, show US users the English version, rather than treating all versions as duplicate content. hreflang is the standard solution to this problem. This article explains hreflang's purpose, how to write language/region codes, how to choose among three implementation methods, and those details that are extremely error-prone yet most easily overlooked.

What is hreflang#

hreflang is an attribute used to tell search engines "which language/region versions exist for the same content and what their respective URLs are." It helps search engines match the most appropriate version for users in search results.

It solves two core problems:

Correct matching: Let Spanish-speaking users see the Spanish version, Japanese-speaking users see the Japanese version, improving relevance and click-through rate.
Avoid duplicate content misjudgment: Multiple language translations of the same article, or similar content targeting different regions (such as US and UK English versions), will not be treated as duplicate content competing against each other.

Not a ranking signalhreflang does not improve rankings; it optimizes "which version to display." It's a hint rather than a mandatory directive—Google will reference it but also make comprehensive judgments combining user language settings, geographic location, etc.

When is hreflang needed#

hreflang is only meaningful in the following situations. If not applicable, no configuration is needed:

Scenario	Needed
Same content has multiple language translations (Chinese / English / Japanese)	✅ Yes
Same language targeting different regions (en-US / en-GB, different prices/currencies)	✅ Yes
Same language, different regions but nearly identical content	✅ Yes (avoid duplicates)
Only one language, one region	❌ No
Different pages are different content (not translations)	❌ No

Language and region codes#

hreflang values consist of language code (required) and region code (optional), in the format language or language-region:

Language code: Uses ISO 639-1, two lowercase letters, such as zh (Chinese), en (English), ja (Japanese).
Region code: Uses ISO 3166-1 Alpha-2, two uppercase letters, such as US (United States), GB (United Kingdom), CN (China).

hreflang value	Meaning
`en`	English (unspecified region)
`en-US`	American English
`en-GB`	British English
`zh`	Chinese (unspecified region)
`zh-Hans`	Simplified Chinese (script code)
`zh-Hant`	Traditional Chinese (script code)
`x-default`	Default fallback version (special value)

Common code errorsRegion codes are countries/regions not languages: Don't write zh-CN as "simplified"—CN refers to mainland China region. To distinguish simplified/traditional, use script codes zh-Hans / zh-Hant. Also, there's no en-UK notation; the UK is GB. Don't use incorrect formats like en_us (underscore, lowercase).

Three implementation methods#

hreflang has three equivalent implementation methods—choose one (don't duplicate or mix).

Method	Location	Suitable for
HTML `<link>` tag	Each page's `<head>`	HTML sites with moderate page count
HTTP response header	Server response headers	Non-HTML files (PDFs, etc.)
XML Sitemap	`xhtml:link` in sitemap	Large sites, centralized management

Method 1: HTML link tag

In each page's <head>, list all language versions (including itself). Assuming Chinese, English, and Japanese versions:

Each version's head gets this same set

<link rel="alternate" hreflang="zh" href="https://example.com/zh/page.html">
<link rel="alternate" hreflang="en" href="https://example.com/en/page.html">
<link rel="alternate" hreflang="ja" href="https://example.com/ja/page.html">
<link rel="alternate" hreflang="x-default" href="https://example.com/en/page.html">

Method 2: XML Sitemap

In the sitemap, use xhtml:link for each URL to declare its language alternatives. Suitable for large sites with centralized maintenance—see Sitemap for details.

sitemap.xml snippet

<url>
  <loc>https://example.com/zh/page.html</loc>
  <xhtml:link rel="alternate" hreflang="zh" href="https://example.com/zh/page.html"/>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page.html"/>
</url>

Method 3: HTTP response header

Used for non-HTML resources like PDFs, declared in response headers:

HTTP header

Link: <https://example.com/en/doc.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/zh/doc.pdf>; rel="alternate"; hreflang="zh"

Most critical rule: bidirectional references#

This is the most important and most frequently violated hreflang rule: hreflang must mutually confirm. If page A declares B as its English version, then page B must also declare A as its Chinese version. If either side is missing, this relationship will be ignored by search engines.

Moreover, each page's version list must include itself (self-reference). This means that in a three-language site, each page's head should have the complete set of three (or four, including x-default) declarations, and the content of these declarations should be identical across all three pages.

Missing any one breaks it"A→B but B not→A" is the most typical hreflang failure cause. Think of it as mutual confirmation relationships: one-way declarations are invalid; both parties must confirm. When batch generating, especially ensure each page includes a complete, consistent, self-inclusive version list.

Purpose of x-default#

x-default is a special hreflang value used to specify "which page should be displayed when the user's language/region doesn't match any declared version." It's commonly used for:

Language selection page: An entry page letting users choose their language themselves.
Primary/default language version: For example, using the English version as fallback for all uncovered users.

If you have Chinese, English, and Japanese versions, and a French-speaking user visits—they don't match any, so x-default decides which they see. Configuring x-default isn't mandatory but is strongly recommended, avoiding "uncovered users" being randomly assigned.

Coordination with canonical#

hreflang and canonical must be correctly coordinated, otherwise they conflict. The core rule is one sentence: Each language version's canonical points to itself, hreflang lists all versions.

Correct writing for Chinese page /zh/page.html

<!-- canonical points to self, not English version -->
<link rel="canonical" href="https://example.com/zh/page.html">

<!-- hreflang lists all versions (including self) -->
<link rel="alternate" hreflang="zh" href="https://example.com/zh/page.html">
<link rel="alternate" hreflang="en" href="https://example.com/en/page.html">

Fatal errorPointing Chinese page's canonical to the English page (thinking this "consolidates authority") is disastrous—you're telling Google "Chinese page shouldn't be independently indexed," resulting in the Chinese version disappearing from search results. canonical only deduplicates within the same language; never point cross-language.

Common mistakes#

Error	Consequence	Fix
Missing return links (not bidirectional)	Entire hreflang set ignored	Ensure each version declares each other
Version list doesn't include self	Incomplete relationship, may fail	Include self-reference on each page
Using relative URLs	Parsing errors	Must use complete absolute URLs
Wrong language/region codes	Invalid declaration (e.g., en-UK, zh-CN as simplified)	Use ISO standard codes
canonical points cross-language	Non-default language versions not indexed	canonical points to self
hreflang points to noindex/redirect pages	Invalid relationship	Point to indexable 200 pages
Duplicating/mixing three methods	Conflicts, maintenance chaos	Choose only one implementation method

How to verify#

hreflang configuration is complex and error-prone; be sure to verify after launch:

Google Search Console: Previously had dedicated "International Targeting" reports; now mainly observe index status of each language version through "Pages" index reports and actual search performance.
Third-party validation tools: Use hreflang tag validation tools (like Merkle hreflang Tags Testing Tool) to batch check whether return links are complete and codes are valid.
Crawler tools: Screaming Frog and others can crawl the entire site and report missing return links, inconsistencies, and incorrect codes in hreflang.
Manual spot checks: View page source code to confirm each version's declaration list is consistent, includes self, and URLs are correct.

This site's multi-language design#

MagicSEO currently only has a Chinese version, but has been prepared for multiple languages from day one.

Actual configuration in this page's head

<link rel="canonical" href="https://magic-seo.com/articles/en/technical-seo/hreflang.html">
<link rel="alternate" hreflang="en" href="https://magic-seo.com/articles/en/technical-seo/hreflang.html">
<link rel="alternate" hreflang="zh-Hans" href="https://magic-seo.com/articles/zh/technical-seo/hreflang.html">
<link rel="alternate" hreflang="x-default" href="https://magic-seo.com/articles/en/technical-seo/hreflang.html">

Site demonstrationThis site's URLs are language-layered (/articles/en/...), with the en segment reserved for multiple languages. Currently each page declares the English version with en and Chinese version with zh-Hans, x-default fallback also points to English version itself, and each canonical points to itself—this is the correct configuration for multi-language stage. Future adding of other language versions only requires placing pages under /articles/xx/... and adding mutual hreflang references in each version's head, smoothly upgrading to compliant multi-language hreflang without changing existing URL structure.

hreflang configuration checklist#

Only configure when there are multi-language/multi-region versions
Use ISO 639-1 for language, ISO 3166-1 (uppercase) for region
Use zh-Hans / zh-Hant for simplified/traditional, not zh-CN as simplified
Each page lists all versions and includes itself
All versions declare each other (bidirectional references)
Use complete absolute URLs
Configure x-default as fallback
Each language version's canonical points to itself
Choose only one implementation method, don't mix
After launch, use validation tools to confirm return links are complete

Frequently asked questions#

Does hreflang affect rankings?

hreflang itself is not a ranking signal and will not improve a page's ranking. Its purpose is to help search engines display the correct version to users of different languages or regions in search results, thereby improving relevance, click-through rate, and user experience, while reducing duplicate content issues between different language versions. In other words, it optimizes "which version to display," not "how high it ranks."

Does a single-language site need hreflang?

No. hreflang is only meaningful when a site has multiple language or region versions and the content is translated correspondingly. If you only have one language version, you don't need to configure hreflang. However, it's recommended to reserve positions for multiple languages when designing the directory structure (such as /zh/, /en/), so hreflang can be added smoothly when expanding language versions in the future.

Do hreflang and canonical conflict?

They don't conflict, but must be correctly coordinated. Each language version's canonical should point to itself, not to other language versions. hreflang is responsible for declaring that these pages are language alternatives of each other, while canonical is responsible for deduplication within each language. The most common mistake is pointing canonical of all language versions to one language, which causes other language versions to not be independently indexed.

Is x-default mandatory?

Not mandatory, but strongly recommended. x-default is used to specify the default page to display when the user's language/region doesn't match any declared version, often used for language selection pages or primary language versions. Configuring x-default provides a reasonable fallback for all other uncovered users, avoiding them being randomly assigned to inappropriate versions.