Improve example website

- Fix one-time home redirect based on the detected locale not working. - Fix the way it's rendered on mobile. - Improve website visuals and text to better explain the behaviour. - Change comments to better explain the usage and the reasoning behind it.
rinart73 · Jul 10, 2023 · be034c3 · be034c3
1 parent 9637cea
commit be034c3
Show file tree

Hide file tree

Showing 23 changed files with 377 additions and 153 deletions.
diff --git a/src/app.html b/src/app.html
@@ -7,6 +7,6 @@
 		%sveltekit.head%
 	</head>
 	<body data-sveltekit-preload-data="hover">
-		<div>%sveltekit.body%</div>
+		<div style="display: contents">%sveltekit.body%</div>
 	</body>
 </html>
diff --git a/src/components/HeadHrefLangs.svelte b/src/components/HeadHrefLangs.svelte
@@ -4,10 +4,13 @@
 	import { buildAlternateLinks } from '$lib/index.js';
 </script>
 
+<!-- Error pages shouldn't have hreflang -->
 {#if !$page.error}
+	<!-- Alternate links are generated on-demand. So we need to call the `buildAlternateLinks` -->
 	{#each buildAlternateLinks($page.data.LP).hreflang as [hreflang, href]}
 		<link rel="alternate" {hreflang} {href} />
 	{/each}
+	<!-- After they're generated you can reference them normally -->
 	<link rel="alternate" hreflang="x-default" href={$page.data.LP.hreflang.get(baseLocale)} />
 	<link rel="canonical" href={$page.data.LP.hreflang.get($page.data.locale)} />
 {/if}
diff --git a/src/components/Header.svelte b/src/components/Header.svelte
@@ -7,38 +7,57 @@
 
 <header>
 	<a href={getLocaleHomeHref($locale, $page.url)}>
-		<h1>{$LL.site.name()}</h1>
+		<h1>{$LL.site.name()} (demo)</h1>
 	</a>
 
 	<ul class="menu">
 		<li>
-			<a href="/{$locale}/about-project"
-				>{`${$LL.pageAbout.title()} (${$LL.header.incorrectUrl()})`}</a
+			<!-- An mismatched href that will be fixed and redirected. Don't do this. -->
+			<a class="link-hint link-hint--redirect" href="/{$locale}/about"
+				>{$LL.pageAbout.title()} (1)</a
 			>
 		</li>
 		<li>
-			<a href={href($page.data.LP, $locale, '/[l_about]')}>{$LL.pageAbout.title()}</a>
+			<!-- Normal localized href. Use `href` function when you know that the page is available for all locales
+                or when you specify the `fallbackLocales` argument. -->
+			<a
+				class="link-hint link-hint--success"
+				href={href($page.data.LP, $locale, '/[l_about]')}>{$LL.pageAbout.title()} (2)</a
+			>
 		</li>
 		<li>
-			<a href="/{$locale}/about-project/partial"
-				>{`${$LL.pagePartial.title()} (${$LL.header.incorrectUrl()})`}</a
+			<!-- English: A mismatched href that will be corrected.
+                Non-English: 404 error due to the page not being available for a requested locale.
+                Don't do this. -->
+			<a
+				class="link-hint"
+				class:link-hint--redirect={$locale === 'en'}
+				class:link-hint--error={$locale !== 'en'}
+				href="/{$locale}/about/english-only">{$LL.pageEnglish.title()} (3)</a
 			>
 		</li>
+		<!--  Try to use a requested locale. If it's not possible, don't show the element at all. -->
 		{@html wrapHref(
 			$page.data.LP,
 			$locale,
-			'/[l_about]/[l_partial]',
-			`<li><a href="%href%">${$LL.pagePartial.title()} (${$LL.header.onlyVisibleInEnglish()})</a></li>`
+			'/[l_about]/[l_english]',
+			`<li><a class="link-hint link-hint--vary" href="%href%">${$LL.pageEnglish.title()} (4)</a></li>`
 		)}
+		<!-- Try to use a requested locale. If it's not possible, use the `baseLocale` as a fallback instead. -->
 		{@html wrapHref(
 			$page.data.LP,
 			$locale,
-			'/[l_about]/[l_partial]',
-			`<li><a href="%href%">${$LL.pagePartial.title()} (${$LL.header.fallback()})</a></li>`,
+			'/[l_about]/[l_english]',
+			`<li><a class="link-hint ${
+				$locale === 'en' ? 'link-hint--success' : 'link-hint--fallback'
+			}" href="%href%">${$LL.pageEnglish.title()} (5)</a></li>`,
 			true
 		)}
+		<!-- Normal localized href -->
 		<li>
-			<a href={href($page.data.LP, $locale, '/[l_news]')}>{$LL.pageNews.title()}</a>
+			<a class="link-hint link-hint--success" href={href($page.data.LP, $locale, '/[l_news]')}
+				>{$LL.pageNews.title()} (6)</a
+			>
 		</li>
 	</ul>
 

diff --git a/src/components/LocaleSwitcher.svelte b/src/components/LocaleSwitcher.svelte
@@ -16,7 +16,7 @@
 		// select locale
 		setLocale(newLocale);
 
-		// run the `load` function again
+		// Run the `load` function again, including on server side (to fetch translated posts from DB for example).
 		invalidateAll();
 	};
 
@@ -31,8 +31,12 @@
 </script>
 
 <ul class="switcher">
+	<!-- Alternate links are generated on-demand. So we need to call the `buildAlternateLinks`.
+        Make sure to pass the $page.error. The error pages (such as 404) still need working locale switcher, but
+        it should point to the home pages. -->
 	{#each buildAlternateLinks($page.data.LP, $page.error).switcher as [lang, href]}
 		<li>
+			<!-- Add hash for better usability -->
 			<a class:active={lang === $locale} href="{href}{$page.url.hash}">
 				{lang}
 			</a>

diff --git a/src/hooks.server.ts b/src/hooks.server.ts
@@ -9,7 +9,7 @@ loadAllLocales();
 const L = i18n();
 
 export const handle: Handle = async ({ event, resolve }) => {
-	// initialize Localize URL library
+	// initialize Localize URL library on server
 	initLocalizeUrl({
 		baseLocale,
 		locales
@@ -19,9 +19,10 @@ export const handle: Handle = async ({ event, resolve }) => {
 	// track the first visit for language detection
 	let hasVisited = true;
 	// only count translateable part of the website (exclude API)
-	const isTranslateablePath = (event.route.id ?? '').startsWith('/[[lang=lang]]');
-	if (!hasVisited && isTranslateablePath) {
+	if ((event.route.id ?? '').startsWith('/[[lang=lang]]')) {
 		hasVisited = event.cookies.get('visited') === '1';
+	}
+	if (!hasVisited) {
 		event.cookies.set('visited', '1', { path: '/' });
 	}
 

diff --git a/src/i18n/de/index.ts b/src/i18n/de/index.ts
@@ -9,22 +9,30 @@ const de = {
 	site: {
 		name: 'Localize URL'
 	},
-	header: {
-		incorrectUrl: 'Falsche URL',
-		onlyVisibleInEnglish: '',
-		fallback: 'Fallback-URL'
-	},
 	pageHome: {
 		title: 'Startseite',
 		welcome: 'Willkommen auf der Homepage',
-		spectators: '{0} Zuschauer live'
+		apiDescription: 'API-Aufrufe, die nicht von der Bibliothek betroffen sind',
+		spectators: '{0} Zuschauer live',
+		legend: {
+			title: 'Legende',
+			correct: 'Richtiger Link',
+			fallback: 'Fallback-Link (führt zu einem anderen Gebietsschema)',
+			vary: 'Richtiger Link (nur für unterstützte Gebietsschemas sichtbar)',
+			redirect: 'Nicht übereinstimmender Link, Weiterleitung',
+			error: 'Für dieses Gebietsschema nicht verfügbar'
+		}
 	},
 	pageAbout: {
-		title: 'Über das Projekt'
+		title: 'Über uns',
+		text: 'Über uns Seite sagt Hallo.'
+	},
+	pageEnglish: {
+		title: 'Seite nur auf Englisch',
+		text: ''
 	},
 	pageNews: {
-		title: 'Nachricht',
-		posts: 'Beiträge'
+		title: 'Nachricht'
 	},
 	pageError: {
 		title404: 'Seite nicht gefunden',

diff --git a/src/i18n/en/index.ts b/src/i18n/en/index.ts
@@ -5,26 +5,30 @@ const en = {
 	site: {
 		name: 'Localize URL'
 	},
-	header: {
-		incorrectUrl: 'Incorrect URL',
-		onlyVisibleInEnglish: 'Only visible in English',
-		fallback: 'Fallback URL'
-	},
 	pageHome: {
 		title: 'Home page',
 		welcome: 'Welcome to the home page',
-		spectators: '{0} live spectator{{s}}'
+		apiDescription: 'API calls that are not affected by the library',
+		spectators: '{0} live spectator{{s}}',
+		legend: {
+			title: 'Legend',
+			correct: 'Correct link',
+			fallback: 'Fallback link (leads to another locale)',
+			vary: 'Correct link (only visible for supported locales)',
+			redirect: 'Mismatched link, redirect',
+			error: 'Not available for this locale'
+		}
 	},
 	pageAbout: {
-		title: 'About project'
+		title: 'About',
+		text: 'About us page says hello.'
 	},
-	pagePartial: {
-		title: 'Partially translated page',
+	pageEnglish: {
+		title: 'English-only page',
 		text: 'This page is only available in English.'
 	},
 	pageNews: {
-		title: 'News',
-		posts: 'Posts'
+		title: 'News'
 	},
 	pageError: {
 		title404: 'Page Not Found',

diff --git a/src/i18n/i18n-types.ts b/src/i18n/i18n-types.ts
@@ -27,20 +27,6 @@ type RootTranslation = {
 		 */
 		name: string;
 	};
-	header: {
-		/**
-		 * Incorrect URL
-		 */
-		incorrectUrl: string;
-		/**
-		 * Only visible in English
-		 */
-		onlyVisibleInEnglish: string;
-		/**
-		 * Fallback URL
-		 */
-		fallback: string;
-	};
 	pageHome: {
 		/**
 		 * Home page
@@ -50,21 +36,55 @@ type RootTranslation = {
 		 * Welcome to the home page
 		 */
 		welcome: string;
+		/**
+		 * API calls that are not affected by the library
+		 */
+		apiDescription: string;
 		/**
 		 * {0} live spectator{{s}}
 		 * @param {string | number | boolean} 0
 		 */
 		spectators: RequiredParams<'0'>;
+		legend: {
+			/**
+			 * Legend
+			 */
+			title: string;
+			/**
+			 * Correct link
+			 */
+			correct: string;
+			/**
+			 * Fallback link (leads to another locale)
+			 */
+			fallback: string;
+			/**
+			 * Correct link (only visible for supported locales)
+			 */
+			vary: string;
+			/**
+			 * Mismatched link, redirect
+			 */
+			redirect: string;
+			/**
+			 * Not available for this locale
+			 */
+			error: string;
+		};
 	};
 	pageAbout: {
 		/**
-		 * About project
+		 * About
 		 */
 		title: string;
+		/**
+		 * About us page says hello.
+		 */
+		text: string;
 	};
-	pagePartial: {
+	pageEnglish: {
 		/**
-		 * Partially translated page
+		 * English-only page
 		 */
 		title: string;
 		/**
@@ -77,10 +97,6 @@ type RootTranslation = {
 		 * News
 		 */
 		title: string;
-		/**
-		 * Posts
-		 */
-		posts: string;
 	};
 	pageError: {
 		/**
@@ -133,20 +149,6 @@ export type TranslationFunctions = {
 		 */
 		name: () => LocalizedString;
 	};
-	header: {
-		/**
-		 * Incorrect URL
-		 */
-		incorrectUrl: () => LocalizedString;
-		/**
-		 * Only visible in English
-		 */
-		onlyVisibleInEnglish: () => LocalizedString;
-		/**
-		 * Fallback URL
-		 */
-		fallback: () => LocalizedString;
-	};
 	pageHome: {
 		/**
 		 * Home page
@@ -156,20 +158,54 @@ export type TranslationFunctions = {
 		 * Welcome to the home page
 		 */
 		welcome: () => LocalizedString;
+		/**
+		 * API calls that are not affected by the library
+		 */
+		apiDescription: () => LocalizedString;
 		/**
 		 * {0} live spectator{{s}}
 		 */
 		spectators: (arg0: string | number | boolean) => LocalizedString;
+		legend: {
+			/**
+			 * Legend
+			 */
+			title: () => LocalizedString;
+			/**
+			 * Correct link
+			 */
+			correct: () => LocalizedString;
+			/**
+			 * Fallback link (leads to another locale)
+			 */
+			fallback: () => LocalizedString;
+			/**
+			 * Correct link (only visible for supported locales)
+			 */
+			vary: () => LocalizedString;
+			/**
+			 * Mismatched link, redirect
+			 */
+			redirect: () => LocalizedString;
+			/**
+			 * Not available for this locale
+			 */
+			error: () => LocalizedString;
+		};
 	};
 	pageAbout: {
 		/**
-		 * About project
+		 * About
 		 */
 		title: () => LocalizedString;
+		/**
+		 * About us page says hello.
+		 */
+		text: () => LocalizedString;
 	};
-	pagePartial: {
+	pageEnglish: {
 		/**
-		 * Partially translated page
+		 * English-only page
 		 */
 		title: () => LocalizedString;
 		/**
@@ -182,10 +218,6 @@ export type TranslationFunctions = {
 		 * News
 		 */
 		title: () => LocalizedString;
-		/**
-		 * Posts
-		 */
-		posts: () => LocalizedString;
 	};
 	pageError: {
 		/**