3.2 – When it does not work

Never two pages of one language

A group of translations holds at most one page per language. If two German pages carry the same translationKey, that is a contradiction: the plugin skips the link and warns at build time.

That happens more often than one would think — when a key travels along with a copied page, for instance.

Filtered pages are not there

The linking runs after the build’s filters have run. A page with draft: true, an unlisted one, or one removed by publishLanguages does not exist for the switcher — it does not show it.

That is correct, and it looks like a bug

Writing a translation, marking it as a draft and then wondering why the switcher does not know it means looking for the fault in the wrong place.

For hreflang it only holds at the default order

The switcher reads the list after every filter, so a draft is always missing there. hreflang draws from a list this plugin’s own filter fills — and a filter running after it removes pages that are already recorded. With the defaults the order is right; set order below 50 and drafts turn up in hreflang (1.3).

Seeing what was found

Every page carries the result with it:

fileData.multilanguage = {
  lang: "de",
  baseSlug: "notizen/kaffee",
  source: "folder",
  translationKey: "kaffee",
  translations: { en: "en/notes/coffee" }
}

The same thing sits in the built HTML on the switcher as data-translations — the fastest way to look without changing anything: open the page, inspect the element.

If source shows a different way than expected, the fault is in the detection (2.2), not in the linking.

The most common causes

Observation	Cause
Switcher goes to the start page	No link found — with switcher.missing: home the normal case
Switcher does not show the language at all	switcher.missing: hide
Two pages link up wrongly	Identical base paths where no translation was meant — restrict linking or rename
The link seems to work one way only	It is always mutual; if it looks one-sided, these are two separate groups