# Translation System - CSV Guide

## What is this?

This guide explains how the translation CSV file works for the "Next Steps" section on candidate results pages. The system uses **translation tokens** to manage multilingual content efficiently.

---

## Understanding the CSV Structure

The translation CSV file has this structure:

| Token | EN | DE | UK | ... |
|-------|----|----|----|----|
| `default.getHelp.title` | Get Help | Hilfe erhalten | Отримати допомогу | ... |
| `default.getHelp.subtitle` | Get free support... | Lassen Sie sich... | Отримайте... | ... |

**Key parts:**
- **Token** (Column 1): The unique identifier for each piece of text
- **EN, DE, UK, etc.** (Remaining columns): Translations for each language

---

## Token Naming Convention

Tokens follow a specific pattern: `{layer}.{step}.{property}`

### Structure Breakdown

```
default.getHelp.title
   ↓       ↓      ↓
 Layer   Step  Property
```

**1. Layer** - Which candidate group this applies to:
- `default` - Base layer for everyone
- `nurse.default` - All nurses
- `assistant.default` - All assistants
- `nurse.allmet` - Specific nurse situation
- `assistant.missinglicense` - Specific assistant situation

**2. Step** - Which of the 6 steps this text belongs to:
- `getHelp` - Get Help step
- `connect` - Connect with Employers step
- `documents` - Prepare Your Documents step
- `submit` - Submit Your Application step
- `compensatory` - Complete a Compensatory Measure step
- `german` - Improve Your German step

**3. Property** - What part of the step this is:
- `title` - The step heading
- `subtitle` - The description text
- `costs` - Cost information text
- `button` - Button text
- `buttonImprove` / `buttonJoin` - Special buttons for connect step

---

## How the Layer System Works

The system uses **3 layers** that override each other, like stacking transparent sheets:

### Layer 1: `default.*` (Base Layer)

This is the foundation. Every step should have complete translations here.

**Example tokens:**
```
default.submit.title
default.submit.subtitle
default.submit.costs
default.submit.button
```

**When to use:** These apply to ALL candidates unless overridden by a more specific layer.

---

### Layer 2: `{role}.default.*` (Role Layer)

Changes text for **all candidates of a specific role** (nurse/assistant/helper).

**Example tokens:**
```
assistant.default.submit.subtitle
assistant.default.submit.costs
```

**What happens:**
- `assistant.default.submit.subtitle` replaces `default.submit.subtitle` for ALL assistants
- But `default.submit.title` still shows (not overridden)
- But `default.submit.button` still shows (not overridden)

---

### Layer 3: `{role}.{situation}.*` (Specific Situation Layer)

Changes text for **one specific candidate situation** only.

**Example tokens:**
```
assistant.missinglicense.submit.subtitle
```

**What happens:**
- `assistant.missinglicense.submit.subtitle` replaces the subtitle for assistants missing their license
- `assistant.default.submit.costs` still applies (from Layer 2)
- `default.submit.title` still applies (from Layer 1)
- `default.submit.button` still applies (from Layer 1)

---

## Real Example: How Tokens Stack

**Scenario:** A "Nursing Assistant without a license" views the "Submit Your Application" step.

**The system looks for tokens in this order:**

1. **Check Layer 3** (most specific):
   - `assistant.missinglicense.submit.title` → Not found ❌
   - `assistant.missinglicense.submit.subtitle` → Found ✅ "First upload your license..."
   - `assistant.missinglicense.submit.costs` → Not found ❌
   - `assistant.missinglicense.submit.button` → Not found ❌

2. **Check Layer 2** (role-specific):
   - `assistant.default.submit.title` → Not found ❌
   - `assistant.default.submit.subtitle` → Not needed (found in Layer 3)
   - `assistant.default.submit.costs` → Found ✅ "Cost: 150-250€"
   - `assistant.default.submit.button` → Not found ❌

3. **Check Layer 1** (default):
   - `default.submit.title` → Found ✅ "Submit Your Application"
   - `default.submit.subtitle` → Not needed (found in Layer 3)
   - `default.submit.costs` → Not needed (found in Layer 2)
   - `default.submit.button` → Found ✅ "Learn how to apply"

**Final Result:**
- Title: "Submit Your Application" ← from `default.submit.title`
- Subtitle: "First upload your license..." ← from `assistant.missinglicense.submit.subtitle`
- Costs: "Cost: 150-250€" ← from `assistant.default.submit.costs`
- Button: "Learn how to apply" ← from `default.submit.button`

---

## Available Steps & Properties

### The 6 Steps

Every next-steps journey can have these steps (use camelCase in tokens):

| Token Name | Display Name |
|------------|--------------|
| `getHelp` | Get Help |
| `connect` | Connect with Employers |
| `documents` | Prepare Your Documents |
| `submit` | Submit Your Application |
| `compensatory` | Complete a Compensatory Measure |
| `german` | Improve Your German |

### Properties for Each Step

| Property | What it is | Example Token |
|----------|-----------|---------------|
| `title` | Step heading | `default.getHelp.title` |
| `subtitle` | Description text | `default.getHelp.subtitle` |
| `costs` | Cost information | `default.getHelp.costs` |
| `button` | Button text | `default.getHelp.button` |
| `buttonImprove` | Special button (connect only) | `default.connect.buttonImprove` |
| `buttonJoin` | Special button (connect only) | `default.connect.buttonJoin` |

---

## Available Layers (All Valid Token Prefixes)

### Global Layer
- `default` - Base for everyone

### Role Layers
- `nurse.default` - Shared by all nurse situations
- `assistant.default` - Shared by all assistant situations
- `helper.default` - Shared by all helper situations

### Specific Situation Layers

**Nurses:**
- `nurse.allmet`
- `nurse.missinglicense`
- `nurse.missinglicenseandaccreditation`

**Assistants:**
- `assistant.allmet`
- `assistant.missinglicense`
- `assistant.missinglicenseandaccreditation`

**Helpers:**
- Only uses `helper.default` (no specific situations)

---

## Dynamic Placeholders

Some translations can include placeholders that get replaced with actual data:

| Placeholder | Replaced with | Example |
|-------------|---------------|---------|
| `{currentLevel}` | Candidate's current German level | A1, B1, B2, etc. |
| `{requiredLevel}` | Required German level | B1, B2, etc. |

**Example translation:**
```
default.german.subtitle = "You're currently at {currentLevel} — almost there! To gain full recognition, you'll need to improve your German to {requiredLevel} level."
```

**Becomes:**
```
"You're currently at A2 — almost there! To gain full recognition, you'll need to improve your German to B2 level."
```

---

## Rules for Adding Translations

### 1. Always Fill Out the `default.*` Layer Completely

The base layer should have ALL properties for ALL steps. This ensures there's always a fallback.

**Required tokens for each step:**
```
default.{stepName}.title
default.{stepName}.subtitle
default.{stepName}.costs
default.{stepName}.button
```

### 2. Only Add Role/Situation Tokens When You Need to Change Something

If assistant costs are different, add:
```
assistant.default.submit.costs
```

Don't add:
```
assistant.default.submit.title  ← Not needed if same as default
assistant.default.submit.button ← Not needed if same as default
```

### 3. Use Consistent Naming

- Steps use camelCase: `getHelp`, `connect`, `documents`
- Properties use camelCase: `title`, `subtitle`, `buttonImprove`
- Layers use lowercase with dots: `assistant.default`, `nurse.allmet`

### 4. Add All Languages for Each Token

Every token row must have translations for all supported languages (EN, DE, UK, TL, TR, BS, SQ, VI, ES, HI, AR).

---

## Common Scenarios

### Scenario 1: Change just the subtitle for all assistants

**Add one token:**
```
assistant.default.submit.subtitle
```

All other properties (title, costs, button) will fall through from `default.*`

---

### Scenario 2: Change subtitle for one specific situation

**Add one token:**
```
nurse.missinglicense.submit.subtitle
```

Everything else comes from `nurse.default.*` (if exists) or `default.*`

---

### Scenario 3: Assistants have different costs and different process

**Add two tokens:**
```
assistant.default.submit.subtitle   ← Changed process description
assistant.default.submit.costs      ← Different price
```

Title and button stay from `default.*`

---

### Scenario 4: One situation needs urgent warning

**Add one token:**
```
assistant.missinglicenseandaccreditation.submit.subtitle
```

This overrides even `assistant.default.submit.subtitle` for this specific situation.

---

## Why This System?

### Without this system:
- 7 candidate situations × 6 steps × 4 properties = **168 translations per language**
- Lots of duplication
- Hard to make global changes

### With this system:
- Base layer: ~24 translations (6 steps × 4 properties)
- Role overrides: ~10 translations (only what's different)
- Situation overrides: ~5 translations (only what's specific)
- **Total: ~39 translations per language** (77% less!)

---

## Quick Reference: Token Format

```
{layer}.{step}.{property}
   ↓       ↓        ↓
(role.   (camel  (camel
 situation) Case)   Case)

Examples:
default.getHelp.title
assistant.default.submit.costs
nurse.missinglicense.documents.subtitle
```

---

## Checking Your Work

To verify a token will work correctly:

1. **Check the layer exists** in the "Available Layers" section above
2. **Check the step name** is one of the 6 available steps (camelCase)
3. **Check the property** is one of: title, subtitle, costs, button, buttonImprove, buttonJoin
4. **Ensure all languages have translations** for that token

**Valid token:** ✅ `assistant.default.submit.costs`
**Invalid token:** ❌ `assistant.submit.costs` (missing `.default` or situation)
**Invalid token:** ❌ `default.Submit.costs` (should be `submit` not `Submit`)
**Invalid token:** ❌ `default.submit.price` (should be `costs` not `price`)