feat: add language selection for turn-by-turn navigation instructions (#286)

Author: mustaphaturhan

src/components/settings-panel/settings-options.ts

@@ -753,6 +753,45 @@ export const generalize = {
   },
 };
 
+// Valhalla supported language options for turn-by-turn navigation instructions
+// Reference: https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/#supported-language-tags
+export const languageOptions = [
+  { key: 'bg-BG', text: 'Bulgarian (Bulgaria)', value: 'bg-BG' },
+  { key: 'ca-ES', text: 'Catalan (Spain)', value: 'ca-ES' },
+  { key: 'cs-CZ', text: 'Czech (Czech Republic)', value: 'cs-CZ' },
+  { key: 'da-DK', text: 'Danish (Denmark)', value: 'da-DK' },
+  { key: 'de-DE', text: 'German (Germany)', value: 'de-DE' },
+  { key: 'el-GR', text: 'Greek (Greece)', value: 'el-GR' },
+  { key: 'en-GB', text: 'English (United Kingdom)', value: 'en-GB' },
+  { key: 'en-US', text: 'English (United States)', value: 'en-US' },
+  { key: 'en-US-x-pirate', text: 'English (Pirate)', value: 'en-US-x-pirate' },
+  { key: 'es-ES', text: 'Spanish (Spain)', value: 'es-ES' },
+  { key: 'et-EE', text: 'Estonian (Estonia)', value: 'et-EE' },
+  { key: 'fi-FI', text: 'Finnish (Finland)', value: 'fi-FI' },
+  { key: 'fr-FR', text: 'French (France)', value: 'fr-FR' },
+  { key: 'hi-IN', text: 'Hindi (India)', value: 'hi-IN' },
+  { key: 'hu-HU', text: 'Hungarian (Hungary)', value: 'hu-HU' },
+  { key: 'it-IT', text: 'Italian (Italy)', value: 'it-IT' },
+  { key: 'ja-JP', text: 'Japanese (Japan)', value: 'ja-JP' },
+  { key: 'nb-NO', text: 'Bokmal (Norway)', value: 'nb-NO' },
+  { key: 'nl-NL', text: 'Dutch (Netherlands)', value: 'nl-NL' },
+  { key: 'pl-PL', text: 'Polish (Poland)', value: 'pl-PL' },
+  { key: 'pt-BR', text: 'Portuguese (Brazil)', value: 'pt-BR' },
+  { key: 'pt-PT', text: 'Portuguese (Portugal)', value: 'pt-PT' },
+  { key: 'ro-RO', text: 'Romanian (Romania)', value: 'ro-RO' },
+  { key: 'ru-RU', text: 'Russian (Russia)', value: 'ru-RU' },
+  { key: 'sk-SK', text: 'Slovak (Slovakia)', value: 'sk-SK' },
+  { key: 'sl-SI', text: 'Slovenian (Slovenia)', value: 'sl-SI' },
+  { key: 'sv-SE', text: 'Swedish (Sweden)', value: 'sv-SE' },
+  { key: 'tr-TR', text: 'Turkish (Türkiye)', value: 'tr-TR' },
+  { key: 'uk-UA', text: 'Ukrainian (Ukraine)', value: 'uk-UA' },
+] as const;
+
+export type DirectionsLanguage = (typeof languageOptions)[number]['value'];
+
+export const DEFAULT_DIRECTIONS_LANGUAGE: DirectionsLanguage = 'en-US';
+export const DIRECTIONS_LANGUAGE_STORAGE_KEY = 'directions_language';
+
 export const settingsInit = {
   maneuver_penalty: 5,
   country_crossing_penalty: 0,

src/components/settings-panel/settings-panel.spec.tsx

@@ -2,16 +2,20 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { SettingsPanel } from './settings-panel';
+import { DIRECTIONS_LANGUAGE_STORAGE_KEY } from './settings-options';
 
 const mockUpdateSettings = vi.fn();
 const mockResetSettings = vi.fn();
 const mockToggleSettings = vi.fn();
 const mockRefetchDirections = vi.fn();
 const mockRefetchIsochrones = vi.fn();
 
+const mockUseParams = vi.fn(() => ({ activeTab: 'directions' }));
+const mockUseSearch = vi.fn(() => ({ profile: 'bicycle' }));
+
 vi.mock('@tanstack/react-router', () => ({
-  useParams: vi.fn(() => ({ activeTab: 'directions' })),
-  useSearch: vi.fn(() => ({ profile: 'bicycle' })),
+  useParams: () => mockUseParams(),
+  useSearch: () => mockUseSearch(),
 }));
 
 vi.mock('@/stores/common-store', () => ({
@@ -60,12 +64,20 @@ vi.mock('@/hooks/use-isochrones-queries', () => ({
 }));
 
 describe('SettingsPanel', () => {
+  const originalNavigator = global.navigator;
+
   beforeEach(() => {
     vi.clearAllMocks();
+    localStorage.clear();
+    mockUseParams.mockReturnValue({ activeTab: 'directions' });
+    mockUseSearch.mockReturnValue({ profile: 'bicycle' });
+    vi.stubGlobal('navigator', { ...originalNavigator, language: 'en-US' });
   });
 
   afterEach(() => {
     vi.restoreAllMocks();
+    localStorage.clear();
+    vi.stubGlobal('navigator', originalNavigator);
   });
 
   it('should render without crashing', () => {
@@ -203,4 +215,49 @@ describe('SettingsPanel', () => {
     expect(screen.getByText('Use Living Streets')).toBeInTheDocument();
     expect(screen.getByText('Turn Penalty')).toBeInTheDocument();
   });
+
+  describe('Language Picker', () => {
+    it('should render Directions Language section when activeTab is directions', () => {
+      render(<SettingsPanel />);
+      expect(screen.getByText('Directions Language')).toBeInTheDocument();
+      expect(screen.getByText('Language')).toBeInTheDocument();
+    });
+
+    it('should not render Directions Language section when activeTab is isochrones', () => {
+      mockUseParams.mockReturnValue({ activeTab: 'isochrones' });
+      render(<SettingsPanel />);
+      expect(screen.queryByText('Directions Language')).not.toBeInTheDocument();
+    });
+
+    it('should use system locale when no language is stored', () => {
+      vi.stubGlobal('navigator', { language: 'fr-FR' });
+      render(<SettingsPanel />);
+      expect(screen.getByText('French (France)')).toBeInTheDocument();
+    });
+
+    it('should fall back to en-US when system locale is not supported', () => {
+      vi.stubGlobal('navigator', { language: 'xx-XX' });
+      render(<SettingsPanel />);
+      expect(screen.getByText('English (United States)')).toBeInTheDocument();
+    });
+
+    it('should use stored language from localStorage on initial render', () => {
+      localStorage.setItem(DIRECTIONS_LANGUAGE_STORAGE_KEY, 'de-DE');
+      render(<SettingsPanel />);
+      expect(screen.getByText('German (Germany)')).toBeInTheDocument();
+    });
+
+    it('should render language select with correct id', () => {
+      render(<SettingsPanel />);
+      const languageSelect = screen.getByRole('combobox', {
+        name: /Language/i,
+      });
+      expect(languageSelect).toBeInTheDocument();
+    });
+
+    it('should render language description in help tooltip', () => {
+      render(<SettingsPanel />);
+      expect(screen.getByText('Language')).toBeInTheDocument();
+    });
+  });
 });

src/components/settings-panel/settings-panel.tsx

@@ -1,7 +1,16 @@
 import { useState, useCallback } from 'react';
 import { Button } from '@/components/ui/button';
-import { profileSettings, generalSettings } from './settings-options';
+import {
+  profileSettings,
+  generalSettings,
+  languageOptions,
+  type DirectionsLanguage,
+} from './settings-options';
 import { filterProfileSettings } from '@/utils/filter-profile-settings';
+import {
+  getDirectionsLanguage,
+  setDirectionsLanguage,
+} from '@/utils/directions-language';
 import type { PossibleSettings } from '@/components/types';
 
 import { SliderSetting } from '@/components/ui/slider-setting';
@@ -35,6 +44,20 @@ export const SettingsPanel = () => {
   const { refetch: refetchDirections } = useDirectionsQuery();
   const { refetch: refetchIsochrones } = useIsochronesQuery();
 
+  const [language, setLanguage] = useState<DirectionsLanguage>(() =>
+    getDirectionsLanguage()
+  );
+
+  const handleLanguageChange = useCallback(
+    (value: string) => {
+      const newLanguage = value as DirectionsLanguage;
+      setDirectionsLanguage(newLanguage);
+      setLanguage(newLanguage);
+      refetchDirections();
+    },
+    [refetchDirections]
+  );
+
   const handleMakeRequest = useCallback(() => {
     if (activeTab === 'directions') {
       refetchDirections();
@@ -104,6 +127,26 @@ export const SettingsPanel = () => {
         </SheetHeader>
         <div className="px-3">
           <div className="flex flex-col gap-3 border rounded-md p-2 px-3 mb-3">
+            {activeTab === 'directions' && (
+              <>
+                <section>
+                  <h3 className="text-xs font-semibold tracking-wide text-muted-foreground uppercase mb-1">
+                    Directions Language
+                  </h3>
+                  <SelectSetting
+                    id="directions-language"
+                    label="Language"
+                    description="The language used for turn-by-turn navigation instructions"
+                    placeholder="Select Language"
+                    value={language}
+                    options={[...languageOptions]}
+                    onValueChange={handleLanguageChange}
+                  />
+                </section>
+                <Separator />
+              </>
+            )}
+
             {hasProfileSettings && (
               <section>
                 <div className="flex items-baseline justify-between">

src/hooks/use-directions-queries.ts

@@ -18,6 +18,7 @@ import {
   parseGeocodeResponse,
 } from '@/utils/nominatim';
 import { filterProfileSettings } from '@/utils/filter-profile-settings';
+import { getDirectionsLanguage } from '@/utils/directions-language';
 import { useCommonStore } from '@/stores/common-store';
 import { useDirectionsStore, type Waypoint } from '@/stores/directions-store';
 import { router } from '@/routes';
@@ -40,12 +41,15 @@ async function fetchDirections() {
   }
 
   const settings = filterProfileSettings(profile || 'bicycle', rawSettings);
+  const language = getDirectionsLanguage();
+
   const valhallaRequest = buildDirectionsRequest({
     profile: profile || 'bicycle',
     activeWaypoints,
     // @ts-expect-error todo: initial settings and filtered settings types mismatch
     settings,
     dateTime,
+    language,
   });
 
   const { data } = await axios.get<ValhallaRouteResponse>(

src/utils/directions-language.spec.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  getDirectionsLanguage,
+  setDirectionsLanguage,
+} from './directions-language';
+import {
+  DEFAULT_DIRECTIONS_LANGUAGE,
+  DIRECTIONS_LANGUAGE_STORAGE_KEY,
+} from '@/components/settings-panel/settings-options';
+
+describe('directions-language', () => {
+  const originalNavigator = global.navigator;
+
+  beforeEach(() => {
+    localStorage.clear();
+    vi.clearAllMocks();
+    vi.stubGlobal('navigator', { language: 'en-US' });
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+    vi.stubGlobal('navigator', originalNavigator);
+  });
+
+  describe('getDirectionsLanguage', () => {
+    it('should return system language when localStorage is empty and locale is supported', () => {
+      vi.stubGlobal('navigator', { language: 'de-DE' });
+      expect(getDirectionsLanguage()).toBe('de-DE');
+    });
+
+    it('should return default language when localStorage is empty and locale is not supported', () => {
+      vi.stubGlobal('navigator', { language: 'xx-XX' });
+      expect(getDirectionsLanguage()).toBe(DEFAULT_DIRECTIONS_LANGUAGE);
+    });
+
+    it('should match partial locale when exact match not found', () => {
+      vi.stubGlobal('navigator', { language: 'fr-CA' });
+      expect(getDirectionsLanguage()).toBe('fr-FR');
+    });
+
+    it('should return stored language when valid', () => {
+      localStorage.setItem(DIRECTIONS_LANGUAGE_STORAGE_KEY, 'de-DE');
+      expect(getDirectionsLanguage()).toBe('de-DE');
+    });
+
+    it('should return system language when stored value is invalid', () => {
+      vi.stubGlobal('navigator', { language: 'es-ES' });
+      localStorage.setItem(DIRECTIONS_LANGUAGE_STORAGE_KEY, 'invalid-lang');
+      expect(getDirectionsLanguage()).toBe('es-ES');
+    });
+
+    it('should return stored language for all supported languages', () => {
+      const supportedLanguages = [
+        'bg-BG',
+        'ca-ES',
+        'cs-CZ',
+        'da-DK',
+        'de-DE',
+        'el-GR',
+        'en-GB',
+        'en-US',
+        'en-US-x-pirate',
+        'es-ES',
+        'et-EE',
+        'fi-FI',
+        'fr-FR',
+        'hi-IN',
+        'hu-HU',
+        'it-IT',
+        'ja-JP',
+        'nb-NO',
+        'nl-NL',
+        'pl-PL',
+        'pt-BR',
+        'pt-PT',
+        'ro-RO',
+        'ru-RU',
+        'sk-SK',
+        'sl-SI',
+        'sv-SE',
+        'tr-TR',
+        'uk-UA',
+      ];
+
+      for (const lang of supportedLanguages) {
+        localStorage.setItem(DIRECTIONS_LANGUAGE_STORAGE_KEY, lang);
+        expect(getDirectionsLanguage()).toBe(lang);
+      }
+    });
+  });
+
+  describe('setDirectionsLanguage', () => {
+    it('should save language to localStorage', () => {
+      setDirectionsLanguage('fr-FR');
+      expect(localStorage.getItem(DIRECTIONS_LANGUAGE_STORAGE_KEY)).toBe(
+        'fr-FR'
+      );
+    });
+
+    it('should overwrite existing language in localStorage', () => {
+      setDirectionsLanguage('de-DE');
+      expect(localStorage.getItem(DIRECTIONS_LANGUAGE_STORAGE_KEY)).toBe(
+        'de-DE'
+      );
+
+      setDirectionsLanguage('es-ES');
+      expect(localStorage.getItem(DIRECTIONS_LANGUAGE_STORAGE_KEY)).toBe(
+        'es-ES'
+      );
+    });
+
+    it('should allow setting the default language', () => {
+      setDirectionsLanguage('tr-TR');
+      setDirectionsLanguage(DEFAULT_DIRECTIONS_LANGUAGE);
+      expect(localStorage.getItem(DIRECTIONS_LANGUAGE_STORAGE_KEY)).toBe(
+        DEFAULT_DIRECTIONS_LANGUAGE
+      );
+    });
+  });
+
+  describe('integration', () => {
+    it('should get what was set', () => {
+      setDirectionsLanguage('ja-JP');
+      expect(getDirectionsLanguage()).toBe('ja-JP');
+    });
+
+    it('should persist across calls', () => {
+      setDirectionsLanguage('nl-NL');
+      expect(getDirectionsLanguage()).toBe('nl-NL');
+      expect(getDirectionsLanguage()).toBe('nl-NL');
+    });
+  });
+});