Implement CyberSim Phase 2.5: Localization, Branding, and Immersive Login

docs/scenario-format.md

@@ -53,6 +53,8 @@ For large scenarios, sub-collections can optionally be split across multiple fil
 | `mode` | `string` | **Yes** | Instruction mode: `"guided"`, `"practice"`, or `"assessment"`. |
 | `entryEvent` | `string` | **Yes** | ID of the event executed at scenario start. |
 | `passingScore` | `number` | **Yes** | Minimum score required to pass and earn a certificate (0–100). |
+| `supportedLocales` | `array` | No | List of supported language codes (e.g. `["en", "es"]`). |
+| `login` | `object` | No | Network login metadata: `{ networkName, networkDescription, networkIcon }`. |
 | `engine` | `object` | No | Minimum engine version requirements (`{ "minimumVersion": "0.2.0" }`). |
 | `learner` | `object` | No | Initial persona: `{ name, role, email, department }`. |
 | `organizations` | `array` | No | List of simulated organizations & trusted domain lists. |
@@ -281,3 +283,61 @@ The diagnostics overlay provides:
 - Event trigger states and scheduled timers
 - Current category score breakdowns and recorded findings
 - Scenario SHA-256 fingerprint calculations
+
+---
+
+## 9. Scenario Localization & Personalization
+
+### 9.1 Declaring Supported Locales & Login Presentation
+
+Scenarios declare their supported language codes in `scenario.json`:
+
+```json
+{
+  "formatVersion": "1.0",
+  "id": "my-scenario",
+  "supportedLocales": ["en", "es"],
+  "login": {
+    "networkName": "ACME Corporate Network",
+    "networkDescription": "Simulated Corporate Workplace",
+    "networkIcon": "corporate"
+  }
+}
+```
+
+### 9.2 Providing Scenario Translations (`locales/<lang>.json`)
+
+Translations for scenario-specific content are stored within the scenario package under `locales/`:
+
+```
+scenarios/my-scenario/
+├── scenario.json
+└── locales/
+    ├── en.json
+    └── es.json
+```
+
+The translation catalog can override text properties across messages, pages, files, notifications, alerts, findings, and feedback:
+
+```json
+{
+  "title": "Turno Operativo y Concientización",
+  "messages": {
+    "email_welcome": {
+      "sender": "Morgan Chen (Vicepresidente)",
+      "subject": "Bienvenido al equipo",
+      "body": "Hola {{learner.firstName}},\n\n¡Bienvenido!"
+    }
+  }
+}
+```
+
+### 9.3 Learner Personalization Variables
+
+The following template variables are available for dynamic interpolation across messages, documents, web pages, notifications, and feedback:
+
+- `{{learner.firstName}}`: Learner's validated first name entered at login (HTML-escaped).
+- `{{learner.name}}`: Learner's full name.
+- `{{learner.email}}`: Learner's assigned workplace email address.
+- `{{learner.role}}`: Learner's assigned workplace job title.
+- `{{company.name}}`: Primary enterprise organization name.