Frontend

Internationalization (i18n)

Relevant source files

The following files were used as context for generating this wiki page:

The Primebrick frontend implements a robust internationalization (i18n) system designed to support multiple locales with high-performance reactive translations and standardized date/time formatting. The system is built around a centralized dictionary map and a Svelte derived store for real-time language switching.

System Overview

The i18n architecture separates locale definitions, message bundles, and formatting logic. It supports six primary locales and handles regional variations (e.g., British vs. American English) through aliasing.

Core Components

Dictionary Map (DICTS): A central registry in src/lib/i18n/index.ts:14-23 that maps UiLang tags to their respective JSON message bundles.
Reactive t() Function: A derived Svelte store that provides a translation function. It supports dot-notation keys (e.g., shell.nav.modulesGroup) and variable interpolation using {variable} syntax src/lib/i18n/index.ts:43-50.
Locale Normalization: Logic to resolve browser preferences (navigator.languages) or stored settings into supported application locales src/lib/i18n/languages.ts:30-38.

Translation Flow: Natural Language to Code

The following diagram illustrates how a requested translation key in the UI is resolved to a specific string in a message bundle based on the active locale.

"Translation Resolution Pipeline"

Code
graph TD
    subgraph "Natural Language Space"
        User["User Preference (e.g. 'it-IT')"]
        Browser["navigator.languages"]
    end

    subgraph "Code Entity Space"
        Store["uiLang (Svelte Store)"]
        Dict["DICTS (Record&lt;UiLang, Dict&gt;)"]
        TFunc["t() (Derived Store)"]
        enGB["en-GB.json (Fallback)"]
        itIT["it-IT.json"]
    end

    User --> Store
    Browser -->|normalizeLang| Store
    Store --> TFunc
    Dict -->|Selects| itIT
    TFunc -->|Key Lookup| Dict
    TFunc -->|Fallback if missing| enGB
    TFunc -->|Result| UI["UI Component (e.g. LangSelect.svelte)"]

Sources: src/lib/i18n/index.ts:14-50, src/lib/i18n/store.svelte:1-10, src/lib/i18n/languages.ts:30-38

Supported Locales

The system currently supports the following locales, defined in src/lib/i18n/languages.ts:5-5:

Locale Tag	Language	Region	Message Source
`en-GB`	English	United Kingdom	`en-GB.json`
`en-US`	English	United States	`en-GB.json` (Alias)
`it-IT`	Italiano	Italy	`it-IT.json`
`fr-FR`	Français	France	`fr-FR.json`
`es-ES`	Español	Spain	`es-ES.json`
`de-DE`	Deutsch	Germany	`de-DE.json`
`pt-PT`	Português	Portugal	`pt-PT.json`

Note: en-US uses the en-GB strings but triggers US-specific formatting for dates and numbers via the Intl API src/lib/i18n/index.ts:16-17.

UI Integration

The LangSelect.svelte component provides the user interface for switching languages. It utilizes the orderLangEntriesByBrowser utility to prioritize languages matching the user's browser settings at the top of the dropdown list src/lib/components/LangSelect.svelte:24-27.

"Language Switcher Components"

Code
graph LR
    subgraph "UI Space"
        LS["LangSelect.svelte"]
        Trigger["DropdownMenu.Trigger"]
        Items["DropdownMenu.Item"]
    end

    subgraph "Logic Space"
        setUiLang["setUiLang(lang)"]
        order["orderLangEntriesByBrowser"]
        suffix["uiLangTopBarTwoLetterSuffix"]
    end

    LS --> order
    Trigger -->|Display| suffix
    Items -->|onSelect| setUiLang

Sources: src/lib/components/LangSelect.svelte:53-63, src/lib/i18n/languages.ts:88-92

Detailed Documentation

For specific implementation details, refer to the child pages:

Translation System & Locale Configuration

Covers the technical implementation of the uiLang store, the t() translation function, interpolation logic, and the language selection utilities found in src/lib/i18n/index.ts and src/lib/i18n/languages.ts.

Message Bundle Structure & Namespaces

Explains the hierarchy of the JSON message files, including namespaces like app, common, shell, and entities. Documents the interpolation syntax and specific requirements for adding new translations.

Date & Time Formatting

The system exports several utilities from date-format for consistent temporal display across the application:

formatUiDate: Standard date display.
formatUiDateTime: Date and time display.
formatUiDateTimeInTimeZone: Handles IANA timezone keys for global users.
uiLocaleTag: Provides the active BCP 47 tag for native Intl browser APIs.

Sources: src/lib/i18n/index.ts:52-58

Last modified on July 13, 2026

Glossary Message Bundle Structure & Namespaces