Language Selector

The Language Selector tool allows users to change the interface language of the accessibility widget, making it accessible to users worldwide. It provides an intuitive dropdown interface with search functionality and automatic language detection.

Overview

The Language Selector automatically detects the user's preferred language from multiple sources and provides a comprehensive list of supported languages. Users can easily switch between languages with immediate effect on the widget's interface.

Features

🔍 Smart Language Detection

HTML Language: Detects language from the website's <html lang="..."> attribute
Browser Language: Uses the browser's navigator.language setting
Stored Preference: Remembers the user's previous language selection
Fallback: Defaults to English if no valid language is detected

🎛️ Toggle Control

Enable/Disable Switch: Toggle between custom language and English
Quick Toggle: Instant switching without reopening the dropdown
State Persistence: Remembers the enabled/disabled state across sessions

🔎 Advanced Search

Real-time Search: Filter languages as you type
Multi-criteria Matching: Search by language name or language code
Case-insensitive: Works with any capitalization
No Results Feedback: Clear message when no languages match

📱 User-Friendly Interface

Visual Language Codes: Each language displays its 2-letter code
Native Language Names: Languages shown in their native script
Dropdown Arrow: Clear visual indicator for dropdown state
Current Selection: Prominently displays the active language

Supported Languages

The widget supports 30+ languages covering major world languages:

Code	Language	Native Name
`en`	English	English
`es`	Spanish	Español
`fr`	French	Français
`de`	German	Deutsch
`zh`	Chinese	中文
`bg`	Bulgarian	Български
`cs`	Czech	Čeština
`da`	Danish	Dansk
`el`	Greek	Ελληνικά
`et`	Estonian	Eesti
`fi`	Finnish	Suomi
`hi`	Hindi	हिन्दी
`hr`	Croatian	Hrvatski
`hu`	Hungarian	Magyar
`it`	Italian	Italiano
`ja`	Japanese	日本語
`ko`	Korean	한국어
`lt`	Lithuanian	Lietuvių
`lv`	Latvian	Latviešu
`nl`	Dutch	Nederlands
`no`	Norwegian	Norsk
`pl`	Polish	Polski
`pt`	Portuguese	Português
`ro`	Romanian	Română
`ru`	Russian	Русский
`sk`	Slovak	Slovenčina
`sl`	Slovenian	Slovenščina
`sv`	Swedish	Svenska
`tr`	Turkish	Türkçe

How It Works

1. Language Detection Priority

1. User's stored preference (localStorage)
2. Website's HTML lang attribute
3. Browser's default language
4. Fallback to English

2. Dynamic Loading

Lazy Loading: Translation files are loaded only when needed
Caching: Once loaded, translations are cached for performance
Error Handling: Graceful fallback if translation files fail to load

3. Reactive Updates

Immediate Effect: Interface updates instantly when language changes
Event Broadcasting: Notifies all widget components of language changes
State Synchronization: All UI elements reflect the new language consistently

Usage Examples

Basic Usage

Users can change the language through the widget interface:

Open the Language Selector in the accessibility widget
Toggle the switch to enable custom language selection
Click the language dropdown to open the language list
Search or scroll to find the desired language
Click the language to apply it immediately

Search Functionality

Type "中" → Shows: Chinese (中文)
Type "esp" → Shows: Spanish (Español)
Type "de" → Shows: German (Deutsch)

API Usage

The Language Selector can also be controlled programmatically through the Widget API, allowing developers to integrate language switching into their applications.

Setting Language Programmatically

javascript

// Change widget language to Spanish
window.BrowseAidWidget.api.setLanguage('es');

// Change to French
window.BrowseAidWidget.api.setLanguage('fr');

// Change to German
window.BrowseAidWidget.api.setLanguage('de');

// Get current language
const currentLang = window.BrowseAidWidget.api.getLanguage();
console.log('Current language:', currentLang);

Listening for Language Changes

javascript

// Listen for language changes using the API callback
const unsubscribe = window.BrowseAidWidget.api.onLanguageChange((newLanguage) => {
  console.log('Widget language changed to:', newLanguage);
  // Update your application's language-dependent content
  updateApplicationLanguage(newLanguage);
});

// Alternative: Use native DOM events
document.addEventListener('browseaid:languageChange', (event) => {
  console.log('Language changed to:', event.detail.newLanguage);
  // Synchronize with your app's internationalization
  i18n.setLocale(event.detail.newLanguage);
});

Integration Examples

javascript

// Example: Sync widget language with your app's language selector
document.getElementById('app-language-select').addEventListener('change', (event) => {
  const selectedLanguage = event.target.value;

  // Set both your app's language and the widget's language
  yourApp.setLanguage(selectedLanguage);
  window.BrowseAidWidget.api.setLanguage(selectedLanguage);
});

// Example: Auto-detect and set language on page load
document.addEventListener('DOMContentLoaded', () => {
  // Get language from your app's configuration
  const appLanguage = yourApp.getCurrentLanguage();

  // Sync widget with app language
  if (appLanguage && appLanguage !== 'en') {
    window.BrowseAidWidget.api.setLanguage(appLanguage);
  }
});

// Example: Remember user's language preference
window.BrowseAidWidget.api.onLanguageChange((newLanguage) => {
  // Save preference to your backend or local storage
  localStorage.setItem('user-preferred-language', newLanguage);

  // Update page content language attribute
  document.documentElement.lang = newLanguage;

  // Notify other parts of your application
  window.dispatchEvent(new CustomEvent('appLanguageChanged', {
    detail: { language: newLanguage }
  }));
});

Technical Implementation

Event System

The Language Selector integrates with the widget's event system:

typescript

// Language change events
EventTypes.LANGUAGE_CHANGED     // Fired when locale changes
EventTypes.UPDATE_UI_LANGUAGE   // Triggers UI updates

Storage

Language preferences are automatically saved:

javascript

// Stored in localStorage as:
'ada-widget-language': 'es'  // Selected language code

Troubleshooting

Common Issues

Language not changing?

Check if the toggle is enabled
Verify the language is in the supported list
Clear browser cache and localStorage

Missing translations?

Check browser console for loading errors
Verify network connectivity
Try switching to another language first

Search not working?

Clear the search field and try again
Check for special characters in search
Try searching by language code instead

Developer Debug

Enable debug logging to troubleshoot:

javascript

localStorage.setItem('ada-widget-debug', 'true')

This will show language loading and switching events in the browser console.

Language Selector ​

Overview ​

Features ​

🔍 Smart Language Detection ​

🎛️ Toggle Control ​

🔎 Advanced Search ​

📱 User-Friendly Interface ​

Supported Languages ​

How It Works ​

1. Language Detection Priority ​

2. Dynamic Loading ​

3. Reactive Updates ​

Usage Examples ​

Basic Usage ​

Search Functionality ​

API Usage ​

Setting Language Programmatically ​

Listening for Language Changes ​

Integration Examples ​

Technical Implementation ​

Event System ​

Storage ​

Troubleshooting ​

Common Issues ​

Developer Debug ​

Language Selector

Overview

Features

🔍 Smart Language Detection

🎛️ Toggle Control

🔎 Advanced Search

📱 User-Friendly Interface

Supported Languages

How It Works

1. Language Detection Priority

2. Dynamic Loading

3. Reactive Updates

Usage Examples

Basic Usage

Search Functionality

API Usage

Setting Language Programmatically

Listening for Language Changes

Integration Examples

Technical Implementation

Event System

Storage

Troubleshooting

Common Issues

Developer Debug