# AI Translation

## Objective

Translate app content while preserving structure, placeholders, and product terminology.

A translation pipeline over the app's translatable content that keeps source and target linked, protects non-translatable tokens, and routes uncertain output to review.

## 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. Identify what is genuinely translatable and separate it from what is not. Extract placeholders, markup, URLs, identifiers, code, and proper names into protected tokens before generation and restore them afterwards.
2. Store every translation with a reference to the exact source version it came from. When the source changes, mark the translation stale and queue it for retranslation rather than leaving a silently outdated string in place.
3. Hold a per-language glossary of product terms and their approved renderings, and apply it to every request. A term that translates three ways across the app is worse than leaving it in the source language.
4. Run translation through the app's existing background-job system in batches, with a token ceiling per batch and backoff on provider errors. Do not translate on page render or on a user's request path.
5. Require review before a translation becomes visible to end users, and let a reviewer approve, edit, or reject per string. Machine output published unreviewed will be found by a customer before it is found by the team.

## 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

- Placeholders, markup, URLs, and code fragments come back reordered, translated, or dropped. Verify every protected token is present and unaltered after generation, and reject the string when one is missing rather than shipping a broken interpolation.
- Glossary terms must be enforced after generation as well as requested before it, because a model will happily ignore a term list mid-sentence.
- Word-for-word output loses register. Formality, address form, and politeness level must be specified per language, since the correct choice differs by locale and cannot be inferred from the English source.
- Ambiguous source text — a bare noun that is also a verb, a string with no context, a fragment reused in several places — must be flagged for a human rather than resolved by guessing. Give translators the source context and where the string appears.
- Source and target must stay linked in both directions, so an edit to the source can find every affected translation and a reviewer can always see what a translation was made from.
- Text expansion breaks layouts. Translated strings will run longer than the source in several languages, and the review surface should show where a string is used so the reviewer can catch overflow.
- Right-to-left languages need direction and alignment handled at the layout level; a correct translation rendered in the wrong direction is still broken.
- A refusal, a timeout, or truncated output must leave the previous approved translation in place and mark the string as failed, never fall back to showing the untranslated source where a translation already existed.

## 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

- [ ] Placeholders, markup, URLs, and code are protected before generation and verified intact after it.
- [ ] Each translation records the source version it derives from and is marked stale when the source changes.
- [ ] A per-language glossary is applied and enforced on the output.
- [ ] Translation runs in background batches with token ceilings and backoff, never on a request path.
- [ ] No translation reaches end users without a reviewer approving it.
- [ ] Ambiguous source strings are flagged with their usage context for human resolution.
- [ ] A failed translation leaves the last approved version visible.
- [ ] 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.