@refraction-ui/astro 0.17.0 → 0.17.2

package/dist/i18n/countries.ts

@@ -0,0 +1,122 @@
+/**
+ * Country type and registry for i18n support.
+ */
+
+export interface Country {
+  code: string
+  name: string
+  flag: string
+  defaultLanguages: string[]
+  timezone?: string
+}
+
+export const COUNTRIES: Record<string, Country> = {
+  // North America
+  'US': { code: 'US', name: 'United States',  flag: '🇺🇸', defaultLanguages: ['en'], timezone: 'America/New_York' },
+  'CA': { code: 'CA', name: 'Canada',         flag: '🇨🇦', defaultLanguages: ['en', 'fr'], timezone: 'America/Toronto' },
+  'MX': { code: 'MX', name: 'Mexico',         flag: '🇲🇽', defaultLanguages: ['es'], timezone: 'America/Mexico_City' },
+
+  // UK & Ireland
+  'GB': { code: 'GB', name: 'United Kingdom',  flag: '🇬🇧', defaultLanguages: ['en'], timezone: 'Europe/London' },
+  'IE': { code: 'IE', name: 'Ireland',         flag: '🇮🇪', defaultLanguages: ['en'], timezone: 'Europe/Dublin' },
+
+  // Oceania
+  'AU': { code: 'AU', name: 'Australia',       flag: '🇦🇺', defaultLanguages: ['en'], timezone: 'Australia/Sydney' },
+  'NZ': { code: 'NZ', name: 'New Zealand',     flag: '🇳🇿', defaultLanguages: ['en'], timezone: 'Pacific/Auckland' },
+
+  // South Asia
+  'IN': { code: 'IN', name: 'India',           flag: '🇮🇳', defaultLanguages: ['hi', 'en'], timezone: 'Asia/Kolkata' },
+  'PK': { code: 'PK', name: 'Pakistan',        flag: '🇵🇰', defaultLanguages: ['ur', 'en'], timezone: 'Asia/Karachi' },
+  'BD': { code: 'BD', name: 'Bangladesh',      flag: '🇧🇩', defaultLanguages: ['bn'], timezone: 'Asia/Dhaka' },
+  'LK': { code: 'LK', name: 'Sri Lanka',       flag: '🇱🇰', defaultLanguages: ['ta', 'en'], timezone: 'Asia/Colombo' },
+  'NP': { code: 'NP', name: 'Nepal',           flag: '🇳🇵', defaultLanguages: ['hi', 'en'], timezone: 'Asia/Kathmandu' },
+
+  // Western Europe
+  'FR': { code: 'FR', name: 'France',          flag: '🇫🇷', defaultLanguages: ['fr'], timezone: 'Europe/Paris' },
+  'DE': { code: 'DE', name: 'Germany',         flag: '🇩🇪', defaultLanguages: ['de'], timezone: 'Europe/Berlin' },
+  'ES': { code: 'ES', name: 'Spain',           flag: '🇪🇸', defaultLanguages: ['es'], timezone: 'Europe/Madrid' },
+  'IT': { code: 'IT', name: 'Italy',           flag: '🇮🇹', defaultLanguages: ['it'], timezone: 'Europe/Rome' },
+  'PT': { code: 'PT', name: 'Portugal',        flag: '🇵🇹', defaultLanguages: ['pt'], timezone: 'Europe/Lisbon' },
+  'NL': { code: 'NL', name: 'Netherlands',     flag: '🇳🇱', defaultLanguages: ['nl'], timezone: 'Europe/Amsterdam' },
+  'BE': { code: 'BE', name: 'Belgium',         flag: '🇧🇪', defaultLanguages: ['nl', 'fr', 'de'], timezone: 'Europe/Brussels' },
+  'CH': { code: 'CH', name: 'Switzerland',     flag: '🇨🇭', defaultLanguages: ['de', 'fr', 'it'], timezone: 'Europe/Zurich' },
+  'AT': { code: 'AT', name: 'Austria',         flag: '🇦🇹', defaultLanguages: ['de'], timezone: 'Europe/Vienna' },
+
+  // Nordic
+  'SE': { code: 'SE', name: 'Sweden',          flag: '🇸🇪', defaultLanguages: ['sv'], timezone: 'Europe/Stockholm' },
+  'NO': { code: 'NO', name: 'Norway',          flag: '🇳🇴', defaultLanguages: ['no'], timezone: 'Europe/Oslo' },
+  'DK': { code: 'DK', name: 'Denmark',         flag: '🇩🇰', defaultLanguages: ['da'], timezone: 'Europe/Copenhagen' },
+  'FI': { code: 'FI', name: 'Finland',         flag: '🇫🇮', defaultLanguages: ['fi'], timezone: 'Europe/Helsinki' },
+
+  // Eastern Europe
+  'PL': { code: 'PL', name: 'Poland',          flag: '🇵🇱', defaultLanguages: ['pl'], timezone: 'Europe/Warsaw' },
+  'CZ': { code: 'CZ', name: 'Czech Republic',  flag: '🇨🇿', defaultLanguages: ['cs'], timezone: 'Europe/Prague' },
+  'RO': { code: 'RO', name: 'Romania',         flag: '🇷🇴', defaultLanguages: ['ro'], timezone: 'Europe/Bucharest' },
+  'HU': { code: 'HU', name: 'Hungary',         flag: '🇭🇺', defaultLanguages: ['hu'], timezone: 'Europe/Budapest' },
+  'BG': { code: 'BG', name: 'Bulgaria',        flag: '🇧🇬', defaultLanguages: ['bg'], timezone: 'Europe/Sofia' },
+  'HR': { code: 'HR', name: 'Croatia',         flag: '🇭🇷', defaultLanguages: ['hr'], timezone: 'Europe/Zagreb' },
+  'SK': { code: 'SK', name: 'Slovakia',        flag: '🇸🇰', defaultLanguages: ['sk'], timezone: 'Europe/Bratislava' },
+  'SI': { code: 'SI', name: 'Slovenia',        flag: '🇸🇮', defaultLanguages: ['sl'], timezone: 'Europe/Ljubljana' },
+  'RS': { code: 'RS', name: 'Serbia',          flag: '🇷🇸', defaultLanguages: ['sr'], timezone: 'Europe/Belgrade' },
+  'UA': { code: 'UA', name: 'Ukraine',         flag: '🇺🇦', defaultLanguages: ['uk'], timezone: 'Europe/Kyiv' },
+  'RU': { code: 'RU', name: 'Russia',          flag: '🇷🇺', defaultLanguages: ['ru'], timezone: 'Europe/Moscow' },
+  'TR': { code: 'TR', name: 'Turkey',          flag: '🇹🇷', defaultLanguages: ['tr'], timezone: 'Europe/Istanbul' },
+  'GR': { code: 'GR', name: 'Greece',          flag: '🇬🇷', defaultLanguages: ['el'], timezone: 'Europe/Athens' },
+
+  // East Asia
+  'JP': { code: 'JP', name: 'Japan',           flag: '🇯🇵', defaultLanguages: ['ja'], timezone: 'Asia/Tokyo' },
+  'KR': { code: 'KR', name: 'South Korea',     flag: '🇰🇷', defaultLanguages: ['ko'], timezone: 'Asia/Seoul' },
+  'CN': { code: 'CN', name: 'China',           flag: '🇨🇳', defaultLanguages: ['zh'], timezone: 'Asia/Shanghai' },
+  'TW': { code: 'TW', name: 'Taiwan',          flag: '🇹🇼', defaultLanguages: ['zh'], timezone: 'Asia/Taipei' },
+
+  // Southeast Asia
+  'TH': { code: 'TH', name: 'Thailand',        flag: '🇹🇭', defaultLanguages: ['th'], timezone: 'Asia/Bangkok' },
+  'VN': { code: 'VN', name: 'Vietnam',         flag: '🇻🇳', defaultLanguages: ['vi'], timezone: 'Asia/Ho_Chi_Minh' },
+  'ID': { code: 'ID', name: 'Indonesia',       flag: '🇮🇩', defaultLanguages: ['id'], timezone: 'Asia/Jakarta' },
+  'MY': { code: 'MY', name: 'Malaysia',        flag: '🇲🇾', defaultLanguages: ['ms', 'en'], timezone: 'Asia/Kuala_Lumpur' },
+  'PH': { code: 'PH', name: 'Philippines',     flag: '🇵🇭', defaultLanguages: ['en'], timezone: 'Asia/Manila' },
+  'SG': { code: 'SG', name: 'Singapore',       flag: '🇸🇬', defaultLanguages: ['en', 'ms', 'zh'], timezone: 'Asia/Singapore' },
+
+  // South America
+  'BR': { code: 'BR', name: 'Brazil',          flag: '🇧🇷', defaultLanguages: ['pt'], timezone: 'America/Sao_Paulo' },
+  'AR': { code: 'AR', name: 'Argentina',       flag: '🇦🇷', defaultLanguages: ['es'], timezone: 'America/Argentina/Buenos_Aires' },
+  'CO': { code: 'CO', name: 'Colombia',        flag: '🇨🇴', defaultLanguages: ['es'], timezone: 'America/Bogota' },
+  'CL': { code: 'CL', name: 'Chile',           flag: '🇨🇱', defaultLanguages: ['es'], timezone: 'America/Santiago' },
+
+  // Middle East & North Africa
+  'SA': { code: 'SA', name: 'Saudi Arabia',    flag: '🇸🇦', defaultLanguages: ['ar'], timezone: 'Asia/Riyadh' },
+  'AE': { code: 'AE', name: 'United Arab Emirates', flag: '🇦🇪', defaultLanguages: ['ar', 'en'], timezone: 'Asia/Dubai' },
+  'IL': { code: 'IL', name: 'Israel',          flag: '🇮🇱', defaultLanguages: ['he'], timezone: 'Asia/Jerusalem' },
+  'EG': { code: 'EG', name: 'Egypt',           flag: '🇪🇬', defaultLanguages: ['ar'], timezone: 'Africa/Cairo' },
+}
+
+/**
+ * Get a country by its code.
+ */
+export function getCountry(code: string): Country | undefined {
+  return COUNTRIES[code]
+}
+
+/**
+ * Get the flag emoji for a country code.
+ * Returns empty string if the code is not found.
+ */
+export function getCountryFlag(code: string): string {
+  return COUNTRIES[code]?.flag ?? ''
+}
+
+/**
+ * Get the display name for a country code.
+ * Returns empty string if the code is not found.
+ */
+export function getCountryName(code: string): string {
+  return COUNTRIES[code]?.name ?? ''
+}
+
+/**
+ * Get default languages for a country.
+ * Returns empty array if the country is not found.
+ */
+export function getDefaultLanguagesForCountry(code: string): string[] {
+  return COUNTRIES[code]?.defaultLanguages ?? []
+}

package/dist/i18n/detect-region.ts

@@ -0,0 +1,243 @@
+/**
+ * Region detection utilities.
+ * Detects user country and language from browser/environment signals.
+ */
+
+/** Mapping of IANA timezone identifiers to ISO country codes */
+export const TIMEZONE_TO_COUNTRY: Record<string, string> = {
+  // United States
+  'America/New_York': 'US',
+  'America/Chicago': 'US',
+  'America/Denver': 'US',
+  'America/Los_Angeles': 'US',
+  'America/Phoenix': 'US',
+  'America/Anchorage': 'US',
+  'Pacific/Honolulu': 'US',
+  'America/Detroit': 'US',
+  'America/Indiana/Indianapolis': 'US',
+  'America/Boise': 'US',
+
+  // Canada
+  'America/Toronto': 'CA',
+  'America/Vancouver': 'CA',
+  'America/Edmonton': 'CA',
+  'America/Winnipeg': 'CA',
+  'America/Halifax': 'CA',
+  'America/St_Johns': 'CA',
+
+  // Mexico
+  'America/Mexico_City': 'MX',
+  'America/Cancun': 'MX',
+  'America/Tijuana': 'MX',
+
+  // UK & Ireland
+  'Europe/London': 'GB',
+  'Europe/Dublin': 'IE',
+
+  // Western Europe
+  'Europe/Paris': 'FR',
+  'Europe/Berlin': 'DE',
+  'Europe/Madrid': 'ES',
+  'Europe/Rome': 'IT',
+  'Europe/Lisbon': 'PT',
+  'Europe/Amsterdam': 'NL',
+  'Europe/Brussels': 'BE',
+  'Europe/Zurich': 'CH',
+  'Europe/Vienna': 'AT',
+
+  // Nordic
+  'Europe/Stockholm': 'SE',
+  'Europe/Oslo': 'NO',
+  'Europe/Copenhagen': 'DK',
+  'Europe/Helsinki': 'FI',
+
+  // Eastern Europe
+  'Europe/Warsaw': 'PL',
+  'Europe/Prague': 'CZ',
+  'Europe/Bucharest': 'RO',
+  'Europe/Budapest': 'HU',
+  'Europe/Sofia': 'BG',
+  'Europe/Zagreb': 'HR',
+  'Europe/Bratislava': 'SK',
+  'Europe/Ljubljana': 'SI',
+  'Europe/Belgrade': 'RS',
+  'Europe/Kyiv': 'UA',
+  'Europe/Moscow': 'RU',
+  'Europe/Istanbul': 'TR',
+  'Europe/Athens': 'GR',
+
+  // South Asia
+  'Asia/Kolkata': 'IN',
+  'Asia/Calcutta': 'IN',
+  'Asia/Karachi': 'PK',
+  'Asia/Dhaka': 'BD',
+  'Asia/Colombo': 'LK',
+  'Asia/Kathmandu': 'NP',
+
+  // East Asia
+  'Asia/Tokyo': 'JP',
+  'Asia/Seoul': 'KR',
+  'Asia/Shanghai': 'CN',
+  'Asia/Hong_Kong': 'CN',
+  'Asia/Taipei': 'TW',
+
+  // Southeast Asia
+  'Asia/Bangkok': 'TH',
+  'Asia/Ho_Chi_Minh': 'VN',
+  'Asia/Jakarta': 'ID',
+  'Asia/Kuala_Lumpur': 'MY',
+  'Asia/Manila': 'PH',
+  'Asia/Singapore': 'SG',
+
+  // Oceania
+  'Australia/Sydney': 'AU',
+  'Australia/Melbourne': 'AU',
+  'Australia/Brisbane': 'AU',
+  'Australia/Perth': 'AU',
+  'Australia/Adelaide': 'AU',
+  'Pacific/Auckland': 'NZ',
+
+  // South America
+  'America/Sao_Paulo': 'BR',
+  'America/Rio_Branco': 'BR',
+  'America/Argentina/Buenos_Aires': 'AR',
+  'America/Bogota': 'CO',
+  'America/Santiago': 'CL',
+
+  // Middle East
+  'Asia/Riyadh': 'SA',
+  'Asia/Dubai': 'AE',
+  'Asia/Jerusalem': 'IL',
+  'Africa/Cairo': 'EG',
+}
+
+/** Mapping of BCP-47 locale strings to ISO country codes */
+export const LOCALE_TO_COUNTRY: Record<string, string> = {
+  'en-US': 'US',
+  'en-GB': 'GB',
+  'en-AU': 'AU',
+  'en-CA': 'CA',
+  'en-NZ': 'NZ',
+  'en-IE': 'IE',
+  'en-IN': 'IN',
+  'en-SG': 'SG',
+  'en-PH': 'PH',
+  'en-MY': 'MY',
+  'en-ZA': 'ZA',
+  'hi-IN': 'IN',
+  'te-IN': 'IN',
+  'ta-IN': 'IN',
+  'ur-PK': 'PK',
+  'pa-IN': 'IN',
+  'bn-IN': 'IN',
+  'bn-BD': 'BD',
+  'gu-IN': 'IN',
+  'mr-IN': 'IN',
+  'kn-IN': 'IN',
+  'ml-IN': 'IN',
+  'fr-FR': 'FR',
+  'fr-CA': 'CA',
+  'fr-BE': 'BE',
+  'fr-CH': 'CH',
+  'es-ES': 'ES',
+  'es-MX': 'MX',
+  'es-AR': 'AR',
+  'es-CO': 'CO',
+  'es-CL': 'CL',
+  'de-DE': 'DE',
+  'de-AT': 'AT',
+  'de-CH': 'CH',
+  'it-IT': 'IT',
+  'it-CH': 'CH',
+  'pt-PT': 'PT',
+  'pt-BR': 'BR',
+  'nl-NL': 'NL',
+  'nl-BE': 'BE',
+  'sv-SE': 'SE',
+  'da-DK': 'DK',
+  'nb-NO': 'NO',
+  'nn-NO': 'NO',
+  'fi-FI': 'FI',
+  'pl-PL': 'PL',
+  'cs-CZ': 'CZ',
+  'ro-RO': 'RO',
+  'hu-HU': 'HU',
+  'bg-BG': 'BG',
+  'hr-HR': 'HR',
+  'sk-SK': 'SK',
+  'sl-SI': 'SI',
+  'sr-RS': 'SR',
+  'uk-UA': 'UA',
+  'el-GR': 'GR',
+  'ru-RU': 'RU',
+  'ja-JP': 'JP',
+  'ko-KR': 'KR',
+  'zh-CN': 'CN',
+  'zh-TW': 'TW',
+  'zh-HK': 'CN',
+  'ar-SA': 'SA',
+  'ar-AE': 'AE',
+  'ar-EG': 'EG',
+  'he-IL': 'IL',
+  'tr-TR': 'TR',
+  'th-TH': 'TH',
+  'vi-VN': 'VN',
+  'id-ID': 'ID',
+  'ms-MY': 'MY',
+}
+
+/**
+ * Detect the user's country from environment signals.
+ * Strategy: timezone mapping -> navigator.languages locale mapping -> fallback 'US'
+ */
+export function detectCountry(): string {
+  // 1. Try timezone mapping
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone
+    if (tz && TIMEZONE_TO_COUNTRY[tz]) {
+      return TIMEZONE_TO_COUNTRY[tz]
+    }
+  } catch {
+    // Intl may not be available
+  }
+
+  // 2. Try navigator.languages locale mapping
+  try {
+    if (typeof navigator !== 'undefined') {
+      const languages = navigator.languages
+      if (languages && languages.length > 0) {
+        for (const locale of languages) {
+          if (LOCALE_TO_COUNTRY[locale]) {
+            return LOCALE_TO_COUNTRY[locale]
+          }
+        }
+      }
+    }
+  } catch {
+    // navigator may not be available
+  }
+
+  // 3. Fallback
+  return 'US'
+}
+
+/**
+ * Detect the user's preferred language from navigator.languages.
+ * Returns the first language from navigator.languages, or 'en' as fallback.
+ */
+export function detectLanguage(): string {
+  try {
+    if (typeof navigator !== 'undefined') {
+      const languages = (navigator as any).languages
+      if (languages && languages.length > 0) {
+        return languages[0]
+      }
+      if ((navigator as any).language) {
+        return (navigator as any).language
+      }
+    }
+  } catch {
+    // navigator may not be available
+  }
+  return 'en'
+}

package/dist/i18n/index.ts

@@ -0,0 +1,47 @@
+// Languages
+export type { Language } from './languages.js'
+export {
+  LANGUAGES,
+  getLanguage,
+  getSupportedLanguages,
+  getLanguagesByGroup,
+  getLanguageName,
+  isRTL,
+  getTtsLang,
+} from './languages.js'
+
+// Countries
+export type { Country } from './countries.js'
+export {
+  COUNTRIES,
+  getCountry,
+  getCountryFlag,
+  getCountryName,
+  getDefaultLanguagesForCountry,
+} from './countries.js'
+
+// Region detection
+export {
+  TIMEZONE_TO_COUNTRY,
+  LOCALE_TO_COUNTRY,
+  detectCountry,
+  detectLanguage,
+} from './detect-region.js'
+
+// Voice registry
+export type { VoiceOption } from './voice-registry.js'
+export {
+  VOICES,
+  getVoicesForLanguage,
+  getBestVoice,
+  getVoicesByProvider,
+} from './voice-registry.js'
+
+// Locale utilities
+export {
+  LOCALE_DISPLAY_NAMES,
+  getLocaleDisplayName,
+  getStoredLocale,
+  setStoredLocale,
+  getLocalizedValue,
+} from './locale-utils.js'

package/dist/i18n/languages.ts

@@ -0,0 +1,181 @@
+/**
+ * Language type and registry for i18n support.
+ */
+
+export interface Language {
+  code: string
+  name: string
+  nativeName: string
+  direction: 'ltr' | 'rtl'
+  group?: string
+}
+
+export const LANGUAGES: Record<string, Language> = {
+  // English variants
+  'en':    { code: 'en',    name: 'English',                 nativeName: 'English',        direction: 'ltr', group: 'English' },
+  'en-US': { code: 'en-US', name: 'English (US)',            nativeName: 'English (US)',   direction: 'ltr', group: 'English' },
+  'en-GB': { code: 'en-GB', name: 'English (UK)',            nativeName: 'English (UK)',   direction: 'ltr', group: 'English' },
+  'en-IN': { code: 'en-IN', name: 'English (India)',         nativeName: 'English (India)',direction: 'ltr', group: 'English' },
+
+  // Indian languages
+  'hi': { code: 'hi', name: 'Hindi',      nativeName: 'हिन्दी',    direction: 'ltr', group: 'Indian' },
+  'te': { code: 'te', name: 'Telugu',     nativeName: 'తెలుగు',    direction: 'ltr', group: 'Indian' },
+  'ta': { code: 'ta', name: 'Tamil',      nativeName: 'தமிழ்',     direction: 'ltr', group: 'Indian' },
+  'ur': { code: 'ur', name: 'Urdu',       nativeName: 'اردو',      direction: 'rtl', group: 'Indian' },
+  'pa': { code: 'pa', name: 'Punjabi',    nativeName: 'ਪੰਜਾਬੀ',    direction: 'ltr', group: 'Indian' },
+  'bn': { code: 'bn', name: 'Bengali',    nativeName: 'বাংলা',     direction: 'ltr', group: 'Indian' },
+  'gu': { code: 'gu', name: 'Gujarati',   nativeName: 'ગુજરાતી',   direction: 'ltr', group: 'Indian' },
+  'mr': { code: 'mr', name: 'Marathi',    nativeName: 'मराठी',      direction: 'ltr', group: 'Indian' },
+  'kn': { code: 'kn', name: 'Kannada',    nativeName: 'ಕನ್ನಡ',     direction: 'ltr', group: 'Indian' },
+  'ml': { code: 'ml', name: 'Malayalam',   nativeName: 'മലയാളം',    direction: 'ltr', group: 'Indian' },
+
+  // Western European
+  'fr': { code: 'fr', name: 'French',     nativeName: 'Français',   direction: 'ltr', group: 'European' },
+  'es': { code: 'es', name: 'Spanish',    nativeName: 'Español',    direction: 'ltr', group: 'European' },
+  'de': { code: 'de', name: 'German',     nativeName: 'Deutsch',    direction: 'ltr', group: 'European' },
+  'it': { code: 'it', name: 'Italian',    nativeName: 'Italiano',   direction: 'ltr', group: 'European' },
+  'pt': { code: 'pt', name: 'Portuguese', nativeName: 'Português',  direction: 'ltr', group: 'European' },
+  'pt-BR': { code: 'pt-BR', name: 'Portuguese (Brazil)', nativeName: 'Português (Brasil)', direction: 'ltr', group: 'European' },
+  'nl': { code: 'nl', name: 'Dutch',      nativeName: 'Nederlands',  direction: 'ltr', group: 'European' },
+
+  // Nordic
+  'sv': { code: 'sv', name: 'Swedish',    nativeName: 'Svenska',    direction: 'ltr', group: 'European' },
+  'da': { code: 'da', name: 'Danish',     nativeName: 'Dansk',      direction: 'ltr', group: 'European' },
+  'no': { code: 'no', name: 'Norwegian',  nativeName: 'Norsk',      direction: 'ltr', group: 'European' },
+  'fi': { code: 'fi', name: 'Finnish',    nativeName: 'Suomi',      direction: 'ltr', group: 'European' },
+
+  // Eastern European
+  'pl': { code: 'pl', name: 'Polish',     nativeName: 'Polski',     direction: 'ltr', group: 'European' },
+  'cs': { code: 'cs', name: 'Czech',      nativeName: 'Čeština',    direction: 'ltr', group: 'European' },
+  'ro': { code: 'ro', name: 'Romanian',   nativeName: 'Română',     direction: 'ltr', group: 'European' },
+  'hu': { code: 'hu', name: 'Hungarian',  nativeName: 'Magyar',     direction: 'ltr', group: 'European' },
+  'bg': { code: 'bg', name: 'Bulgarian',  nativeName: 'Български',  direction: 'ltr', group: 'European' },
+  'hr': { code: 'hr', name: 'Croatian',   nativeName: 'Hrvatski',   direction: 'ltr', group: 'European' },
+  'sk': { code: 'sk', name: 'Slovak',     nativeName: 'Slovenčina',  direction: 'ltr', group: 'European' },
+  'sl': { code: 'sl', name: 'Slovenian',  nativeName: 'Slovenščina', direction: 'ltr', group: 'European' },
+  'sr': { code: 'sr', name: 'Serbian',    nativeName: 'Srpski',     direction: 'ltr', group: 'European' },
+  'uk': { code: 'uk', name: 'Ukrainian',  nativeName: 'Українська', direction: 'ltr', group: 'European' },
+  'el': { code: 'el', name: 'Greek',      nativeName: 'Ελληνικά',   direction: 'ltr', group: 'European' },
+  'ru': { code: 'ru', name: 'Russian',    nativeName: 'Русский',    direction: 'ltr', group: 'European' },
+
+  // East Asian
+  'ja': { code: 'ja', name: 'Japanese',   nativeName: '日本語',     direction: 'ltr', group: 'East Asian' },
+  'ko': { code: 'ko', name: 'Korean',     nativeName: '한국어',     direction: 'ltr', group: 'East Asian' },
+  'zh': { code: 'zh', name: 'Chinese (Simplified)',  nativeName: '中文（简体）', direction: 'ltr', group: 'East Asian' },
+  'zh-TW': { code: 'zh-TW', name: 'Chinese (Traditional)', nativeName: '中文（繁體）', direction: 'ltr', group: 'East Asian' },
+
+  // Middle Eastern
+  'ar': { code: 'ar', name: 'Arabic',     nativeName: 'العربية',    direction: 'rtl', group: 'Middle Eastern' },
+  'he': { code: 'he', name: 'Hebrew',     nativeName: 'עברית',      direction: 'rtl', group: 'Middle Eastern' },
+  'tr': { code: 'tr', name: 'Turkish',    nativeName: 'Türkçe',     direction: 'ltr', group: 'Middle Eastern' },
+
+  // Southeast Asian
+  'th': { code: 'th', name: 'Thai',       nativeName: 'ไทย',        direction: 'ltr', group: 'Southeast Asian' },
+  'vi': { code: 'vi', name: 'Vietnamese', nativeName: 'Tiếng Việt', direction: 'ltr', group: 'Southeast Asian' },
+  'id': { code: 'id', name: 'Indonesian', nativeName: 'Bahasa Indonesia', direction: 'ltr', group: 'Southeast Asian' },
+  'ms': { code: 'ms', name: 'Malay',      nativeName: 'Bahasa Melayu',    direction: 'ltr', group: 'Southeast Asian' },
+}
+
+/** BCP-47 TTS language tag mappings for base language codes */
+const TTS_LANG_MAP: Record<string, string> = {
+  'en':    'en-US',
+  'en-US': 'en-US',
+  'en-GB': 'en-GB',
+  'en-IN': 'en-IN',
+  'hi':    'hi-IN',
+  'te':    'te-IN',
+  'ta':    'ta-IN',
+  'ur':    'ur-PK',
+  'pa':    'pa-IN',
+  'bn':    'bn-IN',
+  'gu':    'gu-IN',
+  'mr':    'mr-IN',
+  'kn':    'kn-IN',
+  'ml':    'ml-IN',
+  'fr':    'fr-FR',
+  'es':    'es-ES',
+  'de':    'de-DE',
+  'it':    'it-IT',
+  'pt':    'pt-PT',
+  'pt-BR': 'pt-BR',
+  'nl':    'nl-NL',
+  'sv':    'sv-SE',
+  'da':    'da-DK',
+  'no':    'nb-NO',
+  'fi':    'fi-FI',
+  'pl':    'pl-PL',
+  'cs':    'cs-CZ',
+  'ro':    'ro-RO',
+  'hu':    'hu-HU',
+  'bg':    'bg-BG',
+  'hr':    'hr-HR',
+  'sk':    'sk-SK',
+  'sl':    'sl-SI',
+  'sr':    'sr-RS',
+  'uk':    'uk-UA',
+  'el':    'el-GR',
+  'ru':    'ru-RU',
+  'ja':    'ja-JP',
+  'ko':    'ko-KR',
+  'zh':    'zh-CN',
+  'zh-TW': 'zh-TW',
+  'ar':    'ar-SA',
+  'he':    'he-IL',
+  'tr':    'tr-TR',
+  'th':    'th-TH',
+  'vi':    'vi-VN',
+  'id':    'id-ID',
+  'ms':    'ms-MY',
+}
+
+/**
+ * Get a language by its code.
+ */
+export function getLanguage(code: string): Language | undefined {
+  return LANGUAGES[code]
+}
+
+/**
+ * Get all supported languages as an array.
+ */
+export function getSupportedLanguages(): Language[] {
+  return Object.values(LANGUAGES)
+}
+
+/**
+ * Get languages grouped by their language family/group.
+ */
+export function getLanguagesByGroup(): Record<string, Language[]> {
+  const groups: Record<string, Language[]> = {}
+  for (const lang of Object.values(LANGUAGES)) {
+    const group = lang.group ?? 'Other'
+    if (!groups[group]) {
+      groups[group] = []
+    }
+    groups[group].push(lang)
+  }
+  return groups
+}
+
+/**
+ * Get the display name for a language code.
+ * Returns empty string if the code is not found.
+ */
+export function getLanguageName(code: string): string {
+  return LANGUAGES[code]?.name ?? ''
+}
+
+/**
+ * Check if a language code represents a right-to-left language.
+ */
+export function isRTL(code: string): boolean {
+  return LANGUAGES[code]?.direction === 'rtl'
+}
+
+/**
+ * Get the BCP-47 language tag suitable for TTS engines.
+ * Returns the code itself if no mapping exists.
+ */
+export function getTtsLang(code: string): string {
+  return TTS_LANG_MAP[code] ?? code
+}