@tracearr/translations 0.1.0

package/src/language.ts

@@ -0,0 +1,270 @@
+/**
+ * Language detection and management utilities.
+ *
+ * Works in both web (browser) and mobile (React Native/Expo) environments.
+ * Language codes use full locale format (e.g., 'fr-FR', 'zh-CN') except for
+ * English which uses 'en' as the base/fallback language.
+ */
+
+import i18n from 'i18next';
+
+// Locale loader — set by config.ts (web) or config.mobile.ts (mobile) at import time
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+let _loadLocaleFn: (lang: string) => Promise<void> = async () => {};
+
+/** @internal */
+export function _registerLocaleLoader(fn: (lang: string) => Promise<void>): void {
+  _loadLocaleFn = fn;
+}
+
+// Storage key for persisted language preference
+const LANGUAGE_STORAGE_KEY = 'tracearr_language';
+
+/**
+ * Supported languages with display names.
+ * Add new languages here when adding translations.
+ */
+export const languageNames = {
+  en: 'English',
+  'af-ZA': 'Afrikaans',
+  'ar-SA': 'العربية',
+  'ca-ES': 'Català',
+  'cs-CZ': 'Čeština',
+  'da-DK': 'Dansk',
+  'de-DE': 'Deutsch',
+  'el-GR': 'Ελληνικά',
+  'es-ES': 'Español',
+  'fi-FI': 'Suomi',
+  'fr-FR': 'Français',
+  'he-IL': 'עברית',
+  'hu-HU': 'Magyar',
+  'it-IT': 'Italiano',
+  'ja-JP': '日本語',
+  'ko-KR': '한국어',
+  'nl-NL': 'Nederlands',
+  'no-NO': 'Norsk',
+  'pl-PL': 'Polski',
+  'pt-BR': 'Português (Brasil)',
+  'pt-PT': 'Português (Portugal)',
+  'ro-RO': 'Română',
+  'ru-RU': 'Русский',
+  'sr-SP': 'Српски',
+  'sv-SE': 'Svenska',
+  'tr-TR': 'Türkçe',
+  'uk-UA': 'Українська',
+  'vi-VN': 'Tiếng Việt',
+  'zh-CN': '中文 (简体)',
+  'zh-TW': '中文 (繁體)',
+} as const;
+
+export type LanguageCode = keyof typeof languageNames;
+
+/**
+ * Get the list of supported language codes.
+ */
+export function getSupportedLanguages(): string[] {
+  return Object.keys(languageNames);
+}
+
+/**
+ * Check if a language code is supported (exact match).
+ */
+export function isLanguageSupported(lang: string): boolean {
+  if (!lang || typeof lang !== 'string') return false;
+  return lang in languageNames;
+}
+
+/**
+ * Resolve a language code to the best matching supported locale.
+ *
+ * Handles exact matches, legacy two-letter codes (e.g., 'fr' → 'fr-FR'),
+ * and browser locale strings (e.g., 'zh-Hant-TW' → 'zh-TW').
+ *
+ * Returns null if no match is found.
+ */
+export function resolveLocale(lang: string): string | null {
+  if (!lang || typeof lang !== 'string') return null;
+
+  // Normalize: lowercase language, uppercase region
+  const normalized = normalizeLocaleCode(lang);
+
+  // Exact match (e.g., 'zh-CN', 'en')
+  if (normalized in languageNames) return normalized;
+
+  // Try base language match (e.g., 'fr' → 'fr-FR', 'zh' → 'zh-CN')
+  const baseLang = normalized.split('-')[0];
+  if (!baseLang) return null;
+
+  // 'en' is a direct match
+  if (baseLang === 'en') return 'en';
+
+  // Find first supported locale starting with the base language
+  const match = Object.keys(languageNames).find((code) => code.startsWith(baseLang + '-'));
+  return match ?? null;
+}
+
+/**
+ * Normalize a locale code: lowercase language, uppercase region.
+ * e.g., 'ZH-cn' → 'zh-CN', 'FR' → 'fr', 'pt-br' → 'pt-BR'
+ */
+function normalizeLocaleCode(code: string): string {
+  const trimmed = code.trim();
+  const [lang, region] = trimmed.split('-');
+  if (!region) return trimmed.toLowerCase();
+  return `${lang?.toLowerCase()}-${region.toUpperCase()}`;
+}
+
+/**
+ * Detect the user's preferred language.
+ *
+ * Priority order:
+ * 1. Stored preference (localStorage/AsyncStorage)
+ * 2. Browser/device language (checks all preferred languages)
+ * 3. Fallback to 'en'
+ *
+ * @param storage - Optional storage adapter for React Native (AsyncStorage)
+ */
+export async function detectLanguage(storage?: {
+  getItem: (key: string) => Promise<string | null>;
+}): Promise<string> {
+  // 1. Check stored preference
+  try {
+    const stored = await getStoredLanguage(storage);
+    if (stored) {
+      const resolved = resolveLocale(stored);
+      if (resolved) return resolved;
+    }
+  } catch (error) {
+    console.warn('[i18n] Failed to get stored language:', error);
+  }
+
+  // 2. Check browser/device language
+  const detected = detectSystemLanguage();
+  if (detected) return detected;
+
+  // 3. Fallback
+  return 'en';
+}
+
+/**
+ * Detect the system/browser language.
+ * Checks all preferred languages in order (navigator.languages).
+ * Works in both web and React Native environments.
+ */
+export function detectSystemLanguage(): string | null {
+  if (typeof navigator === 'undefined') return null;
+
+  // Check all preferred languages in order
+  const languages = navigator.languages || (navigator.language ? [navigator.language] : []);
+
+  for (const lang of languages) {
+    if (!lang) continue;
+    const resolved = resolveLocale(lang);
+    if (resolved) return resolved;
+  }
+
+  return null;
+}
+
+/**
+ * Get the stored language preference.
+ * Safely handles localStorage exceptions (private browsing, SSR, etc.).
+ */
+async function getStoredLanguage(storage?: {
+  getItem: (key: string) => Promise<string | null>;
+}): Promise<string | null> {
+  // React Native with AsyncStorage
+  if (storage) {
+    try {
+      return await storage.getItem(LANGUAGE_STORAGE_KEY);
+    } catch (error) {
+      console.warn('[i18n] AsyncStorage read failed:', error);
+      return null;
+    }
+  }
+
+  // Browser with localStorage
+  if (typeof localStorage !== 'undefined') {
+    try {
+      return localStorage.getItem(LANGUAGE_STORAGE_KEY);
+    } catch (error) {
+      // Fails in private browsing, SSR, or when storage is disabled
+      console.warn('[i18n] localStorage read failed:', error);
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Store the language preference.
+ * Safely handles localStorage exceptions.
+ */
+async function setStoredLanguage(
+  lang: string,
+  storage?: { setItem: (key: string, value: string) => Promise<void> }
+): Promise<void> {
+  // React Native with AsyncStorage
+  if (storage) {
+    try {
+      await storage.setItem(LANGUAGE_STORAGE_KEY, lang);
+    } catch (error) {
+      console.warn('[i18n] AsyncStorage write failed:', error);
+    }
+    return;
+  }
+
+  // Browser with localStorage
+  if (typeof localStorage !== 'undefined') {
+    try {
+      localStorage.setItem(LANGUAGE_STORAGE_KEY, lang);
+    } catch (error) {
+      // Fails in private browsing, SSR, or when quota exceeded
+      console.warn('[i18n] localStorage write failed:', error);
+    }
+  }
+}
+
+/**
+ * Change the current language and persist the preference.
+ *
+ * @param lang - Locale code (e.g., 'en', 'fr-FR', 'zh-CN')
+ * @param storage - Optional storage adapter for React Native
+ * @throws Error if language code is invalid or unsupported
+ */
+export async function changeLanguage(
+  lang: string,
+  storage?: { setItem: (key: string, value: string) => Promise<void> }
+): Promise<void> {
+  // Validate input
+  if (!lang || typeof lang !== 'string') {
+    throw new Error(`Invalid language code: ${String(lang)}`);
+  }
+
+  const resolved = resolveLocale(lang);
+
+  if (!resolved) {
+    throw new Error(
+      `Language '${lang}' is not supported. Available: ${getSupportedLanguages().join(', ')}`
+    );
+  }
+
+  await _loadLocaleFn(resolved);
+  await i18n.changeLanguage(resolved);
+  await setStoredLanguage(resolved, storage);
+}
+
+/**
+ * Get the current language.
+ */
+export function getCurrentLanguage(): string {
+  return i18n.language || 'en';
+}
+
+/**
+ * Get the display name for a language code.
+ */
+export function getLanguageDisplayName(lang: string): string {
+  return languageNames[lang as LanguageCode] || lang;
+}

package/src/locales/af-ZA/common.json

@@ -0,0 +1,308 @@
+{
+  "actions": {
+    "acknowledge": "Acknowledge",
+    "add": "Add",
+    "apply": "Apply",
+    "back": "Back",
+    "cancel": "Cancel",
+    "clear": "Clear",
+    "close": "Close",
+    "collapse": "Collapse",
+    "confirm": "Confirm",
+    "connect": "Connect",
+    "continue": "Continue",
+    "copy": "Copy",
+    "create": "Create",
+    "delete": "Delete",
+    "deselectAll": "Deselect All",
+    "disconnect": "Disconnect",
+    "dismiss": "Dismiss",
+    "download": "Download",
+    "edit": "Edit",
+    "expand": "Expand",
+    "export": "Export",
+    "filter": "Filter",
+    "goHome": "Go Home",
+    "grantPermission": "Grant Permission",
+    "import": "Import",
+    "later": "Later",
+    "next": "Next",
+    "openSettings": "Open Settings",
+    "previous": "Previous",
+    "refresh": "Refresh",
+    "remove": "Remove",
+    "reset": "Reset",
+    "retry": "Retry",
+    "save": "Save",
+    "search": "Search",
+    "select": "Select",
+    "selectAll": "Select All",
+    "showLess": "Show Less",
+    "showMore": "Show More",
+    "signIn": "Sign In",
+    "signOut": "Sign Out",
+    "signUp": "Sign Up",
+    "sort": "Sort",
+    "submit": "Submit",
+    "sync": "Sync",
+    "terminate": "Terminate",
+    "test": "Test",
+    "tryAgain": "Try Again",
+    "update": "Update",
+    "upload": "Upload",
+    "view": "View",
+    "viewAll": "View All",
+    "viewOnGithub": "View on GitHub",
+    "viewProfile": "View Profile"
+  },
+  "beta": "beta",
+  "confirmations": {
+    "deleteMessage": "Are you sure you want to delete this? This action cannot be undone.",
+    "deleteTitle": "Confirm Delete",
+    "unsavedChanges": "You have unsaved changes. Are you sure you want to leave?"
+  },
+  "count": {
+    "alert_one": "{{count}} alert",
+    "alert_other": "{{count}} alerts",
+    "device_one": "{{count}} device",
+    "device_other": "{{count}} devices",
+    "error_one": "{{count}} error",
+    "error_other": "{{count}} errors",
+    "item_one": "{{count}} item",
+    "item_other": "{{count}} items",
+    "library_one": "{{count}} library",
+    "library_other": "{{count}} libraries",
+    "location_one": "{{count}} location",
+    "location_other": "{{count}} locations",
+    "result_one": "{{count}} result",
+    "result_other": "{{count}} results",
+    "rule_one": "{{count}} rule",
+    "rule_other": "{{count}} rules",
+    "selected_one": "{{count}} selected",
+    "selected_other": "{{count}} selected",
+    "server_one": "{{count}} server",
+    "server_other": "{{count}} servers",
+    "session_one": "{{count}} session",
+    "session_other": "{{count}} sessions",
+    "stream_one": "{{count}} stream",
+    "stream_other": "{{count}} streams",
+    "user_one": "{{count}} user",
+    "user_other": "{{count}} users",
+    "usersAdded_one": "{{count}} user added",
+    "usersAdded_other": "{{count}} users added",
+    "usersUpdated_one": "{{count}} user updated",
+    "usersUpdated_other": "{{count}} users updated",
+    "violation_one": "{{count}} violation",
+    "violation_other": "{{count}} violations"
+  },
+  "duration": {
+    "day_one": "{{count}} day",
+    "day_other": "{{count}} days",
+    "hour_one": "{{count}} hour",
+    "hour_other": "{{count}} hours",
+    "minute_one": "{{count}} minute",
+    "minute_other": "{{count}} minutes",
+    "second_one": "{{count}} second",
+    "second_other": "{{count}} seconds"
+  },
+  "empty": {
+    "noData": "No data available",
+    "noDeviceData": "No device data available",
+    "noItems": "No items",
+    "noJobHistory": "No job history yet",
+    "noLocationData": "No location data available",
+    "noResults": "No results found",
+    "noSessionsFound": "No sessions found",
+    "noUserData": "No user data available"
+  },
+  "errors": {
+    "badRequest": "Invalid request",
+    "cannotReachServer": "Cannot reach server. Check URL and network connection.",
+    "conflict": "A conflict occurred",
+    "connectionFailed": "Connection failed",
+    "connectionTimedOut": "Connection timed out. Check your server URL.",
+    "failedToLoad": "Failed to load {{item}}",
+    "forbidden": "Access denied",
+    "generic": "An error occurred",
+    "networkError": "Network connection failed",
+    "notFound": "Not found",
+    "pageNotFound": "Page Not Found",
+    "pageNotFoundDesc": "The page you're looking for doesn't exist or has been moved.",
+    "rateLimited": "Too many requests. Please try again later",
+    "serverError": "Server error",
+    "somethingWentWrong": "Something went wrong",
+    "timeout": "Request timed out",
+    "unauthorized": "You are not authorized to perform this action",
+    "unexpectedError": "An unexpected error occurred. Please try again."
+  },
+  "labels": {
+    "actions": "Actions",
+    "active": "Active",
+    "activeStreams": "Active Streams",
+    "apiKey": "API Key",
+    "bandwidth": "Bandwidth",
+    "content": "Content",
+    "created": "Created",
+    "data": "Data",
+    "date": "Date",
+    "days": "days",
+    "device": "Device",
+    "deviceId": "Device ID",
+    "disabled": "Disabled",
+    "duration": "Duration",
+    "filters": "Filters",
+    "ipAddress": "IP Address",
+    "items": "Items",
+    "joined": "Joined",
+    "lastActivity": "Last Activity",
+    "loadMore": "Load More",
+    "location": "Location",
+    "media": "Media",
+    "mediaLength": "Media length",
+    "name": "Name",
+    "never": "Never",
+    "pausedTime": "Paused Time",
+    "platform": "Platform",
+    "player": "Player",
+    "product": "Product",
+    "progress": "Progress",
+    "quality": "Quality",
+    "rank": "Rank",
+    "reason": "Reason",
+    "recentSessions": "Recent Sessions",
+    "resolution": "Resolution",
+    "rule": "Rule",
+    "segments": "segments",
+    "server": "Server",
+    "serverOwner": "Server Owner",
+    "sessionDetails": "Session Details",
+    "sessions": "Sessions",
+    "severity": "Severity",
+    "size": "Size",
+    "started": "Started",
+    "status": "Status",
+    "stopped": "Stopped",
+    "streamDetails": "Stream Details",
+    "total": "total",
+    "totalSessions": "Total Sessions",
+    "transcodeReason": "Transcode Reason",
+    "trustScore": "Trust Score",
+    "type": "Type",
+    "unknown": "Unknown",
+    "user": "User",
+    "watchTime": "Watch Time",
+    "when": "When"
+  },
+  "media": {
+    "episode": "Episode",
+    "episode_plural": "Episodes",
+    "liveTV": "Live TV",
+    "movie": "Movie",
+    "movie_plural": "Movies",
+    "music": "Music",
+    "photo": "Photo",
+    "track": "Track",
+    "track_plural": "Tracks",
+    "tv": "TV",
+    "tvShows": "TV Shows"
+  },
+  "messages": {
+    "noChangesDetected": "No changes detected"
+  },
+  "or": "or",
+  "periods": {
+    "byDay": "By Day",
+    "byHour": "By Hour",
+    "last30Days": "Last 30 Days",
+    "last7Days": "Last 7 Days",
+    "lastYear": "Last Year"
+  },
+  "playback": {
+    "directPlay": "Direct Play",
+    "directStream": "Direct Stream",
+    "paused": "Paused",
+    "playing": "Playing",
+    "stopped": "Stopped",
+    "transcode": "Transcode"
+  },
+  "relativeTime": {
+    "day_one": "{{count}} day ago",
+    "day_other": "{{count}} days ago",
+    "hour_one": "{{count}} hour ago",
+    "hour_other": "{{count}} hours ago",
+    "justNow": "Just now",
+    "minute_one": "{{count}} minute ago",
+    "minute_other": "{{count}} minutes ago",
+    "month_one": "{{count}} month ago",
+    "month_other": "{{count}} months ago",
+    "second_one": "{{count}} second ago",
+    "second_other": "{{count}} seconds ago",
+    "week_one": "{{count}} week ago",
+    "week_other": "{{count}} weeks ago",
+    "year_one": "{{count}} year ago",
+    "year_other": "{{count}} years ago"
+  },
+  "search": {
+    "placeholder": "Search...",
+    "searchTitles": "Search titles, users...",
+    "searchUsers": "Search users..."
+  },
+  "servers": {
+    "emby": "Emby",
+    "jellyfin": "Jellyfin",
+    "plex": "Plex"
+  },
+  "severity": {
+    "high": "High",
+    "low": "Low",
+    "warning": "Warning"
+  },
+  "states": {
+    "acknowledged": "Acknowledged",
+    "acknowledging": "Acknowledging...",
+    "active": "Active",
+    "completed": "Completed",
+    "connected": "Connected",
+    "connecting": "Connecting...",
+    "deleting": "Deleting...",
+    "disabled": "Disabled",
+    "disconnected": "Disconnected",
+    "dismissing": "Dismissing...",
+    "enabled": "Enabled",
+    "error": "Error",
+    "failed": "Failed",
+    "inactive": "Inactive",
+    "loading": "Loading...",
+    "offline": "Offline",
+    "online": "Online",
+    "pending": "Pending",
+    "saving": "Saving...",
+    "success": "Success"
+  },
+  "table": {
+    "selectAllOnPage": "Select all on page",
+    "selectAllTotal": "Select all {{total}} items",
+    "selectRow": "Select row"
+  },
+  "time": {
+    "allTime": "All Time",
+    "now": "Now",
+    "thisMonth": "This Month",
+    "thisWeek": "This Week",
+    "today": "Today",
+    "yesterday": "Yesterday"
+  },
+  "units": {
+    "km": "km",
+    "kmh": "km/h",
+    "mi": "mi",
+    "mph": "mph"
+  },
+  "validation": {
+    "invalidEmail": "Please enter a valid email address",
+    "invalidUrl": "Please enter a valid URL",
+    "maxLength": "Must be at most {{max}} characters",
+    "minLength": "Must be at least {{min}} characters",
+    "required": "This field is required"
+  }
+}