# Linguist Guide

> **You are a Linguist.** Your job is to review, correct, and approve VTT caption and audio description files for the language(s) you are assigned to. You do not upload videos or manage other users. After you approve content, a Reviewer performs a second-pass check before the job moves to Final Review.

---

## Your Sidebar

| Item | What it does |
|------|-------------|
| 🏠 Dashboard | Your home screen — quality control hero cards and KPI tiles |
| 📋 All Jobs | Full list of all jobs in your organisation |
| 📝 My QC Queue | Your personal list of assigned QC tasks (with badge count) |
| 🔍 QC Review | Organisation-wide QC queue |
| ✅ Final Review | Final review queue (read access) |
| 📖 Help | This guide |

After login, you are automatically redirected to **My QC Queue** — your main working area.

---

## 1. Your Dashboard

![Linguist dashboard](/help-screenshots/linguist/01-dashboard.png)

The dashboard shows:
- **Quality Control** hero card (blue) — shows the number of jobs currently in QC. **Left-click** it or the **Go to QC Review** button to open the QC Review queue.
- **Final Approval** hero card (purple) — shows jobs awaiting final review. **Left-click** it to view the Final Review queue.
- **KPI tiles** at the top — Total, Processing, In QC Review, Completed counts.

---

## 2. My QC Queue

This is where you work. It shows only the jobs assigned **to you**.

**Step 1.** In the sidebar, **left-click** **My QC Queue** (📝).

![My QC Queue page](/help-screenshots/linguist/02-qc-queue.png)

### Status tabs

At the top of the queue, **left-click** a tab to filter:

| Tab | Shows |
|-----|-------|
| **All** | Everything |
| **Pending** | Assigned but not yet started |
| **In Progress** | You have started work |
| **Pending Review** | Submitted, awaiting reviewer |
| **In Review** | Reviewer is checking |
| **Approved** | Approved by reviewer |
| **Rejected** | Reviewer requested changes |

### Table columns

Each row shows: Job name · Language code · QC Status · Job Status · Assigned date · Action.

**Left-click** the **Assigned** column header to sort by date ascending or descending. Click again to cycle: default → ascending (↑) → descending (↓).

**Step 2.** **Left-click** **Open →** on any row to open the VTT editor for that job and language.

---

## 3. Opening a Language for Review

When you **left-click** **Open →** from your queue, you are taken to the **QC Detail** page for that job.

![QC Detail page](/help-screenshots/linguist/03-qc-detail.png)

The page shows:
- Job title and source filename at the top.
- **Per-language cards** — one collapsible card per language. Yours is expanded by default.
- Below the language card: the **VTT Editor** for Captions and/or Audio Description.

### Language card status

The language card header shows a coloured status icon and label:
- 🟡 **Pending** — assigned, not started
- 🔵 **In Progress** — you have started
- 🟣 **Pending Review** — submitted, awaiting reviewer
- ✅ **Approved** — approved by reviewer
- 🔴 **Rejected** — reviewer sent changes back

**Left-click** the language card header to expand or collapse it.

### Starting work

**Left-click** the **Start work** button (yellow) on your language card. The status changes to **In Progress** and the VTT editors appear below.

![Start work button highlighted](/help-screenshots/linguist/04-start-work.png)

---

## 4. Using the VTT Editor

The VTT editor is where you correct captions and audio descriptions cue by cue.

![VTT Editor with cues](/help-screenshots/linguist/05-vtt-editor.png)

### Reading a cue

Each cue (caption or description) is a card containing:
- **Cue number** (orange circle) — sequential, e.g. ①, ②
- **Start time** → **End time** (e.g. `00:00:02.000 → 00:00:05.500`)
- **Duration** in milliseconds (grey, to the right)
- **Text content** — the caption or description text
- **CPS badge** (amber) — Characters Per Second — appears if the cue is too fast to read (>20 CPS). A tooltip explains the issue.
- **Validation warnings** (amber text) — overlap or timing issues

### Editing cue text

**Step 1.** **Hover** over the text of a cue — an **Edit text** button (blue) appears on the right.

**Step 2.** **Left-click** **Edit text**. The text becomes an editable textarea (the **CueEditor**).

![Cue in edit mode](/help-screenshots/linguist/06-cue-edit-mode.png)

**Step 3.** Edit the text as needed. The character count and CPS update live.

**Step 4.** **Left-click** **Save** to save the cue, or **left-click** **Cancel** to discard changes.

> **Keyboard shortcut:** Press **Cmd+Enter** (Mac) or **Ctrl+Enter** (Windows) to save. Press **Esc** to cancel.

### Editing timestamps

**Step 1.** **Left-click** the start time field (e.g. `00:00:02.000`). It becomes editable.

**Step 2.** Type the new timestamp in `HH:MM:SS.mmm` format.

**Step 3.** Press **Enter** to confirm, or press **Esc** to revert.

> **Tip:** Timestamps must not overlap with the next cue. A yellow warning appears if there is an overlap.

### Inserting a new cue

Between cues, a **gap row** appears if there is more than 0.5 seconds of blank space. **Left-click** the gap row to insert a new cue at that position.

You can also use the **Insert Before** or **Insert After** icon buttons on any cue (appear when you hover over the cue).

### Deleting a cue

**Left-click** the **Delete** icon button (🗑, red on hover) on the right side of the cue card.

A confirmation modal appears:
- **Left-click** **Confirm delete** to permanently remove the cue.
- **Left-click** **Cancel** to abort.

### Playing a cue

**Hover** over a cue — a **▶** play button appears on the timing row. **Left-click** ▶ to play the video from the start of that cue in the video preview above.

### Validation errors

If the editor detects errors, a red badge appears in the header: **Validation errors: N**. **Left-click** it to expand the full list. Fix each issue before submitting.

Common errors:
- **Overlap** — cue starts before the previous one ends. Adjust timestamps.
- **CPS > 20** — text is too long for the duration. Shorten the text or extend the end time.
- **Empty cue** — a cue has no text. Add text or delete the cue.

---

## 5. Adding a Comment

To leave a note for the Reviewer or PM, **left-click** the **💬 Comments (N)** button on your language card.

A comment text area expands. Type your comment and **left-click** **Send**.

![Comments expanded](/help-screenshots/linguist/07-comments.png)

---

## 6. English-First Gate

Translations are generated from the **approved English master VTT** to ensure every language has the same cues and timings as the English source.

**What this means for you:**
- When a job arrives in QC, **English is processed first**. Target languages are not available until English is approved by a reviewer or admin.
- If you open a job and your language card shows an amber banner, English has not yet been approved.

![QC Detail showing EN-gate amber banner and disabled actions](/help-screenshots/linguist/10-en-first-gate.png)

The amber banner reads: *"Waiting for EN approval — translation will start automatically once the source language is approved."*

While the banner is shown:
- **Start work**, **Submit for review**, and **Assign** are disabled.
- You can still view the video and any pre-existing VTT content, but you cannot edit or submit.

Once an authorised reviewer approves English, the translation is generated automatically. The banner disappears and your language card becomes fully active.

> **No action needed from you.** Simply wait for the notification or check back when English is approved.

---

## 7. Submitting for Review

When you are satisfied with your edits:

**Step 1.** **Left-click** **↑ Submit for review** (blue button) on your language card.

![Submit for review button](/help-screenshots/linguist/08-submit-for-review.png)

The job status changes to **Pending Review** and a Reviewer is notified.

> **Important:** The English (source) language must be **Approved** before you can submit translations of that language. If you see a "Source language must be approved first" error, the Reviewer needs to approve the English content before you can proceed.

---

## 8. Handling Reviewer Feedback

If a Reviewer sends changes back, the language status changes to **Rejected** (or **QC Feedback**) and the job reappears in your queue.

**Step 1.** Open the job from **My QC Queue**.

**Step 2.** Expand your language card. You will see the **Feedback categories** the reviewer selected (e.g. Timing, Mistranslation, Terminology) and any written notes.

![Reviewer feedback displayed](/help-screenshots/linguist/09-reviewer-feedback.png)

**Step 3.** Address all the issues in the VTT editor.

**Step 4.** **Left-click** **↑ Submit for review** again.

---

## 9. Viewing Glossaries

Glossaries contain client-approved brand terms, product names, and preferred translations. Active glossary terms are highlighted in the VTT editor with an **amber underline**.

**Hover** over a highlighted term to see the glossary entry tooltip (correct translation or note).

To view full glossary lists: **left-click** **Clients** in the sidebar (if you have access) → open a client → **left-click** **Glossaries**.

---

## 10. QC Review (Organisation-wide View)

In addition to your personal queue, you can see all jobs in QC across the organisation.

**Left-click** **QC Review** (🔍) in the sidebar. You see a list of all pending QC jobs.

**Left-click** any job row to open it in the QC Detail editor.

---

## 11. Timeline Preview & Rendering

After editing cues or adjusting the AD script, the **Timeline Preview** bar shows the structure of the accessible video so you can verify the layout before triggering a render.

### Reading the Timeline bar

The bar spans the full video duration (left = 0:00, right = end). Colours indicate:

| Colour | Meaning |
|--------|---------|
| Blue | Video segment — no narration |
| Orange | AD Audio segment — narration plays here |
| Light orange | TTS cue queued for regeneration |
| Red line | Pause Point — video pauses to insert narration |
| Red tick | Pause Point that has been manually adjusted |

### Render Accessible Video Changes

The purple panel below the timeline becomes active when there is something to render:

| Message | What triggered it |
|---------|------------------|
| "N TTS cue(s) queued for regeneration" | You queued one or more cues for TTS re-synthesis |
| "Pause points have been adjusted" | You moved or added pause points |
| "Audio Description script was replaced" | A new AD VTT file was uploaded |

**Left-click Clear queue** (small link next to the cue count) to discard queued regenerations without rendering.

**Run Whisper pause refinement** checkbox:
- **Tick it** when you changed the *number or position* of AD cues — Whisper re-aligns pause points to speech boundaries.
- **Leave unchecked** when you only shifted pause timing manually.

**Step 1.** Check the Timeline bar — orange (AD Audio) segments should cover the right parts of the video.

**Step 2.** When changes are pending, the **Render Changes** button turns purple and becomes clickable. **Left-click** it.

**Step 3.** A **Rendering…** spinner appears. The page updates automatically when the render completes.

> **Note:** Editing cue *text only* does not require a render — text is saved immediately. Only timing changes, queued TTS regenerations, or AD script replacements require rendering.

---

## 12. Mouse Interactions Reference

| Action | Where | What happens |
|--------|-------|--------------|
| **Left-click** **Open →** | My QC Queue row | Opens QC Detail for that language |
| **Left-click** column header (Assigned) | Queue table | Sorts by that column ascending/descending |
| **Left-click** language card header | QC Detail | Expands or collapses the language panel |
| **Left-click** **Start work** | Language card | Marks as In Progress, reveals editor |
| **Left-click** **Edit text** | Cue (on hover) | Opens text edit mode for that cue |
| **Left-click** **Save** | Cue editor | Saves changes to the cue |
| **Left-click** timestamp field | Cue | Makes timestamp editable |
| **Left-click** gap row | Between cues | Inserts a new cue |
| **Left-click** **Insert Before/After** icon | Cue (on hover) | Inserts cue above/below |
| **Left-click** **Delete** icon | Cue (on hover) | Opens delete confirmation modal |
| **Left-click** **Confirm delete** | Delete modal | Permanently deletes the cue |
| **Left-click** ▶ play button | Cue (on hover) | Plays video from that cue start |
| **Left-click** **💬 Comments** | Language card | Expands comment input |
| **Left-click** **Submit for review** | Language card | Submits for Reviewer check |
| **Hover** glossary underline | Cue text | Shows glossary entry tooltip |

---

## 13. Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Cmd/Ctrl + Enter` | Save current cue text edit |
| `Esc` | Cancel cue text edit or revert timestamp |
| `Enter` | Confirm timestamp (in timestamp field) |

---

## 14. Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| "Source language must be approved first" | English content not yet approved | Wait for Reviewer to approve English, then proceed |
| CPS warning (amber badge) | Text too long for cue duration | Shorten the text or extend the end timestamp |
| Overlap warning | Cue starts before previous ends | Adjust start or end timestamp to close the gap |
| "Saving…" stuck | Network interruption | Wait; if not resolved in 30s, refresh and re-edit |
| Empty queue | No jobs assigned to you | Check with Production or your team lead |
