hreflang for international shops: links and codes

A shop with three language versions carries nine annotations for a single page, and as a rule nobody notices when one of them is missing. The pages load, the translation is in place, sales run – but French users are still served the English version, because two pages do not point to each other and Google therefore ignores the annotation (Google, Search Central). hreflang is not a language switcher, it is a mapping between addresses: it tells the search engine which URLs say the same thing in another language or for another country. This article shows the three methods available for the annotation, why the return link is the real obligation, which language and region codes are valid, what x-default does and where the Geo-blocking Regulation draws a line around automatic redirects. The technical framework for all of this is part of our search engine optimization for shops.

What the annotation does and what it does not

hreflang maps addresses to one another, it does not set a language. The annotation says: these addresses show the same content in another language or country version, pick the right one for this user. What it explicitly does not do is stated in the documentation itself: Google determines the language of a page algorithmically and not from hreflang or the lang attribute (Google, Search Central). A page does not become French because hreflang="fr-FR" is attached to it, but because French text is on it. That order matters more in daily work than it sounds: annotating a category page that is only half translated improves nothing, it merely asserts something about content the search engine assesses independently anyway. The annotation is a statement about relationships between pages, not a property of a single page – which is exactly why it cannot be checked on a single page either.

For the annotation itself Google names three equivalent methods: link elements in the head section of every page, a Link header in the HTTP response and entries in the XML sitemap. Which one you use is explicitly left open and depends on what can be maintained most cleanly in your own system (Google, Search Central). In a shop the decision usually comes down to a very practical question: which layer actually knows all the language versions? The page template knows them if all versions live in the same system. The server knows them if the mapping can be derived from the address. The sitemap generator knows them if it reads all domains and directories. Where none of these three layers has the complete picture, the missing annotation is not the problem but its symptom.

Three methods, one and the same statement

Equivalent does not mean freely mixable. Experience suggests picking one method and sticking with it: otherwise every check has to look in two places, and contradictions between the head section and the sitemap only surface once somebody puts them side by side. The table sorts the three methods by what they demand in day-to-day operation.

<link rel="alternate" hreflang="de-DE" href="https://shop.example/de/produkt/" />
<link rel="alternate" hreflang="en-GB" href="https://shop.example/en/product/" />
<link rel="alternate" hreflang="fr-FR" href="https://shop.example/fr/produit/" />
<link rel="alternate" hreflang="x-default" href="https://shop.example/" />

The sitemap states the same thing in a different place. Every address gets its own url entry, and each of those entries lists all versions, itself included. With three language versions that means three entries with three identical child entries each, nine annotations in total for a single page (Google, Search Central). That looks redundant and is precisely the point: the return link is not an optional extra, it is the condition for the annotation to apply at all. The child entries do not count towards the URL limit of the sitemap (Google, Search Central); the size limit of 50 MB uncompressed still applies (Google, Search Central), and a large structure reaches it sooner than one without language annotations – the sitemap then has to be split into several files, which can be submitted together through a sitemap index file. For shops with several thousand articles this is the method most readily generated by machine and checked by machine just as easily.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://shop.example/de/produkt/</loc>
    <xhtml:link rel="alternate" hreflang="de-DE" href="https://shop.example/de/produkt/"/>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://shop.example/en/product/"/>
    <xhtml:link rel="alternate" hreflang="fr-FR" href="https://shop.example/fr/produit/"/>
  </url>
  <url>
    <loc>https://shop.example/en/product/</loc>
    <xhtml:link rel="alternate" hreflang="de-DE" href="https://shop.example/de/produkt/"/>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://shop.example/en/product/"/>
    <xhtml:link rel="alternate" hreflang="fr-FR" href="https://shop.example/fr/produit/"/>
  </url>
  <!-- third entry for /fr/produit/ with the same list -->
</urlset>

The third method runs through the server response. A Link header carries the same list as the head section, and it is identical for every version of a page (Google, Search Central): the same line for the German, the English and the French address. It becomes interesting wherever there is no HTML head – it is useful for files without an HTML head, such as PDF files (Google, Search Central). A data sheet in three languages can be annotated that way without touching the file itself. The price is a question of responsibility: the entry moves from the content system into the server configuration, and whoever is not allowed to change anything there cannot correct the annotation either.

The return link is the real obligation

The rule most structures fail on fits into one sentence: each language version must list itself as well as all other language versions (Google, Search Central). If two pages do not point to each other, Google ignores the annotation – and not just one direction, but the pair. That is why a half-maintained structure achieves less than the effort suggests: where the return link is missing, the annotation has no effect for that pair, and nobody receives a notice about it.

If two pages don't both point to each other, the tags will be ignored.

Google, Search Central: Localized versions of your pages

Google lists missing return links among the most common hreflang mistakes (Google, Search Central), and that matches what shows up in shop projects: the annotation is produced by the system that delivers the main version, and the secondary versions get it added later. Making matters harder, the annotated alternate URLs do not need to be on the same domain (Google, Search Central). As soon as one version lives on its own country domain, the obligation leaves your own system: the return link has to come from a place maintained by a different department, a different service provider or a different content system. Anyone running such a structure needs a written agreement about it rather than an assumption.

• Every version lists itself – with the address it is actually delivered under.
• Every version lists every other version, including the rarely maintained one.
• The annotation points to addresses that answer with status 200, not to redirects.
• Across domain boundaries the same obligation applies – both sides have to deliver.
• The list is produced in one place and rolled out into all versions instead of being maintained separately per version.

Language and region codes

Only language codes from ISO 639-1 and region codes from ISO 3166-1 Alpha 2 are permitted; codes that are not listed in these two standards are not supported (Google, Search Central). The first code denotes the language: a country code on its own is not a valid annotation, and the language is not derived from the country automatically (Google, Search Central). The example in the documentation is Belgium – de-be, nl-be and fr-be annotate the three language versions for Belgian users, while a standalone be does not mean Belgium but the Belarusian language. Mistakes of this kind are particularly stubborn because they are syntactically fine: the annotation is read, it just means something other than intended.

Wrong region codes rarely stand out because they break nothing – they simply do nothing. If an annotation uses codes reserved for something else, Google ignores that part of the entry; EU, UN or UK have no effect in hreflang annotations (Google, Search Central). en-UK in particular appears in many structures that grew over time, because the code looks like the obvious abbreviation. For languages with several writing systems there is a rule of its own: for language script variations Google derives the script from the country code, so zh-TW yields traditional characters (Google, Search Central).

x-default and the fallback URL

x-default is a reserved value and denotes the fallback page for every language setting that matches none of the annotated versions (Google, Search Central). One point matters here: x-default is not "the English version". It is the page a user should land on whose language does not occur in the shop at all – typically a selection page listing all versions, or the home page from which every version can be reached. Entering the English product page instead makes a decision for the user rather than offering one.

Next to that sits the case of several versions of the same language. For several versions of the same language Google additionally recommends a catchall URL without a region (Google, Search Central): alongside de-DE, de-AT and de-CH there is then a plain de for all German-speaking users whose region is not among them. This is not an edge case – as soon as a shop runs two country versions of the same language, there are users outside both countries, and without a catchall URL the x-default entry is all that is left for them.

<link rel="alternate" hreflang="de-DE" href="https://shop.example/de-de/" />
<link rel="alternate" hreflang="de-AT" href="https://shop.example/de-at/" />
<link rel="alternate" hreflang="de"    href="https://shop.example/de/" />
<link rel="alternate" hreflang="en-GB" href="https://shop.example/en-gb/" />
<link rel="alternate" hreflang="en"    href="https://shop.example/en/" />
<link rel="alternate" hreflang="x-default" href="https://shop.example/" />

Domains, directories and what is read from them

Before the annotation comes the question of how the versions are laid out in the first place: country domains of their own, subdomains or directories of one domain. A country-specific domain is a strong signal to Google that a website is intended for a particular country (Google, Search Central) – it is the only one of the three layouts the documentation explicitly credits with such a signal. It gets expensive elsewhere: every domain needs its own maintenance, its own certificates and its own sitemap. For the annotation itself the layout does not matter, because the annotated alternate URLs do not need to be on the same domain (Google, Search Central). Whether the versions live in one system or several is a question of the content management system and of responsibilities, not of the annotation.

What does not work is documented just as clearly. Google ignores locational meta tags such as geo.position (Google, Search Central), and Google explicitly advises against adapting content on the basis of IP analysis (Google, Search Central). Both turn up regularly in shops that grew over time, usually as leftovers of an earlier solution. Anyone running several sales channels is better off separating the versions by address than by runtime detection; how to organise several shops under one roof is covered in the article on Shopware multistore.

Redirect or offer

A tempting reflex in international shops is the automatic redirect: whoever arrives with a French browser setting ends up on /fr/. Google advises against automatically redirecting users from one language version to another (Google, Search Central); the section of the documentation is called "Let the user switch the page language" for a reason. The practical reason is banal: the browser setting says something about the device, not about the person in front of it. A German-speaking buyer with an English company laptop gets the wrong version, and a visitor clicking a link to the German product page does not get to see what the sender meant. The better solution is unspectacular: offer the matching version visibly and leave the switch to the user.

The second limit is legal and has been drawn sharply in the EU for years. Without the customer's explicit consent, traders are prohibited from redirecting to a different version of the online interface for reasons of nationality, place of residence or place of establishment (Regulation (EU) 2018/302, Article 3(2)). The regulation has applied since 3 December 2018 (Regulation (EU) 2018/302, Article 11(1)) and therefore generally concerns every online shop that customers from other member states access; certain areas such as transport, financial and audiovisual services are excluded (Regulation (EU) 2018/302, Article 1(3)). What is meant is not the language choice as such, but the redirect without explicit consent to a version that differs in layout, language or other characteristics and is selected by nationality, place of residence or place of establishment.

Two follow-on rules are regularly overlooked. Even after a redirect with consent, the version of the interface the customer originally sought to access must remain easily accessible (Regulation (EU) 2018/302, Article 3(2)) – consent that closes off the way back does not meet the requirement. And where a redirect is legally required, the explanation for it has to be given in the language of the interface the customer originally sought to access (Regulation (EU) 2018/302, Article 3(3)). For implementation that means: the notice belongs in the language of the page the customer wanted to open, not in the language of the target – a requirement a server-level redirect without access to the translations can hardly meet.

How much cross-border buying actually happens

The share of cross-border orders can be quantified – but only together with the reference population. Among people in the EU who bought online in the last three months, 82.96 percent ordered from sellers in their own country in 2023 and 32.84 percent from sellers in other EU countries (Eurostat, EU-27, 2023). The two values do not add up to one hundred, because the same person can appear in both groups: anyone ordering domestically and from elsewhere in the EU is counted twice. For shop structure this is the sober version of internationalization – a minority buys across borders, but one that carries weight in absolute numbers.

Two further series from the same data set round out the picture. 40.24 percent ordered from sellers in other countries inside or outside the EU, and 16.11 percent from sellers in unknown countries (Eurostat, in each case as a share of people who bought online in the last three months, EU-27, 2023). The last series is the most instructive one if read correctly: the indicator denotes purchases from sellers in unknown countries – it says nothing about the response behaviour of the people surveyed. For a shop, an unknown country of origin of the seller mainly means one thing: origin, language and responsibility were not recognisable to the buyer.

The three countries stand here as examples, not as a range: they show that the value differs widely from market to market, not where the edges lie. Three further numbers provide the frame. 78 percent of internet users in the EU bought or ordered goods or services online in 2025 (Eurostat, respondents aged 16 to 74 who used the internet in the last twelve months). The European Union has 24 official languages (European Union). And 59 percent of Europeans are able to hold a conversation in at least one additional language besides their mother tongue (European Commission, Special Eurobarometer 540, 26,523 respondents aged 15 and over, surveyed in autumn 2023). No recommendation about how many versions a shop needs follows from these three numbers, but an order of work does: markets with their own responsibilities first, then languages. How the versions themselves come about is covered in the article on shop internationalization.

In the shop: where the annotation is produced

In Shopware 6 (Community Edition) the annotation hangs off the sales channel: the hreflang meta tag is justified there by a shop having several language versions (Shopware). For localisation a distinction is made between annotation by ISO standard and the browser language alone (Shopware) – that is the decisive switch, because it determines whether a version is annotated as de-DE or as de. The decision belongs to the structure and not to the settings: anyone running two German-language country versions needs the code with a region; anyone delivering a single German-language version for all regions has an easier time with the language code without a region. Reordering the versions during a shop migration is the cheapest moment to get this right.

1. Take stock: which versions exist, under which addresses, in which system, with which responsibility.
2. Settle on one method: head section, Link header or sitemap – and deliberately leave the other two empty.
3. Add the self-reference and the catchall URL: every version lists itself, plus x-default and, where a language has several versions, the catchall URL without a region.
4. Generate the list centrally: one source from which all versions receive the same list.
5. Wire in a check: one run on every release that compares return links, status codes and codes.

Mistakes that surface late

Anyone looking for the International Targeting report in Search Console will not find it any more. It is deprecated, and on 24 August 2022 Google removed the references to it from its search documentation (Google, Search Central) – which supports the statement that it has not been maintained since August 2022 at the latest. None of that changes the annotation itself: Google continues to support hreflang and continues to use the entries (Google, Search Console Help). What has gone is the convenient place where the errors were collected; since then the checking rests entirely with the operator.

• Missing return link: one version points, the other does not point back – Google lists this among the most common hreflang mistakes (Google, Search Central).
• Missing self-reference: the template outputs "all other languages" and leaves out its own version.
• Country code on its own: at instead of de-AT, be instead of nl-be – the first code denotes the language (Google, Search Central).
• Reserved code: EU, UN or UK have no effect, while the rest of the entry is still read (Google, Search Central).
• x-default missing or pointing wrong: a fallback page that presupposes a language itself is not a fallback page.
• Dead targets after a relaunch: the annotation points to addresses that no longer exist – during a move it belongs in the same redirect plan as every other address.

Because the checking rests with the operator, it belongs in operations and not in a one-off acceptance test. A run that reads the sitemap, fetches every annotated address and compares the opposite direction takes a few minutes and finds exactly the cases nobody reports. Two things matter more than they look: the run has to record the status code of the target address – an annotation pointing to a redirect is not a return link – and it has to log what it could not measure. What crawlers actually fetch from the versions is shown by log file analysis; only both together produce a picture.

Where the numbers come from and what they do not say

The technical statements come from two documents in the Google search documentation: "Localized versions of your pages" and "Managing multi-regional and multilingual sites"; both are living pages and the quotations apply to the page state that was checked. The note about the deprecated report comes from the change list of the search documentation and from Search Console Help. The legal requirements are set out in Regulation (EU) 2018/302. The market figures come from the Eurostat data set isoc_ec_ibos, retrieved through the dissemination API, and from the Statistics Explained article on e-commerce statistics. The language figures come from the languages page of the European Union and from Special Eurobarometer 540. The Shopware statements come from the manufacturer documentation on the sales channel.

What the numbers do not say is part of the picture. The Eurostat shares refer to people who bought online in the last three months – not to online buyers in a wider sense and not to revenue. The three country values are examples and not a range; Austria is not the highest value in the EU-27. The language figure is a survey from autumn 2023 whose field period differs slightly between two official sources, and it counts at least one additional language besides the mother tongue, not foreign language skills in a narrower sense. Two dates are foreseeable: Eurostat plans the next update of the article on e-commerce statistics for February 2027 (Eurostat), and under Article 9(1) of the Geo-blocking Regulation the Commission reports on its evaluation every five years – the first report was due by 23 March 2020, and following that cycle the next deadline falls on 23 March 2030 (Regulation (EU) 2018/302, Article 9(1)). That is a deadline, not an appointment.

The annotation belongs to the structure, not to the polish

hreflang is not a task for the week before launch. The annotation describes a structure, and anyone describing the structure after the fact often describes something that was not intended that way: two versions of the same language without a catchall URL, a country domain without a return link, a selection page that was not planned. Anyone writing down the language matrix before the first translation – which versions exist, under which addresses, with which fallback page – usually has the annotation done with manageable effort afterwards and only needs to keep checking it. That is exactly how we set it up as part of technical search engine optimization: record the matrix, settle on one method, generate centrally, check on every release. Anyone changing the content system anyway plans both together – the move to TYPO3 14 LTS is a fitting moment to put the language versions in order once instead of carrying them along.