# Translated Subtitles

## Objective

Let viewers pick their own language for a video's captions.

Additional caption tracks in other languages, generated from the source track and selectable in the player.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Translate cue by cue from the corrected source caption track, not from the raw audio, so timing and sentence boundaries are already settled before translation begins.
2. Reuse the app's existing AI Translation path and its language list rather than introducing a second translation configuration. This feature adds tracks and player selection, not a new translation engine.
3. Offer only the languages the audience actually uses. Generating twenty tracks per video costs real money and buries the two that matter in a long player menu.
4. Default the player's caption selection to the viewer's own language preference where a track exists, using the app's existing Locale and Language Switcher setting rather than guessing from the browser alone.
5. Do not present machine translations as authoritative. Label them, and allow a human-reviewed track to replace one without regenerating the rest.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Translated text is routinely longer than the source. Keep the original cue timings but split overlong cues across the available window rather than letting text overflow the screen or get truncated.
- When a viewer requests a language with no track, fall back to the source language with a visible note rather than showing an empty caption area or silently turning captions off.
- Right-to-left languages need correct text direction, alignment, and punctuation placement in the caption renderer. Left-aligned mirrored text is worse than no track.
- Editing the source track must invalidate the translations derived from it, so a corrected name in the original does not persist as the wrong name in five other languages.
- Cache translations per cue and re-translate only the cues whose source text changed. Re-running the whole track on every edit is slow and expensive for no benefit.
- Proper nouns, product names, and code identifiers should be protected from translation, or the captions will helpfully translate the name of the app.
- Track language codes must include region where it matters, so two variants of the same language do not collide in the player menu.
- Generation runs as a background job with progress, and a failure on one language must not block the others.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Viewers can select from the available caption languages in the player.
- [ ] Cue timings are preserved and overlong translations are split rather than clipped.
- [ ] A missing requested language falls back to the source track with a visible notice.
- [ ] Right-to-left languages render with correct direction and alignment.
- [ ] Editing the source track invalidates the derived translations.
- [ ] Regeneration re-translates only the cues whose source changed.
- [ ] Machine-translated tracks are labelled and can be superseded by a reviewed version.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.