The challenge
Most multilingual sites get one of three things wrong: duplicate content flags from missing hreflang tags, orphaned pages from incomplete reciprocal links, or schema that ignores language entirely. Wishfy needed a four-language site (English, Dutch, German, French) that got all three right from day one — not as a retrofit, but as a core architectural decision.
The constraint: a single domain (`wishfy.ai`), no subdomains, no country-code TLDs. Everything lives under subdirectories: `/en/`, `/nl/`, `/de/`, `/fr/`.
Subdirectory strategy
Subdirectories beat subdomains for multilingual SEO when you're building domain authority from scratch. All link equity flows to one domain. All crawl budget stays in one property. Google Search Console shows one unified view.
The routing layer uses Astro's `[lang]` dynamic parameter. Every page route starts with `[lang]/` — services, work, blog, legal. The root `/` redirects to the default locale (`/en/`). No content lives outside a language subdirectory.
hreflang implementation
Every page emits a complete set of hreflang `<link>` tags in the `<head>` — one for each language the page exists in, plus an `x-default` pointing to the English version. The implementation uses each content entry's `translationKey` to find its counterparts across locales.
Reciprocity is enforced at build time: if `/en/services/seo` declares a Dutch alternate, `/nl/services/seo` must declare the English alternate back. Broken reciprocity is the number-one hreflang failure mode, and we catch it before deployment.
The hreflang tags use full URLs with the canonical domain — `https://wishfy.ai/nl/services/seo`, not relative paths. Google's documentation is explicit: hreflang values must be fully qualified.
Per-language sitemaps
The site generates five sitemaps: one per language (`sitemap-en.xml`, `sitemap-nl.xml`, `sitemap-de.xml`, `sitemap-fr.xml`) plus a sitemap index (`sitemap-index.xml`) that references all four. Each language sitemap contains only URLs for that locale, with `<xhtml:link>` alternates pointing to the other language versions.
This structure gives search engines a clear signal: here are all the English pages, here are all the Dutch pages, and here's how they relate. No ambiguity, no mixed-language sitemap noise.
Content collection architecture
Content lives in locale-prefixed directories within Astro's content collections: `services/en/seo.mdx`, `services/nl/seo.mdx`. Each entry carries a `locale` field and a `translationKey` that links translations together. The schema enforces this at the type level — you can't create a content entry without declaring its language.
This architecture means content queries are always locale-aware. The services index for Dutch shows only Dutch entries. The blog for German shows only German posts. There's no runtime filtering guesswork — the data model makes it impossible to mix languages accidentally.
Schema inLanguage coverage
Every JSON-LD schema block on the site includes an `inLanguage` property matched to the page locale. The Organization schema on `/de/` declares `"inLanguage": "de"`. The Service schema on `/fr/services/geo` declares `"inLanguage": "fr"`. This tells both search engines and LLMs exactly which language context each structured data block belongs to.
The outcome
Four languages. One domain. Zero duplicate content flags in Google Search Console. 100% hreflang reciprocity verified at build time. Per-language sitemaps with proper alternate annotations. Schema that knows what language it speaks. This is what multilingual SEO architecture looks like when it's built into the foundation instead of bolted on after launch.