Localization (i18n)

Universal Game Launcher implements an industry-standard, library-driven internationalization architecture powered by i18next. Rather than hard-coding static translation dictionaries into the desktop binary, the launcher dynamically loads UI localization and gaming taxonomy directly from the HELIX Gaming DB REST API (https://api.helix-origin.club) with persistent offline caching.

🌐 Dynamic Cloud & Offline-First Architecture

┌────────────────────────────────────────────────────────┐
│             User Selects Language in Settings          │
│       (e.g., Japanese "ja", German "de", Russian "ru") │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│             Universal Game Launcher i18next            │
│         src/lib/i18n/index.ts · Svelte 5 Stores        │
└───────────────────────────┬────────────────────────────┘
                            │
               Check local offline cache
              ┌─────────────┴─────────────┐
              ▼                           ▼
      [Cache Hit]                 [Cache Miss / Stale]
Read SQLite Persistent KV      Fetch Remote i18n Bundle
  `i18n_bundle_{code}`           `https://api.helix-origin.club`
  Instant 0ms UI load            `/api/v2/i18n/{code}/bundle.json`
              │                           │
              └─────────────┬─────────────┘
                            │ Inject namespaces (app, genres,
                            │ categories, platforms, common)
                            ▼
┌────────────────────────────────────────────────────────┐
│         Instant Reactive UI Re-render ($t, $locale)    │
│    Zero layout shift · Bi-directional (RTL) Support    │
└────────────────────────────────────────────────────────┘

⚡ Key Architectural Advantages

1. Library-Driven & Extensible (No Hardcoded Strings)

All localization dictionaries reside centrally in the open-source HELIX Gaming DB catalog under locales/{code}/. Client applications load translations dynamically over HTTPS, allowing community translators to improve translations and add missing keys via Pull Requests without requiring a new desktop app release.

2. Dual UI & Metadata Taxonomy Support

The dynamic i18n bundle (/api/v2/i18n/{code}/bundle.json) delivers multi-namespace coverage in a single HTTP request:

• app: Complete launcher UI dictionaries (navigation, library, settings, dialogs, status, errors).
• genres: Localized video game genres (Action, Metroidvania, RPG, Visual Novel, etc.).
• categories: Game categories (Single-player, Multi-player, Co-op, VR, etc.).
• platforms: Platform labels (Windows, macOS, Linux, Steam Deck, Retro Consoles).
• common: Universal UI strings (Save, Cancel, Refresh, Delete, Search, Loading).

3. High-Performance Offline Caching

When a language bundle is fetched from https://api.helix-origin.club, it is automatically persisted to the launcher’s local SQLite Key-Value storage (i18n_bundle_{langCode}) with a 7-day retention period. When launching offline or on an airplane, the launcher instantly boots with the user’s localized interface with zero network latency.

4. Robust Fallback Chains & Safe Interpolation

If an individual string or key has not yet been translated into a specific language, i18next automatically resolves the key from the fallback English (en) dictionary. Template parameters such as {count} or {games} interpolate safely without breaking formatting.

5. Native Bi-directional Layout (RTL)

The reactive $activeLanguage store automatically detects right-to-left languages (e.g. Arabic ar) and dynamically updates the document root with dir="rtl", flipping navigation bars, margins, and layout axes.

🌍 Supported Primary Languages