Hreflang implementation: a checklist for flawless execution

Hreflang Implementation: A Checklist for Getting It Right

Implement hreflang based on the scope of your site: for large sites with more than a few hundred URLs, use an XML sitemap; for smaller sites, the HTML head; and for PDFs and other non-HTML resources, an HTTP header. Immediately check three things: reciprocity of links across all language versions, self-reference in rel=canonical tags, and the correctness of your language and region ISO codes. Without these three checks, no amount of hreflang markup will do you any good.

In short:

• If your website has more than a few hundred URLs, using an XML sitemap for hreflang implementation is recommended, since it allows for automated maintenance.
• For smaller sites with up to ten URLs, a simple HTML head solution works, while PDFs or non-HTML content should use HTTP headers.
• On multilingual sites, you must ensure reciprocal links between every version, including a self-reference on each page, otherwise the system won't be validly recognized.
• Common implementation mistakes include missing reciprocal links, conflicts with canonical tags, and incorrect language or region codes, any of which can completely cancel out hreflang's SEO effect.
• For large projects, it makes sense to automate hreflang within the build process or CMS, since manual management quickly becomes unmanageable and risky.

Table of Contents

• What hreflang actually tells search engines
• Three implementation methods: how to choose the right one
• Code examples and how to verify it works
• The most common implementation mistakes and quick fixes
• The role and correct use of hreflang="x-default"
• Why hreflang and canonical need to tell the same story
• Automation and regular checks for long-term stability
• When to do this yourself, and when to call in an expert
• What most often goes wrong in practice on multilingual projects
• Why it makes sense to leave hreflang implementation to a developer, not a plugin
• Sources
• Frequently asked questions

What hreflang actually tells search engines

Hreflang is a signal, not a command. Google and other search engines treat the tag as a strong hint about which language- or region-specific URL to show a given user, not as a binding rule. If another version of a page is technically better, faster, or more authoritative, a search engine can display it instead, despite your tag.

The syntax is based on two standards. Language is marked with an ISO 639-1 code (for example, "sl" for Slovenian, "de" for German), and region with an ISO 3166-1 Alpha-2 code (for example, "AT" for Austria, "CH" for Switzerland). The combination "de-AT" means a German-speaking audience in Austria, while a standalone "de" covers all German-speaking users regardless of country. This distinction is often overlooked and leads to a misinterpreted audience.

Every language version needs a tag pointing back to itself. This is called self-reference, and it's the foundation of the entire system. Hreflang, by definition, requires a fully reciprocal matrix. Every page in the cluster needs links to every other page in the cluster, including itself.

Here's what that looks like in practice, for a page with three language versions:

• the Slovenian page (sl-SI) needs links to itself, to the English version, and to the German version,
• the English page (en) needs links to itself, to the Slovenian version, and to the German version,
• the German page (de) needs links to itself, to the Slovenian version, and to the English version.

Miss just one direction, and the entire cluster becomes unreliable. Hreflang isn't needed when a site only offers content in one language for one region, or when the differences between language versions are purely cosmetic (just a currency symbol, say, with no translation). In these cases, adding hreflang tags just adds complexity with no benefit.

Three implementation methods: how to choose the right one

There are three ways to write hreflang tags, and each has its place depending on the size and type of site.

1. HTML head. Insert <link rel="alternate" hreflang="..."> tags into the <head> of every HTML page. This method is the most intuitive and is supported by every CMS, but on large sites it quickly becomes unmanageable, since you have to maintain the matrix on every individual page.
2. XML sitemap. All the links between language versions are written centrally, in xhtml:link elements within the sitemap file. This is the recommended method for large sites, since it removes the need to edit hundreds or thousands of individual pages and substantially reduces the risk of human error during maintenance.
3. HTTP header. For resources with no HTML head, such as PDF documents, use the Link HTTP header. This is the only method that works for documents and files where no HTML head exists.

For smaller sites with up to a few dozen pages, the HTML head is entirely manageable and the fastest to set up. Once the number of URLs exceeds a few hundred — especially for multilingual online stores with thousands of product pages — an XML sitemap becomes the only sensible choice, since it allows for automated generation through your CMS or build process.

Some sites combine methods: product pages and categories are managed through the sitemap, while static pages (about, contact) use the HTML head, since they rarely change. This is a reasonable approach, as long as the methods don't conflict. If the same URL appears in both the sitemap and the head with different values, the search engine receives contradictory signals and may disregard the entire cluster.

Code examples and how to verify it works

In the HTML head, each language version needs a separate <link> element for every other version, including itself:

<link rel="alternate" hreflang="sl-SI" href="https://example.si/page/" />
<link rel="alternate" hreflang="de-AT" href="https://example.si/de-at/page/" />
<link rel="alternate" hreflang="x-default" href="https://example.si/page/" />

In an XML sitemap, the same logic is written using xhtml:link elements inside each <url> block, allowing the entire matrix to be managed centrally in one place. For PDF documents or other non-HTML resources, use an HTTP header in the form Link: <https://example.si/de-at/document.pdf>; rel="alternate"; hreflang="de-AT".

After implementation, check the following steps in order:

• every URL in a hreflang tag needs to return a 200 status, not a 404 or a redirect,
• every link needs to be reciprocal — check this with a tool like the DiagnoSEO hreflang checker, which reads HTML, HTTP headers, and the sitemap all at once,
• check the "International Targeting" report in Google Search Console, where errors and warnings are displayed,
• for large sites, use Screaming Frog to crawl in bulk and export every hreflang link into a table.

When a tool reports an error, fix the missing return links first, since these are the fastest to invalidate the entire cluster.

The most common implementation mistakes and quick fixes

Nearly seven out of ten sites with a hreflang implementation have at least one technical error. An Ahrefs analysis found that 67% of sites using hreflang suffer from at least one mistake, suggesting this is one of the most underrated technical SEO problems.

The most common mistakes are:

• missing return links – page A points to page B, but page B doesn't point back to page A; this is the most common mistake, and the only one capable of invalidating the entire cluster,
• conflict with the canonical tag – hreflang points to a URL whose canonical is set to a different page, which the search engine reads as a contradictory signal,
• redirect chains – a hreflang tag points to a URL that then redirects to another address, instead of the final destination,
• incorrect language or region codes – typical mistakes include "sl-SL" instead of "sl-SI," or using uppercase letters for the language code,
• staging or test URLs – leftovers from a development environment that weren't updated at launch,
• URL parameters in hreflang – tracking parameters (such as ?utm_source=) cause the search engine to no longer recognize the page as equivalent to the canonical version.

The fix always follows the same order: first align the canonical tags, then correct the codes, and finally re-check reciprocity. After every change, rerun a check with DiagnoSEO or Screaming Frog, since fixing one error often reveals the next.

Pro tip: For large online stores, check only a sample of 50 to 100 random product pages instead of the entire catalog. If the sample comes back error-free, the odds that the whole sitemap is correct are very high, since generation errors tend to repeat systematically.

The role and correct use of hreflang="x-default"

The hreflang="x-default" tag tells the search engine and browser which page to show a user who doesn't match any of the specified language-region combinations. Google recommends x-default as a safety net, not as a substitute for missing translations.

The most sensible use is on the page in the site's original language, or on a global landing page where the user picks their own version. Google explicitly notes that x-default isn't meant for translations — it's simply there to direct visitors who don't fall into any specific category.

Two mistakes come up more often than you'd expect:

• x-default points to a URL that then redirects elsewhere, instead of an actually accessible page,
• x-default is missing entirely, leaving users from untargeted regions with no clear default experience.

Checking this is simple: visit the site with a VPN set to a country that isn't one of your target markets, and see which page loads. If you get a 404 error or an unexpected redirect, x-default isn't set up correctly.

Why hreflang and canonical need to tell the same story

A conflict between hreflang and rel=canonical is one of the most common reasons search engines ignore an entire cluster. The rule is simple: every language version needs a canonical that points to itself, not to another language version or to a "main" version in a single language.

The audit process has three steps:

1. List every canonical value for each URL in your hreflang matrix — easiest done by crawling with Screaming Frog or a similar tool.
2. Compare the canonical values against the hreflang matrix. Every URL that appears in a hreflang tag needs a canonical pointing to itself. If the Slovenian page has a canonical pointing to the English page, the search engine reads the Slovenian page as just a duplicate, and ignores the hreflang tag on it.
3. Fix mismatches at the source. Don't just fix the symptom on one page — check whether the error is systemic (an incorrect default setting in a CMS template, say), since in that case it shows up on every page of that type.

This mistake is especially common on online stores, where the content management system automatically sets the canonical to the "main" language, regardless of which language version the visitor is actually viewing. The result is that all the foreign-language versions quietly vanish from the index, while the hreflang tags remain technically correct but have no effect. A regular audit of canonical values should be part of every maintenance cycle, not a one-time project.

Automation and regular checks for long-term stability

A hreflang implementation isn't a one-time project — it's a system that needs ongoing maintenance. Every new page, new language, or change to your URL structure can break the entire matrix if the process isn't automated.

For medium and large sites, an XML sitemap is the only realistic long-term solution, since it's generated automatically with every publish or content change. When building or redesigning a website, it makes sense to build hreflang generation into the build process or the CMS, so that an editor adding a new language version doesn't need to worry about the technical syntax.

Recommended operational practice includes:

• automated sitemap generation with every page publish, move, or deletion, with no manual intervention,
• reciprocity checks as part of the CI/CD process, so an error in the hreflang matrix blocks a change from being published until it's fixed,
• a monthly review in Google Search Console's "International Targeting" report, where newly emerging errors appear within a few weeks,
• a quarterly deep audit with Screaming Frog or a tool like DiagnoSEO, covering the entire site rather than just a sample.

Pay special attention to URL parameters. Tracking parameters like ?utm_campaign= or session IDs should never appear in hreflang values, since the search engine then treats every parameter combination as a separate URL, which drastically inflates the size of the matrix and burns crawl budget on unnecessary variations of the same page.

A sudden spike almost always means a recent change to the site broke part of the matrix, and acting quickly prevents errors from piling up.

For online stores with a multilingual offering, it's also worth separately tracking managing a multilingual structure for foreign markets, since decisions about URL structure (subdomains, subfolders, or separate domains) directly affect the complexity of the hreflang matrix.

When to do this yourself, and when to call in an expert

Handling this in-house makes sense when a site has up to a few dozen pages and the CMS allows easy editing of the <head> element, through a plugin or a built-in template editor, say. In that case, it's enough for one person to follow a clear process: list every language version, write out the matrix in a table, add the tags, and verify with a free tool.

A checklist for a first audit includes:

• listing every URL by language and region,
• checking that every URL has the correct ISO code,
• checking for full reciprocity across every version,
• checking alignment with the canonical tags,
• testing in Google Search Console after publishing.

Once the number of URLs exceeds a few hundred, when it's an online store with dynamically generated product pages, or when integration with an external translation management system is needed, manual maintenance becomes risky and time-consuming. In these cases, it's worth commissioning the technical implementation from a provider who can automate the generation and set up monitoring. Moxy-web builds custom websites and online stores, including integrations with existing systems, which allows hreflang logic to be built directly into the CMS or build process, instead of manually fixing hundreds of pages.

What most often goes wrong in practice on multilingual projects

Working on multilingual web projects, the same mistake comes up surprisingly often: teams set up translations first and only think about hreflang afterward, instead of planning URL architecture and language structure together from the start. The result is that hreflang implementation ends up as a retrofit on an already-built structure, where aligning it with canonical tags is much harder.

Another thing teams regularly underestimate is maintenance after launch. The initial implementation is often technically flawless, but problems build up months later, when new product categories or a new language get added and no one updates the entire matrix. Making reciprocity checks part of the regular workflow, rather than a one-time project, is the difference between a website that holds on to its international visibility long-term and one that slowly loses it for no obvious reason.

The biggest misconception we run into is the belief that hreflang is a "set it and forget it" setting. In reality, it's a living system that has to change every time the site's structure changes.

— Ziga

Why it makes sense to leave hreflang implementation to a developer, not a plugin

For businesses running a multilingual website or online store, the difference between a generic plugin and custom-built code is that a plugin only writes the tags, while real technical control only happens once hreflang logic is built directly into the site's architecture. Moxy-web doesn't use pre-built platforms — it develops the code itself, which means the hreflang matrix, self-referencing, and alignment with canonical tags can be built directly into the CMS template, without the technical constraints of a third-party plugin. When building or redesigning an online store, this means the sitemap and language links are generated centrally and automatically with every content change, instead of an editor fixing them by hand.

If you're planning a new multilingual website, online store, or web application and want hreflang to work correctly from day one, check out the offering on the Moxy-web homepage and ask about an individual solution tailored to your market structure.

Sources

For a deeper look at the technical claims in this article, see the following sources:

• Ahrefs: hreflang study
• Hreflang — Wikipedia
• Google Search Central — Localized versions

Frequently asked questions

What is hreflang implementation, and why is it needed?

Hreflang implementation is the process of adding tags that tell search engines which language or regional version of a page matches a given user. Without it, a search engine might show the wrong language version, or treat equivalent pages as duplicate content.

Which implementation method is best for an online store?

For online stores with a multilingual offering, an XML sitemap is the most practical method, since it allows the entire matrix to be managed centrally and automatically, without editing every product page individually. The HTML head remains a sensible choice only for smaller sites with up to a few dozen URLs.

How often should I check that my hreflang tags are working?

A monthly review of the "International Targeting" report in Google Search Console is recommended, along with a quarterly deep audit using Screaming Frog or a tool like the DiagnoSEO hreflang checker. A sudden spike in errors almost always means a recent site change broke part of the matrix.

What happens if hreflang and canonical aren't aligned?

If the canonical points to a different language version instead of itself, the search engine treats the page as a duplicate and ignores its hreflang tag. This is one of the most common reasons international pages vanish from the index despite technically correct hreflang tags.

How much does a hreflang implementation cost at Moxy-web?

The price depends on the scope of the site and the implementation method chosen, so it's assessed case by case. Current information and inquiries can be found on the Moxy-web homepage.

Recommended

• How to Set Up a Multilingual Website for Foreign Markets