Languages, regions and search engines (hreflang)

When a page exists in more than one language or region, search engines need to know that the versions belong together, so that someone in Germany is shown the German page and someone in Switzerland the Swiss one. This is done with hreflang: a list of links on every version that names each language and its address.

CMS Orbit builds this list for you. You don't add or edit hreflang anywhere. This article explains what it builds, so you can check that it's right and fix it when SEO health says it isn't.

What a version is

Two pages are versions of each other when one was made from the other with Copy to another region or language. See Copy a page to another region or language. The copy stays linked to its source, and CMS Orbit lists every linked copy in the same environment as a version of the page.

A page you create from scratch in another region is a new page, not a version, even if it has the same name and address. If two pages should be linked, make one a copy of the other.

What CMS Orbit adds to each version

For a page with versions, each version gets a link to every version, including itself, plus one called x-default:

• The language code is the code of the version's locale, such as de-DE. It must be a valid code (see below), or search engines ignore the link.
• The address is built from Configuration › Domains and the region's address prefix, the same way as the page's canonical link.
• x-default is the version for visitors who don't match any language, such as someone in France. It is the version in the Default region set in SEO › Settings, in that region's main language. When the default region has no version of the page, the next region that has one is used.

The links appear in two places, both made for you:

• in the page's metadata, which your website adds to the page with CMS Orbit's SDK;
• in the sitemap, for every page listed there.

Which versions are left out

A version is only linked when it is:

• published: a draft is not linked until it goes live;
• visible to search engines: a version set to hide from search engines isn't linked from the others, and has no hreflang links of its own;
• at an address: a region without a website address can't be linked.

Environments search engines can't see, which is every environment except Production, show no hreflang at all. The checks still run there, so you can fix pages before they go live.

Valid language codes

A code is a language, with a country if the version is for one country:

• Language only: en, ga, de
• Language and country: de-DE, de-CH, fr-CH
• With a script or an area, rarely needed: zh-Hant-TW, es-419 for Spanish in Latin America

Codes use a hyphen, not an underscore. de_DE, german and de-Germany are not valid. Each region's locales are added in Configuration › Environments, where you pick the language and country from a list, so the code is valid. It can't be changed afterwards, because websites ask for content by it.

Checking that it's right

SEO › Health has a Languages card with every problem found. Errors and warnings lower the page's score, notes don't. In the editor, the page's SEO tab shows the same checks, and under Languages and regions it lists every version of the page with its code, region, address and state.

Why these errors are rare, and how they still happen

Most hreflang mistakes on other websites come from links typed by hand. In CMS Orbit nobody types them, so the usual ones can't happen:

• The links are built from the versions: a version can't be forgotten, and two versions can't disagree about each other, because every version gets the same list.
• Language codes are picked from a list: a new locale always has a valid code, and each code can only be used once in a region.
• Addresses come from the domain settings: a language link always uses the same address as the page's canonical and the sitemap.

The checks are still worth having, because the settings around the links can change:

• Older locales made before codes were checked can still have a code such as de_DE.
• Two regions can each choose the same code, such as de in Germany and in Switzerland.
• Two regions on one domain without an address prefix end up at the same address.
• A redirect added when a page moved can stay behind after the page moves back, and send visitors away from a live version.
• Hiding a page from search engines, or pointing its canonical elsewhere, takes it out of the links, sometimes on purpose and sometimes not.

So when everything is set up, you should rarely see an error here. When you do, it's usually one of the changes above.

What each check means and how to fix it

One-click fixes

Three checks can be fixed in one click. Open the issue in SEO › Health, read what the fix does, and choose the button:

• Turn off the redirect: the redirect stays in SEO › Redirects, turned off, so you can turn it back on. It takes effect straight away. Turning redirects on and off needs permission to manage redirects.
• Let search engines find it: turns off Hide from search engines for the page.
• Remove the canonical: clears the page's canonical, so the page points to itself again.

The last two change the page's draft, like the other fixes in SEO health, and go live with the page's next publish. None of them run by themselves: hiding a page and pointing its canonical elsewhere are often done on purpose, so a person decides. Every change is recorded in the page's history or the audit log.

As with other checks, each issue can be assigned to someone or left as it is with a reason.

Checking the live website

The checks above look at what CMS Orbit sends. CMS Orbit also checks that your website really shows it. About once a day it loads each published page in Production from the live website, reads its hreflang and canonical links and compares them with what they should be. Choose Check live website in a page's SEO tab to check that page straight away.

Only pages on a verified domain are checked. The check announces itself as "CMS Orbit SEO check" and reads only the start of each page, so it doesn't slow your website down.

Common questions

Why isn't my page linked to its version in another region? Most often the other page was created from scratch rather than copied, so they aren't versions of each other. Otherwise it isn't published yet, or is hidden from search engines. The page's Languages and regions list shows which.

Do I need a version in every region? No. Only the versions that exist are linked. SEO health notes regions where a page isn't published, but that doesn't lower the score.

Can I change the hreflang links by hand? No. They follow the versions, so change the versions instead: copy, publish, hide or move a page, and the links follow.

Which region should be the default? The one that serves visitors from elsewhere best, often your main market or the version in English. Set it in SEO › Settings under Default region.