Hreflang & Switching

Multilingual Chinaski sites signal to search engines which language each page is in, and give visitors a visible switcher in the page header. Both come from the same source: the computed hreflang set per page. This page explains how translations are paired, when alternates appear, and how the built-in language switcher behaves.

What hreflang is generated for

With your active languages configured and a Site URL set, every page and post carries <link rel="alternate" hreflang="…"> entries for itself in each language, in the built HTML head. Two guards apply:

• A monolingual site has no hreflang (there’s nothing to switch between).
• Alternates are only generated when your Site URL setting points at your real domain, because they must be absolute links.

How translations are paired

To link a page to its translations, the builder has to know which pages are “the same content” in different languages.

• Pages pair by a translation key first, so translations that use localized URLs (an /en/about page whose Spanish version is /es/sobre) are still correctly linked. If no translation key exists for the page, same-slug matching is the fallback.
• Posts pair by identical slug across languages.

Only languages that actually have a matching version are listed, and an x-default entry points to the default-language variant whenever one exists in the set: the standard signal for Search that says which version to show when no specific language matches the user.

When a translation doesn’t exist

Your switcher can’t just vanish on untranslated pages. When a post has no translated twin with the same slug, the builder falls back to language roots: each language’s homepage URL. So on a multilingual site every page or post includes the language switcher; choosing another language from one of those takes you to that language’s front page rather than a missing copy of the article.

The on-page switcher

The default theme renders a small language switcher in the header: a static list of the site languages, no JavaScript involved:

• The current language is displayed as text (not a link), marked for assistive tech as the current selection.
• Every other language with an available version links to that version at the language’s own URL, per-language subdomains or path segments, matching what a visitor should navigate to.
• The fallback above applies: on a multilingual site with no translations for the page you’re viewing, the switcher still links to the other languages’ home pages.

Because the switcher is driven by the same computation that produces the hreflang tags, what search engines see and what a visitor can click is always the same list. Custom themes decide their own header markup; the switcher ships with the default theme’s header and can be added to any theme.

Getting the alternates right: practical tips

• Set your Site URL, without it, no alternates are generated (they must be absolute).
• Give each translation its place under the same content in the admin (or matching slug for posts) so the pairing is complete.
• For pages whose slugs differ per language (localized slugs), use the translation key feature so alternates match; without it, same-slug fallback might fail to pair them.
• Pairing rules apply per page/post: a post in English with no Spanish twin shows root links in the switcher and no specific hreflang alternates to the post itself, while a fully translated pair shows per-article alternates.