Hreflang check

Q: Should I use a language code alone or add the country?

Use the language alone ( de ) when one page serves every speaker of that language. Only add the country ( de-AT , de-CH ) when you publish different pages per country, for prices or shipping for example. You can combine the two, with country lines for the specific pages and a plain language line as the general one.

Q: Can hreflang point to another domain?

Yes. example.com and example.de can be versions of each other, as long as each lists the other and itself. The rules are the same as within one domain.

Enter the address of a page that exists in several languages. We read its hreflang lines, validate every code, then visit each alternate version to see whether it answers, may be indexed and names this page in return.

A list of twins, repeated on every twin

When the same page exists in English, German and Japanese, a search engine sees three separate pages. With hreflang you tell it they’re one page in three versions, so a reader in Berlin gets the German address and not the English one. Each version carries the complete list of versions, itself included:

<link rel="alternate" hreflang="en" href="https://www.example.com/en/pricing/">
<link rel="alternate" hreflang="de" href="https://www.example.com/de/preise/">
<link rel="alternate" hreflang="ja" href="https://www.example.com/ja/pricing/">
<link rel="alternate" hreflang="x-default" href="https://www.example.com/en/pricing/">

The list can live in three places: in the <head> of the page, in a Link response header, or in the XML sitemap. This check reads the first two. It doesn’t read sitemaps, so a page with no annotation here may still be covered there.

Hreflang changes which version gets shown. It doesn’t change how well the page ranks. Search engines treat it as a hint and drop it as soon as it looks inconsistent, which is why small mistakes cost so much.

What a valid code looks like

A value is a language, optionally followed by a script and a country, joined with hyphens. Capital letters don’t matter.

Part	Standard	Examples
Language (required)	ISO 639-1, two letters	`en`, `de`, `ja`, `pt`
Script (optional)	ISO 15924, four letters	`zh-Hans`, `zh-Hant`, `sr-Latn`
Country (optional)	ISO 3166-1, two letters	`en-GB`, `pt-BR`, `zh-Hant-TW`

The country never stands alone and never comes first. Here are the mistakes this check names, with the correction when only one is possible:

en-UK: the ISO code of the United Kingdom is GB.
en_US: an underscore, the way software locales write it. Hreflang wants en-US.
es-LA: read as Spanish for Laos. Google reads no code for Latin America, so use es or one line per country.
jp, cn, cz, dk: country codes used as languages. The languages are ja, zh, cs, da.
en-EU, es-419, three-letter codes such as eng, and retired codes such as iw for Hebrew.

The table of results spells every code out in words. That catches the mistakes no rule can catch, like uk, which is a perfectly valid code and means Ukrainian.

What is checked on the page itself

Addresses. Each line needs a full address with scheme and host. Relative ones get reported.
Duplicates and conflicts. The same line twice does no harm and is reported as a remark. One code given to two different addresses is an error, because nobody can tell which page is the version for that language.
Self-reference. The page has to appear in its own list, with its exact address. A missing trailing slash is enough to break the match.
x-default. The version for readers whose language isn’t listed. It’s optional, so leaving it out gets a note and isn’t counted as a fault.
Canonical. Hreflang only works between canonical pages. A German page whose canonical names the English page tells search engines to forget the German one, and its hreflang lines go with it.
The lang attribute. If <html lang> says sv while the page lists itself as se, one of the two is wrong.
Position. Lines that end up outside <head>, often because a stray element closes the head early, are ignored by Google and flagged here.

Return links, the half that usually fails

An annotation only counts if both pages agree. If the English page says “my German version is there” and the German page doesn’t say “my English version is here”, the pair is thrown out. So once we’ve read your page, our server requests each alternate once, without following redirects, and reports for each one:

Status: It has to answer 200. A redirect means the line names an address that isn’t the final one. An error means the version is gone. An x-default that redirects is accepted, since that’s exactly what a language chooser does.
Indexable: No noindex in a robots meta tag or an X-Robots-Tag header.
Canonical to itself: Its canonical, if it has one, has to be its own address.
Links back: Its own block has to list your page, under the same code your page uses for itself.

When the corrections are mechanical (a misspelled code, a relative address, a repeated line, a missing line for the page itself), the result ends with a corrected block you can paste. Lines that need a decision from you stay as they are, marked with a comment.

One check visits at most 35 alternates and stops after about half a minute. The table marks the ones it skipped. We don’t see annotations written by JavaScript, and a site that redirects visitors by location may show our server something different from what a crawler gets.

Questions people ask

Do I need hreflang if my site is in one language?

No. Hreflang links versions of the same page to one another. With a single version there’s nothing to link, and the check reports “no annotations” as a neutral result.

What is x-default and is it required?

It’s the line for everyone your other lines don’t cover, such as a reader whose language you don’t offer. It usually points to the English version or to a page where the visitor picks a language. It’s recommended, not required.

Should I use a language code alone or add the country?

Use the language alone (de) when one page serves every speaker of that language. Only add the country (de-AT, de-CH) when you publish different pages per country, for prices or shipping for example. You can combine the two, with country lines for the specific pages and a plain language line as the general one.

What does “no return link” mean?

Your page names another version, but that version doesn’t name your page in its own hreflang block. Search engines ignore one-way annotations. To fix it, output the same complete list on every version, ideally from a single shared source.

Can hreflang point to another domain?

Yes. example.com and example.de can be versions of each other, as long as each lists the other and itself. The rules are the same as within one domain.

Does hreflang replace the canonical tag?

No. They do different jobs and they have to agree. The canonical says which address stands for a page among its duplicates, and hreflang says which other pages are its translations. Each language version should be canonical to itself.