hreflang without tears

// Editorial team

hreflang tags tell search engines which language versions of a page exist, so that a Thai reader is shown the Thai page and a French reader the French one. The rules are simple, and they are easy to get wrong across a large site.

Pick a URL structure

Use a subdirectory per language, such as /fr/ and /de/, unless you have a reason to use separate domains. Subdirectories are easy to host and share the main domain's history. Keep the rest of the path the same in every language where you can, which makes generating the tags simple.

Every page lists every version

Each language version must list all versions, including itself. If the English page points to the French page but the French page does not point back, search engines may ignore the pair. These return links are the most common failure.

Use the right codes

Language codes follow ISO 639-1, such as "th" for Thai and "uk" for Ukrainian, not "ua". Region codes are optional and use ISO 3166-1, as in "pt-BR". A region code on its own is invalid.

x-default

Add an x-default entry for the page to show when no language matches, usually the English version or a language selector.

Tags or sitemap

You can put hreflang in the page head or in the XML sitemap. On sites with thirty languages, the head tags add a lot of markup to every page, and the sitemap can be easier to maintain. Do not mix the two methods for the same page.

Translate the page

hreflang only links equivalent pages. A page with a translated menu and an English body is not a translation. Translate the content, the title and the meta description.

Check it automatically

We run a build check that every hreflang target exists, returns 200 and points back. It catches broken pairs before they ship.