# Internationalization (i18n)

# Internationalization (i18n)

<details>
<summary>Relevant source files</summary>

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

- [src/lib/components/AppPageBreadcrumb.svelte](src/lib/components/AppPageBreadcrumb.svelte)
- [src/lib/components/LangSelect.svelte](src/lib/components/LangSelect.svelte)
- [src/lib/components/ui/dropdown-menu/index.ts](src/lib/components/ui/dropdown-menu/index.ts)
- [src/lib/i18n/index.ts](src/lib/i18n/index.ts)
- [src/lib/i18n/languages.ts](src/lib/i18n/languages.ts)
- [src/lib/i18n/messages/de-DE.json](src/lib/i18n/messages/de-DE.json)
- [src/lib/i18n/messages/en-GB.json](src/lib/i18n/messages/en-GB.json)
- [src/lib/i18n/messages/es-ES.json](src/lib/i18n/messages/es-ES.json)
- [src/lib/i18n/messages/fr-FR.json](src/lib/i18n/messages/fr-FR.json)
- [src/lib/i18n/messages/it-IT.json](src/lib/i18n/messages/it-IT.json)
- [src/lib/i18n/messages/pt-PT.json](src/lib/i18n/messages/pt-PT.json)

</details>



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"
```mermaid
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"
```mermaid
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](#7.1)
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](#7.2)
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]()

---