From c5be09bcb9954fffbcd10f785673fd4f6b5def26 Mon Sep 17 00:00:00 2001
From: alex <misc@wiesner.com.br>
Date: Sun, 8 Mar 2026 17:21:51 +0000
Subject: [PATCH] fix(frontend): clean docs links and improve settings clarity

---
 frontend/src/lib/components/AboutModal.svelte |   2 +-
 frontend/src/lib/components/Navbar.svelte     |  15 +--
 .../lib/components/cards/CountryCard.svelte   |  72 ++++++++++--
 frontend/src/locales/de.json                  |   4 +
 frontend/src/locales/en.json                  |   4 +
 frontend/src/routes/+error.svelte             |   6 +-
 frontend/src/routes/settings/+page.svelte     | 109 ++++++++++--------
 frontend/src/routes/worldtravel/+page.svelte  |  15 +--
 8 files changed, 146 insertions(+), 81 deletions(-)

diff --git a/frontend/src/lib/components/AboutModal.svelte b/frontend/src/lib/components/AboutModal.svelte
index 6f733890..05ac90aa 100644
--- a/frontend/src/lib/components/AboutModal.svelte
+++ b/frontend/src/lib/components/AboutModal.svelte
@@ -200,7 +200,7 @@
 						</a>
 						<!-- documentation -->
 						<a
-							href="https://voyage.app"
+							href="https://github.com/Alex-Wiesner/voyage"
 							target="_blank"
 							rel="noopener noreferrer"
 							class="btn btn-outline btn-sm"
diff --git a/frontend/src/lib/components/Navbar.svelte b/frontend/src/lib/components/Navbar.svelte
index 88deb0ec..50455d1c 100644
--- a/frontend/src/lib/components/Navbar.svelte
+++ b/frontend/src/lib/components/Navbar.svelte
@@ -6,7 +6,6 @@
 
 	import DotsHorizontal from '~icons/mdi/dots-horizontal';
 	import Calendar from '~icons/mdi/calendar';
-	import HelpCircle from '~icons/mdi/help-circle';
 	import AboutModal from './AboutModal.svelte';
 	import AccountMultiple from '~icons/mdi/account-multiple';
 	import MapMarker from '~icons/mdi/map-marker';
@@ -122,12 +121,6 @@
 		{ path: '/locations', icon: MapMarker, label: 'locations.locations' },
 		{ path: '/collections', icon: FormatListBulletedSquare, label: 'navbar.collections' },
 		{ path: '/invites', icon: AccountMultiple, label: 'invites.title' },
-		{
-			path: 'https://voyage.app/docs/usage/usage.html',
-			icon: HelpCircle,
-			label: 'navbar.documentation',
-			external: true
-		},
 		{ path: '/worldtravel', icon: Earth, label: 'navbar.worldtravel' },
 		{ path: '/map', icon: MapIcon, label: 'navbar.map' },
 		{ path: '/calendar', icon: Calendar, label: 'navbar.calendar' },
@@ -306,12 +299,14 @@
 					>
 						{$t('navbar.about')}
 					</button>
-					<button
+					<a
+						href="https://github.com/Alex-Wiesner/voyage"
+						target="_blank"
+						rel="noopener noreferrer"
 						class="btn btn-ghost w-full justify-start gap-3"
-						on:click={() => (window.location.href = 'https://voyage.app')}
 					>
 						{$t('navbar.documentation')}
-					</button>
+					</a>
 					<button
 						class="btn btn-ghost w-full justify-start gap-3"
 						on:click={() => (window.location.href = 'https://discord.gg/wRbQ9Egr8C')}
diff --git a/frontend/src/lib/components/cards/CountryCard.svelte b/frontend/src/lib/components/cards/CountryCard.svelte
index 2959bacf..ef64a1bf 100644
--- a/frontend/src/lib/components/cards/CountryCard.svelte
+++ b/frontend/src/lib/components/cards/CountryCard.svelte
@@ -1,7 +1,6 @@
 <script lang="ts">
 	import { goto } from '$app/navigation';
 	import type { Country } from '$lib/types';
-	import { createEventDispatcher } from 'svelte';
 	import { t } from 'svelte-i18n';
 
 	import MapMarkerStar from '~icons/mdi/map-marker-star';
@@ -9,6 +8,50 @@
 
 	export let country: Country;
 
+	type FlagDisplayState = 'primary' | 'cdn' | 'placeholder';
+
+	let flagState: FlagDisplayState = 'placeholder';
+	let lastFlagKey = '';
+
+	$: normalizedCountryCode = country.country_code.trim().toLowerCase();
+	$: primaryFlagUrl = country.flag_url.trim() || null;
+	$: cdnFlagUrl =
+		normalizedCountryCode.length === 2
+			? `https://flagcdn.com/w320/${normalizedCountryCode}.png`
+			: null;
+	$: currentFlagSrc =
+		flagState === 'primary' ? primaryFlagUrl : flagState === 'cdn' ? cdnFlagUrl : null;
+	$: showFlagImage = Boolean(currentFlagSrc);
+
+	function getInitialFlagState(): FlagDisplayState {
+		if (primaryFlagUrl) {
+			return 'primary';
+		}
+
+		if (cdnFlagUrl) {
+			return 'cdn';
+		}
+
+		return 'placeholder';
+	}
+
+	$: {
+		const flagKey = `${primaryFlagUrl ?? ''}|${cdnFlagUrl ?? ''}`;
+		if (flagKey !== lastFlagKey) {
+			lastFlagKey = flagKey;
+			flagState = getInitialFlagState();
+		}
+	}
+
+	function handleFlagError() {
+		if (flagState === 'primary' && cdnFlagUrl && cdnFlagUrl !== primaryFlagUrl) {
+			flagState = 'cdn';
+			return;
+		}
+
+		flagState = 'placeholder';
+	}
+
 	async function nav() {
 		goto(`/worldtravel/${country.country_code}`);
 	}
@@ -18,8 +61,23 @@
 	class="card w-full max-w-md bg-base-300 text-base-content shadow-2xl hover:shadow-3xl transition-all duration-300 border border-base-300 hover:border-primary/20 group overflow-hidden"
 >
 	<!-- Flag Image -->
-	<figure>
-		<img src={country.flag_url} alt={`Flag of ${country.name}`} class="w-full h-48 object-cover" />
+	<figure class="w-full h-48 bg-base-200 overflow-hidden">
+		{#if showFlagImage}
+			<img
+				src={currentFlagSrc}
+				alt={`Flag of ${country.name}`}
+				class="w-full h-full object-cover"
+				on:error={handleFlagError}
+			/>
+		{:else}
+			<div
+				class="w-full h-full flex flex-col items-center justify-center gap-1 text-base-content/70"
+				aria-label={`Flag unavailable for ${country.name}`}
+			>
+				<span class="text-3xl" aria-hidden="true">🏳️</span>
+				<span class="text-sm font-medium">{$t('country.flag_unavailable')}</span>
+			</div>
+		{/if}
 	</figure>
 
 	<!-- Content -->
@@ -64,11 +122,3 @@
 		</div>
 	</div>
 </div>
-
-<style>
-	.truncate {
-		overflow: hidden;
-		text-overflow: ellipsis;
-		white-space: nowrap;
-	}
-</style>
diff --git a/frontend/src/locales/de.json b/frontend/src/locales/de.json
index b22a2b6e..3548bab0 100644
--- a/frontend/src/locales/de.json
+++ b/frontend/src/locales/de.json
@@ -589,6 +589,9 @@
 		"show_more": "Mehr anzeigen",
 		"all_locations_visited": "Alle Orte besucht!"
 	},
+	"country": {
+		"flag_unavailable": "Flagge nicht verfügbar"
+	},
 	"settings": {
 		"account_settings": "Benutzerkontoeinstellungen",
 		"email_change": "E-Mail ändern",
@@ -745,6 +748,7 @@
 		"no_api_keys_saved": "Noch keine API-Schlüssel gespeichert.",
 		"add_api_key": "API-Schlüssel hinzufügen",
 		"provider": "Anbieter",
+		"api_key_provider_google_places": "Google Places API",
 		"api_key_value": "API-Schlüssel",
 		"api_key_value_placeholder": "Geben Sie Ihren API-Schlüssel ein",
 		"api_key_write_only_hint": "Aus Sicherheitsgründen ist Ihr Klartextschlüssel nur zum Schreiben verfügbar und wird nach dem Speichern nicht mehr angezeigt.",
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index c0e4b23b..9d837fba 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -561,6 +561,9 @@
 		"about_region": "About Region",
 		"all_locations_visited": "All locations visited!"
 	},
+	"country": {
+		"flag_unavailable": "Flag unavailable"
+	},
 	"auth": {
 		"username": "Username",
 		"password": "Password",
@@ -742,6 +745,7 @@
 		"no_api_keys_saved": "No API keys saved yet.",
 		"add_api_key": "Add API Key",
 		"provider": "Provider",
+		"api_key_provider_google_places": "Google Places API",
 		"api_key_value": "API Key",
 		"api_key_value_placeholder": "Enter your API key",
 		"api_key_write_only_hint": "For security, your plaintext key is write-only and is never shown after saving.",
diff --git a/frontend/src/routes/+error.svelte b/frontend/src/routes/+error.svelte
index e759b49d..3863c659 100644
--- a/frontend/src/routes/+error.svelte
+++ b/frontend/src/routes/+error.svelte
@@ -48,7 +48,11 @@
 			<div class="alert alert-warning mt-4">
 				<p class="text-muted-foreground">
 					<strong>Administrators:</strong> Please check your setup using the
-					<a class="link link-primary" target="_blank" href="https://voyage.app"
+					<a
+						class="link link-primary"
+						target="_blank"
+						rel="noopener noreferrer"
+						href="https://github.com/Alex-Wiesner/voyage"
 						>documentation</a
 					>.
 				</p>
diff --git a/frontend/src/routes/settings/+page.svelte b/frontend/src/routes/settings/+page.svelte
index 8830d58e..5b8e6b33 100644
--- a/frontend/src/routes/settings/+page.svelte
+++ b/frontend/src/routes/settings/+page.svelte
@@ -1244,13 +1244,14 @@
 								<div class="mt-4 p-4 bg-info/10 rounded-lg">
 									<p class="text-sm">
 										📖 {$t('immich.need_help')}
-										<a
-											class="link link-primary"
-											href="https://voyage.app/docs/configuration/immich_integration.html"
-											target="_blank">{$t('navbar.documentation')}</a
-										>
-									</p>
-								</div>
+									<a
+										class="link link-primary"
+										href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/configuration/immich_integration.md"
+										target="_blank"
+										rel="noopener noreferrer">{$t('navbar.documentation')}</a
+									>
+								</p>
+							</div>
 							</div>
 
 							<!-- Google maps integration - displayt only if its connected -->
@@ -1274,13 +1275,14 @@
 										{#if user.is_staff}
 											<p class="text-sm">
 												📖 {$t('immich.need_help')}
-												<a
-													class="link link-primary"
-													href="https://voyage.app/docs/configuration/google_maps_integration.html"
-													target="_blank">{$t('navbar.documentation')}</a
-												>
-											</p>
-										{:else if !googleMapsEnabled}
+										<a
+											class="link link-primary"
+											href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/configuration/google_maps_integration.md"
+											target="_blank"
+											rel="noopener noreferrer">{$t('navbar.documentation')}</a
+										>
+									</p>
+								{:else if !googleMapsEnabled}
 											<p class="text-sm">
 												ℹ️ {$t('google_maps.google_maps_integration_desc_no_staff')}
 											</p>
@@ -1337,13 +1339,14 @@
 										{#if user.is_staff}
 											<p class="text-sm">
 												📖 {$t('immich.need_help')}
-												<a
-													class="link link-primary"
-													href="https://voyage.app/docs/configuration/strava_integration.html"
-													target="_blank">{$t('navbar.documentation')}</a
-												>
-											</p>
-										{:else if !stravaGlobalEnabled}
+										<a
+											class="link link-primary"
+											href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/configuration/strava_integration.md"
+											target="_blank"
+											rel="noopener noreferrer">{$t('navbar.documentation')}</a
+										>
+									</p>
+								{:else if !stravaGlobalEnabled}
 											<p class="text-sm">
 												ℹ️ {$t('google_maps.google_maps_integration_desc_no_staff')}
 											</p>
@@ -1451,13 +1454,14 @@
 									<div class="mt-4 p-4 bg-info/10 rounded-lg">
 										<p class="text-sm">
 											📖 {$t('immich.need_help')}
-											<a
-												class="link link-primary"
-												href="https://voyage.app/docs/configuration/wanderer_integration.html"
-												target="_blank">{$t('navbar.documentation')}</a
-											>
-										</p>
-									</div>
+									<a
+										class="link link-primary"
+										href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/configuration/wanderer_integration.md"
+										target="_blank"
+										rel="noopener noreferrer">{$t('navbar.documentation')}</a
+									>
+								</p>
+							</div>
 								{/if}
 							</div>
 						</div>
@@ -1524,7 +1528,7 @@
 										>
 										<a
 											class="link link-primary"
-											href="https://voyage.app/docs/usage/usage.html"
+										href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/guides/travel_agent.md"
 											target="_blank"
 											rel="noopener noreferrer"
 											>{$t('settings.travel_agent_help_setup_guide')}</a
@@ -1615,9 +1619,9 @@
 											class="select select-bordered select-primary w-full"
 											bind:value={newApiKeyProvider}
 										>
-											<option value="google_maps">Google Maps</option>
-										</select>
-									</div>
+										<option value="google_maps">{$t('settings.api_key_provider_google_places')}</option>
+									</select>
+								</div>
 									<div class="form-control">
 										<label class="label" for="api-key-value">
 											<span class="label-text font-medium">{$t('settings.api_key_value')}</span>
@@ -1944,13 +1948,14 @@
 											</svg>
 											<div>
 												<span>{$t('settings.social_auth_desc_2')}</span>
-												<a
-													href="https://voyage.app/docs/configuration/social_auth.html"
-													class="link link-neutral font-medium"
-													target="_blank">{$t('settings.documentation_link')}</a
-												>
-											</div>
-										</div>
+										<a
+											href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/configuration/social_auth.md"
+											class="link link-neutral font-medium"
+											target="_blank"
+											rel="noopener noreferrer">{$t('settings.documentation_link')}</a
+										>
+									</div>
+								</div>
 									</div>
 
 									<!-- Debug Information -->
@@ -2015,19 +2020,21 @@
 												Sean Morley. {$t('settings.all_rights_reserved')}
 											</p>
 											<div class="flex justify-center gap-3 mt-2">
-												<a
-													href="https://github.com/Alex-Wiesner/voyage"
-													target="_blank"
-													class="link link-primary text-sm"
-												>
-													GitHub
+											<a
+												href="https://github.com/Alex-Wiesner/voyage"
+												target="_blank"
+												rel="noopener noreferrer"
+												class="link link-primary text-sm"
+											>
+												GitHub
 												</a>
-												<a
-													href="https://github.com/Alex-Wiesner/voyage/blob/main/LICENSE"
-													target="_blank"
-													class="link link-secondary text-sm"
-												>
-													{$t('settings.license')}
+											<a
+												href="https://github.com/Alex-Wiesner/voyage/blob/main/LICENSE"
+												target="_blank"
+												rel="noopener noreferrer"
+												class="link link-secondary text-sm"
+											>
+												{$t('settings.license')}
 												</a>
 											</div>
 										</div>
diff --git a/frontend/src/routes/worldtravel/+page.svelte b/frontend/src/routes/worldtravel/+page.svelte
index 9354ca6e..2d172eae 100644
--- a/frontend/src/routes/worldtravel/+page.svelte
+++ b/frontend/src/routes/worldtravel/+page.svelte
@@ -726,13 +726,14 @@
 										<p class="text-sm">{$t('worldtravel.no_country_data_available_desc')}</p>
 									</div>
 								</div>
-								<a
-									class="link link-primary mt-4 inline-block"
-									href="https://voyage.app/docs/configuration/updating.html#updating-the-region-data"
-									target="_blank"
-								>
-									{$t('settings.documentation_link')}
-								</a>
+							<a
+								class="link link-primary mt-4 inline-block"
+								href="https://github.com/Alex-Wiesner/voyage/blob/main/documentation/docs/configuration/updating.md#updating-region-data"
+								target="_blank"
+								rel="noopener noreferrer"
+							>
+								{$t('settings.documentation_link')}
+							</a>
 							</div>
 						{/if}
 					</div>