Frontend

Message Bundle Structure & Namespaces

Relevant source files

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

This page details the organization, syntax, and hierarchical structure of the internationalization (i18n) message bundles in the Primebrick Frontend. The system utilizes a multi-file JSON structure to support six primary locales, employing a nested namespace strategy to ensure maintainability and prevent key collisions.

Locale Support & Files

The application supports six distinct locales. Each locale is defined in a standalone JSON file located within the src/lib/i18n/messages/ directory.

Locale	File Path	Primary Region
English	`src/lib/i18n/messages/en-GB.json`	United Kingdom
German	`src/lib/i18n/messages/de-DE.json`	Germany
Italian	`src/lib/i18n/messages/it-IT.json`	Italy
Portuguese	`src/lib/i18n/messages/pt-PT.json`	Portugal
Spanish	`src/lib/i18n/messages/es-ES.json`	Spain
French	`src/lib/i18n/messages/fr-FR.json`	France

Namespace Hierarchy

The message bundles are organized into functional namespaces. This hierarchy allows the t() function to resolve keys using dot notation (e.g., $t('login.username')).

1. `app` & `login`

Basic application metadata and the authentication interface.

app: Contains the global application title src/lib/i18n/messages/en-GB.json:2-4.
login: Handles credentials labels, placeholders, and the "Hero" section quotes used in the login screen carousel src/lib/i18n/messages/en-GB.json:5-28.

2. `common` & `validation`

Shared UI strings and form error messages.

common: Reusable labels for buttons (Save, Cancel, Delete), loading states, and generic dialog titles src/lib/i18n/messages/en-GB.json:29-84.
validation: Error strings for Zod schema validation, such as required, tooShort, and invalidUrl src/lib/i18n/messages/en-GB.json:85-93.

3. `shell`

Navigation and global layout components.

nav: Labels for the sidebar groups and items src/lib/i18n/messages/en-GB.json:99-110.
commandPalette: Search and command interface labels src/lib/i18n/messages/en-GB.json:115-128.
userMenu: Dropdown options for profile, billing, and sign-out src/lib/i18n/messages/en-GB.json:132-144.

4. `settings`

The comprehensive settings module, divided into sub-sections.

profile: User identity fields (Email, Display Name) and IDP (Identity Provider) metadata src/lib/i18n/messages/en-GB.json:167-191.
audit: Standard metadata labels for entity lifecycle (Created At, Updated By) src/lib/i18n/messages/en-GB.json:192-201.
organizations / users / security: Entity-specific settings management src/lib/i18n/messages/en-GB.json:202-206.

5. `entities`

Labels specific to data domains, such as customer or crm. This namespace is used by the EntityListTable to render localized column headers.

Sources: src/lib/i18n/messages/en-GB.json:1-206

Variable Interpolation Syntax

The system supports dynamic content within translations using curly braces {variable}. These placeholders are replaced at runtime by the interpolate function within the i18n engine.

Example: Account Lockout

Key: login.accountLocked
Value: "Account temporarily locked. Please try again in {minutes} minutes." src/lib/i18n/messages/en-GB.json:16-16
Usage: $t('login.accountLocked', { minutes: 5 })

Example: Validation Limits

Key: validation.tooLong
Value: "Must be at most {max} characters" src/lib/i18n/messages/en-GB.json:89-89

Sources: src/lib/i18n/messages/en-GB.json:16-89

Audit & Version History Strings

The versionHistory system relies on specific semantic keys to describe changes in the audit log. These are primarily located under common and settings.audit.

Audit Action Mapping

The audit log displays actions performed on entities. The UI maps backend action codes to localized strings:

Delete: common.delete src/lib/i18n/messages/en-GB.json:59-59
Restore: common.restore src/lib/i18n/messages/en-GB.json:63-63
Duplicate: common.duplicate src/lib/i18n/messages/en-GB.json:67-67

Timezone Keys

The system uses IANA timezone keys for display in the AppTopbar. While the keys themselves (e.g., Europe/Rome) are standard, the labels for "Time" and "Date" are localized under common.time and common.date src/lib/i18n/messages/en-GB.json:52-53.

Sources: src/lib/i18n/messages/en-GB.json:52-72

Data Flow: Message Resolution

The following diagram illustrates how a key is resolved from a component through the i18n store to the JSON message bundle.

Translation Resolution Pipeline

Code
graph TD
    subgraph "Natural Language Space"
        A["UI Component Label: 'Username'"]
    end

    subgraph "Code Entity Space"
        B["$t('login.username')"]
        C["i18n/index.ts: getPath()"]
        D["i18n/messages/en-GB.json"]
        E["i18n/index.ts: interpolate()"]
    end

    A -->|Refers to| B
    B -->|Calls| C
    C -->|Looks up key in| D
    D -->|Returns string template| E
    E -->|Injects variables| B

Sources: src/lib/i18n/messages/en-GB.json:8-8, docs/ai/i18n.md:12-23

AI Agent Compliance Rules

To maintain the integrity of the i18n system, specific rules are enforced for automated agents (Devin/AI):

Immediate Translation: Labels must never be hardcoded in Svelte components. When a label is added, it must be added to all six JSON files simultaneously docs/ai/i18n.md:3-5.
Namespace Prefixing: To avoid conflicts, keys should be prefixed with the component or module name (e.g., eventToast.title) docs/ai/i18n.md:9-9.
Path Consistency: The src/lib/i18n/ directory is the single source of truth for all dictionary data docs/ai/i18n.md:7-7.

Namespace Organization Logic

Code
graph LR
    subgraph "JSON Bundle: en-GB.json"
        ROOT["Root Object"]
        APP["app"]
        LOG["login"]
        COM["common"]
        SHE["shell"]
        SET["settings"]
    end

    ROOT --> APP
    ROOT --> LOG
    ROOT --> COM
    ROOT --> SHE
    ROOT --> SET

    SHE --> NAV["nav"]
    SHE --> CP["commandPalette"]
    SET --> PROF["profile"]
    SET --> AUD["audit"]

Sources: src/lib/i18n/messages/en-GB.json:1-206, docs/ai/i18n.md:1-24

Last modified on July 13, 2026

Internationalization (i18n)Modules & Templates Management

Frontend

Message Bundle Structure & Namespaces

Relevant source files

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

Locale Support & Files

The application supports six distinct locales. Each locale is defined in a standalone JSON file located within the src/lib/i18n/messages/ directory.

Locale	File Path	Primary Region
English	`src/lib/i18n/messages/en-GB.json`	United Kingdom
German	`src/lib/i18n/messages/de-DE.json`	Germany
Italian	`src/lib/i18n/messages/it-IT.json`	Italy
Portuguese	`src/lib/i18n/messages/pt-PT.json`	Portugal
Spanish	`src/lib/i18n/messages/es-ES.json`	Spain
French	`src/lib/i18n/messages/fr-FR.json`	France

Namespace Hierarchy

The message bundles are organized into functional namespaces. This hierarchy allows the t() function to resolve keys using dot notation (e.g., $t('login.username')).

1. `app` & `login`

Basic application metadata and the authentication interface.

app: Contains the global application title src/lib/i18n/messages/en-GB.json:2-4.
login: Handles credentials labels, placeholders, and the "Hero" section quotes used in the login screen carousel src/lib/i18n/messages/en-GB.json:5-28.

2. `common` & `validation`

Shared UI strings and form error messages.

common: Reusable labels for buttons (Save, Cancel, Delete), loading states, and generic dialog titles src/lib/i18n/messages/en-GB.json:29-84.
validation: Error strings for Zod schema validation, such as required, tooShort, and invalidUrl src/lib/i18n/messages/en-GB.json:85-93.

3. `shell`

Navigation and global layout components.

nav: Labels for the sidebar groups and items src/lib/i18n/messages/en-GB.json:99-110.
commandPalette: Search and command interface labels src/lib/i18n/messages/en-GB.json:115-128.
userMenu: Dropdown options for profile, billing, and sign-out src/lib/i18n/messages/en-GB.json:132-144.

4. `settings`

The comprehensive settings module, divided into sub-sections.

profile: User identity fields (Email, Display Name) and IDP (Identity Provider) metadata src/lib/i18n/messages/en-GB.json:167-191.
audit: Standard metadata labels for entity lifecycle (Created At, Updated By) src/lib/i18n/messages/en-GB.json:192-201.
organizations / users / security: Entity-specific settings management src/lib/i18n/messages/en-GB.json:202-206.

5. `entities`

Labels specific to data domains, such as customer or crm. This namespace is used by the EntityListTable to render localized column headers.

Sources: src/lib/i18n/messages/en-GB.json:1-206

Variable Interpolation Syntax

The system supports dynamic content within translations using curly braces {variable}. These placeholders are replaced at runtime by the interpolate function within the i18n engine.

Example: Account Lockout

Key: login.accountLocked
Value: "Account temporarily locked. Please try again in {minutes} minutes." src/lib/i18n/messages/en-GB.json:16-16
Usage: $t('login.accountLocked', { minutes: 5 })

Example: Validation Limits

Key: validation.tooLong
Value: "Must be at most {max} characters" src/lib/i18n/messages/en-GB.json:89-89

Sources: src/lib/i18n/messages/en-GB.json:16-89

Audit & Version History Strings

The versionHistory system relies on specific semantic keys to describe changes in the audit log. These are primarily located under common and settings.audit.

Audit Action Mapping

The audit log displays actions performed on entities. The UI maps backend action codes to localized strings:

Delete: common.delete src/lib/i18n/messages/en-GB.json:59-59
Restore: common.restore src/lib/i18n/messages/en-GB.json:63-63
Duplicate: common.duplicate src/lib/i18n/messages/en-GB.json:67-67

Timezone Keys

Sources: src/lib/i18n/messages/en-GB.json:52-72

Data Flow: Message Resolution

The following diagram illustrates how a key is resolved from a component through the i18n store to the JSON message bundle.

Translation Resolution Pipeline

Code
graph TD
    subgraph "Natural Language Space"
        A["UI Component Label: 'Username'"]
    end

    subgraph "Code Entity Space"
        B["$t('login.username')"]
        C["i18n/index.ts: getPath()"]
        D["i18n/messages/en-GB.json"]
        E["i18n/index.ts: interpolate()"]
    end

    A -->|Refers to| B
    B -->|Calls| C
    C -->|Looks up key in| D
    D -->|Returns string template| E
    E -->|Injects variables| B

Sources: src/lib/i18n/messages/en-GB.json:8-8, docs/ai/i18n.md:12-23

AI Agent Compliance Rules

To maintain the integrity of the i18n system, specific rules are enforced for automated agents (Devin/AI):

Immediate Translation: Labels must never be hardcoded in Svelte components. When a label is added, it must be added to all six JSON files simultaneously docs/ai/i18n.md:3-5.
Namespace Prefixing: To avoid conflicts, keys should be prefixed with the component or module name (e.g., eventToast.title) docs/ai/i18n.md:9-9.
Path Consistency: The src/lib/i18n/ directory is the single source of truth for all dictionary data docs/ai/i18n.md:7-7.

Namespace Organization Logic

Code
graph LR
    subgraph "JSON Bundle: en-GB.json"
        ROOT["Root Object"]
        APP["app"]
        LOG["login"]
        COM["common"]
        SHE["shell"]
        SET["settings"]
    end

    ROOT --> APP
    ROOT --> LOG
    ROOT --> COM
    ROOT --> SHE
    ROOT --> SET

    SHE --> NAV["nav"]
    SHE --> CP["commandPalette"]
    SET --> PROF["profile"]
    SET --> AUD["audit"]

Sources: src/lib/i18n/messages/en-GB.json:1-206, docs/ai/i18n.md:1-24

Last modified on July 13, 2026

Internationalization (i18n)Modules & Templates Management

Message Bundle Structure & Namespaces

Locale Support & Files

Namespace Hierarchy

1. app & login

2. common & validation

3. shell

4. settings

5. entities

Variable Interpolation Syntax

Audit & Version History Strings

Audit Action Mapping

Timezone Keys

Data Flow: Message Resolution

Translation Resolution Pipeline

AI Agent Compliance Rules

Namespace Organization Logic

Message Bundle Structure & Namespaces

Locale Support & Files

Namespace Hierarchy

1. app & login

2. common & validation

3. shell

4. settings

5. entities

Variable Interpolation Syntax

Audit & Version History Strings

Audit Action Mapping

Timezone Keys

Data Flow: Message Resolution

Translation Resolution Pipeline

AI Agent Compliance Rules

Namespace Organization Logic

1. `app` & `login`

2. `common` & `validation`

3. `shell`

4. `settings`

5. `entities`

1. `app` & `login`

2. `common` & `validation`

3. `shell`

4. `settings`

5. `entities`