🌐 Fix doc localization routing, links, and SEO tags

- Doc links, header, redirects, and pagination dropped the language or 404'd
- Render markdown links through a lang-aware component so prerendered HTML is correct
- Match only supported languages; drop the duplicate /en prefix
- Untranslated pages fall back to English with a notice
- Add a language switcher so translations are reachable
- Set html lang per language and remove duplicate canonical/OG tags

Author: SnaveSutit

src/app.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="en">
+<html lang="%lang%">
 	<head>
 		<meta charset="utf-8" />
 		<link rel="icon" href="%sveltekit.assets%/images/animated_java_icon.svg" />

src/hooks.server.ts

@@ -0,0 +1,7 @@
+import { DEFAULT_LANGUAGE } from '$lib/docs/docs'
+import type { Handle } from '@sveltejs/kit'
+
+export const handle: Handle = ({ event, resolve }) => {
+	const lang = event.params.lang ?? DEFAULT_LANGUAGE
+	return resolve(event, { transformPageChunk: ({ html }) => html.replace('%lang%', lang) })
+}

src/lib/docs/docLayout.svelte

@@ -0,0 +1,16 @@
+<!--
+	@component
+	mdsvex layout for every doc page. Its module exports replace the matching
+	markdown elements, so `a` makes doc links follow the current language.
+-->
+<script module lang="ts">
+	export { default as a } from './docLink.svelte'
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+
+	const { children }: { children?: Snippet } = $props()
+</script>
+
+{@render children?.()}

src/lib/docs/docLink.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import { page } from '$app/state'
+	import { localizeHref } from '$lib/docs/docs'
+	import type { Snippet } from 'svelte'
+	import type { HTMLAnchorAttributes } from 'svelte/elements'
+
+	interface Props extends HTMLAnchorAttributes {
+		children?: Snippet
+	}
+
+	const { href, children, ...rest }: Props = $props()
+</script>
+
+<a href={localizeHref(href ?? '', page.params.lang)} {...rest}>{@render children?.()}</a>

src/lib/docs/docs.ts

@@ -1,21 +1,53 @@
-import { resolve } from '$app/paths'
 import type { Component } from 'svelte'
 
 const MODULES = import.meta.glob('/src/docs/**/*.md')
 
 export const DEFAULT_LANGUAGE = 'en'
-export const SUPPORTED_LANGUAGES = ['de', 'en', 'nl', 'ru', 'uk', 'zh-cn']
+export const SUPPORTED_LANGUAGES = ['en', 'de', 'nl', 'ru', 'uk', 'zh-cn']
+/** Languages served under a `/<lang>` prefix. The default language has no prefix. */
+export const PREFIXED_LANGUAGES = SUPPORTED_LANGUAGES.filter(lang => lang !== DEFAULT_LANGUAGE)
 
-export function getDocModule(lang = 'en', path: string) {
-	const normalizedLang = SUPPORTED_LANGUAGES.includes(lang) ? lang : DEFAULT_LANGUAGE
-	const key = `/src/docs/${path}/${normalizedLang}.md`
+type DocModule = () => Promise<{ default: Component; metadata?: Record<string, any> }>
 
-	const mod = MODULES[key] ?? MODULES[`/src/docs/${path}/${DEFAULT_LANGUAGE}.md`]
+/** Every doc page path relative to `/docs` (e.g. `nodes/cubes`) that has at least one language file. */
+export const DOC_PATHS = [
+	...new Set(
+		Object.keys(MODULES).map(key =>
+			key.replace(/^\/src\/docs\//, '').replace(/\/[^/]+\.md$/, '')
+		)
+	),
+]
 
-	return mod as () => Promise<{ default: Component; metadata: Record<string, any> }>
+/**
+ * Finds the doc module for `path` in `lang`, falling back to the default language.
+ * `translated` is false when the fallback was used.
+ */
+export function getDocModule(path: string, lang: string) {
+	const translatedModule = MODULES[`/src/docs/${path}/${lang}.md`] as DocModule | undefined
+	if (translatedModule) return { load: translatedModule, translated: true }
+
+	const fallback = MODULES[`/src/docs/${path}/${DEFAULT_LANGUAGE}.md`] as DocModule | undefined
+	if (fallback) return { load: fallback, translated: false }
+}
+
+/** Prefixes a site-absolute `/docs` path with `lang`. Every other href is returned unchanged. */
+export function localizeHref(href: string, lang: string | undefined): string {
+	if (!lang || lang === DEFAULT_LANGUAGE || !/^\/docs(?=[/#?]|$)/.test(href)) return href
+	return `/${lang}${href}`
+}
+
+/** Removes a leading `/<lang>` prefix and any trailing slash from a pathname. */
+export function stripLanguage(pathname: string, lang: string | undefined): string {
+	let path = pathname
+	if (lang && lang !== DEFAULT_LANGUAGE && path.startsWith(`/${lang}/`)) {
+		path = path.slice(lang.length + 1)
+	}
+	if (path.length > 1 && path.endsWith('/')) path = path.slice(0, -1)
+	return path
 }
 
-export function docHref(path: string, lang: string): string {
-	const prefix = lang === DEFAULT_LANGUAGE ? '' : `/${lang}`
-	return resolve(`${prefix}/${path}`)
+/** The name of `lang` written in `inLang`, e.g. `Deutsch` for `de` by default, or `German` in `en`. */
+export function getLanguageName(lang: string, inLang = lang): string {
+	const name = new Intl.DisplayNames([inLang], { type: 'language' }).of(lang) ?? lang
+	return name.charAt(0).toLocaleUpperCase(inLang) + name.slice(1)
 }

src/lib/docs/rehypeDocLinks.ts

@@ -0,0 +1,4 @@
+import { PREFIXED_LANGUAGES } from '$lib/docs/docs'
+import type { ParamMatcher } from '@sveltejs/kit'
+
+export const match: ParamMatcher = param => PREFIXED_LANGUAGES.includes(param)

src/params/lang.ts

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import '$lib/styles/global.css'
+	import '$lib/styles/minecraftUI.css'
+
+	const { children } = $props()
+</script>
+
+{@render children?.()}

src/routes/[[lang=lang]]/+layout.svelte

@@ -8,13 +8,37 @@
 	import { backOut } from 'svelte/easing'
 	import { fade, fly } from 'svelte/transition'
 
+	const siteUrl = 'https://animated-java.dev'
+	const pageTitle = 'Animated Java'
+	const pageDescription = 'Effortlessly craft complex animations for Minecraft: Java Edition'
+	const socialImage = `${siteUrl}/images/animated_java_icon.svg`
+
 	let startTransition = $state(false)
 
 	onMount(() => {
 		startTransition = true
 	})
 </script>
 
+<svelte:head>
+	<title>{pageTitle}</title>
+	<meta name="description" content={pageDescription} />
+	<link rel="canonical" href={siteUrl} />
+
+	<meta property="og:type" content="website" />
+	<meta property="og:site_name" content="Animated Java" />
+	<meta property="og:title" content={pageTitle} />
+	<meta property="og:description" content={pageDescription} />
+	<meta property="og:url" content={siteUrl} />
+	<meta property="og:image" content={socialImage} />
+	<meta content="#00ACED" data-react-helmet="true" name="theme-color" />
+
+	<meta name="twitter:card" content="summary_large_image" />
+	<meta name="twitter:title" content={pageTitle} />
+	<meta name="twitter:description" content={pageDescription} />
+	<meta name="twitter:image" content={socialImage} />
+</svelte:head>
+
 <div class="home-page-shell">
 	<div class="bg-layer bg-base" aria-hidden="true"></div>
 	<div class="bg-layer bg-aurora bg-aurora-a" aria-hidden="true"></div>