# Message Bundle Structure & Namespaces # Message Bundle Structure & Namespaces
Relevant source files The following files were used as context for generating this wiki page: - [docs/ai/i18n.md](docs/ai/i18n.md) - [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)
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 | Sources: [src/lib/i18n/messages/en-GB.json:1-1]() | [src/lib/i18n/messages/de-DE.json:1-1]() | [src/lib/i18n/messages/it-IT.json:1-1]() | [src/lib/i18n/messages/pt-PT.json:1-1]() | [src/lib/i18n/messages/es-ES.json:1-1]() | [src/lib/i18n/messages/fr-FR.json:1-1]() ## 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 ```mermaid 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): 1. **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](). 2. **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](). 3. **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 ```mermaid 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]() ---