Generate the hreflang tags for your versions

How to use the tool

Write one line per version of the same page: the language code (en, fr, fr-BE...), a separator, then the full address of that version. Separate groups of equivalent pages with an empty line: a product page and its translations form one group, the “about” page and its translations form another. Click “Generate the tags” to see the findings, then three outputs to copy or download.

The “Load an example” button fills two groups of four and three versions, with an x-default tag, so you can see the result. Each group produces a single block: the same one must appear on every page of the group, including on each version for itself.¹

What the tool writes

Google accepts three locations and treats them the same way: the HTML head, the HTTP headers and the XML sitemap. There is no benefit in combining them and upkeep gets heavier: choose one.¹ The tool writes all three so you can keep the one that suits your site.

The head tags are link elements, one per version. Headers mostly serve files that have no head, such as PDFs: the address sits between angle brackets and the items are separated by a comma.¹ In the sitemap, each page is a url entry with its loc and one xhtml:link element per version, which needs the xhtml namespace.¹ Special characters in addresses (&, for example) are escaped for HTML and XML.

<link rel="alternate" hreflang="en" href="https://www.example.com/shoes/" />
<link rel="alternate" hreflang="fr" href="https://www.example.com/fr/chaussures/" />
<link rel="alternate" hreflang="x-default" href="https://www.example.com/shoes/" />

Link: <https://www.example.com/guide.pdf>; rel="alternate"; hreflang="en",
      <https://www.example.com/fr/guide.pdf>; rel="alternate"; hreflang="fr"

What the tool checks

Google requires that each version cites itself and all the others. If page X points to Y, Y must point to X, otherwise the annotations may be ignored.¹ The tool builds each block from the whole group, so return links are reciprocal by construction, and the green finding reminds you of it. It does refuse to put the same address in two groups, because the page would receive two different blocks.

It then checks the addresses: they must be complete, with the protocol, and an address like /page or //host/page will not do.¹ It also rejects addresses with a space, a quote, an angle bracket or a fragment, which would break a tag or a header. One code can point to a single address per group: the first line is kept, the next one is flagged. An exact duplicate line is merged, and a group with a single version is ignored.

Language and region codes

The code starts with an ISO 639-1 language, optionally followed by an ISO 15924 script (zh-Hant) and an ISO 3166-1 alpha 2 region (en-GB). Case does not matter to Google, but the region is written in capitals by convention: the tool rewrites fr-be as fr-BE.¹

Several frequent mistakes are caught. A country code alone does not name a language: “be” means Belarusian, and for Belgium you must write nl-BE, fr-BE or de-BE. Codes such as es-419 are rejected, and reserved codes such as UK or EU are ignored.¹ An underscore (fr_FR) is not valid either. The validation uses the same method as the hreflang checker, based on the browser’s language and country data.

The x-default value

x-default is a reserved value: it names the fallback page when no language or region matches the visitor’s browser. Google suggests it, notably for a language or country selector, or for a home page that redirects by language. It is not mandatory.¹

Tick the option and the tool adds the line to each group. By default it reuses the first version of the group; enter a code (en, for example) to pick another one. If your fallback is a separate page, a language selector for instance, enter it as an x-default line: it receives its own block in the sitemap.

The limits of the tool

The tool visits no page: it formats what you enter. It cannot know whether the addresses respond, whether a redirect moves them or whether their canonical tag points elsewhere. Google also states that versions where only the template is translated, with an unchanged main content, may be seen as duplicates.¹

The same address under two codes (en and en-GB, for example) is flagged, as Google’s documentation does not cover that case. The generated sitemap may only contain addresses in the folder where it is hosted, or in its subfolders.¹

After generating

Once the tags are in place, run a page through the hreflang checker: it reads the alternatives online and checks their return codes and canonicals. If you chose the sitemap, the XML sitemap validator checks the file. To decide the architecture before tagging, the SEO consultant can support you.

Frequently asked questions