# Spanish Translation Coverage

Code-owned translation expectations now live in `src/lib/translation-rules.ts`. Keep this document aligned with that registry when adding a new user-visible content surface.

## Primary Product Goal

For the first customer tenants, most line managers are expected to be native Spanish speakers. A Spanish-speaking line manager should be able to complete their normal workflow in Spanish without needing to understand English.

That means the highest-priority path is:

1. Spanish line manager signs in.
2. Spanish line manager submits a ticket.
3. Clarification questions, if any, are in Spanish.
4. Notifications and ticket status screens are in Spanish.
5. Expert response received by the line manager is in Spanish.

Expert/admin bilingual workflows matter too, but gaps there are less severe than gaps in the line-manager path.

## Current Coverage Matrix

| Area | Spanish line manager experience | Spanish expert/admin experience | Current behavior | Gap / future work |
| --- | --- | --- | --- | --- |
| App navigation and static UI | Covered | Covered | Typed English/Spanish dictionaries drive signed-in UI, forms, labels, statuses, and buttons. | Continue moving any newly added strings into dictionaries. |
| Onboarding and profile language setting | Covered | Covered | Users can choose English or Spanish during onboarding/profile. Dedicated e2e coverage verifies Spanish selection during onboarding. | None known. |
| Admin invite language | Covered for invite recipient | Covered for admin sender UI | Admin/expert chooses invitee language; invite email uses selected language. | None known. |
| Magic link email | Covered after user row exists | Covered after user row exists | Magic links use saved user preferred language when known. | Unknown users fall back to English. |
| Ticket submit form | Covered | Not primary | Labels, validation copy, option labels, and post-submit states are localized. Full Spanish ticket-submission e2e coverage is in place. | Custom tenant-authored option values still fall back to source text unless added to the bilingual label map or translated into stored variants. |
| User-authored ticket description | Covered when authored in Spanish | Displayed in viewer language only when translation row exists | Original text is preserved with language metadata. Spanish-authored messages naturally remain Spanish. | English-authored messages need generated/backfilled `ticket_message_translations` for Spanish expert display. |
| Ticket title | Covered when source/generated title is Spanish or translation exists | Covered when translation exists | `ticket_translations` stores Spanish title variants for display. Seeded demo tickets now get Spanish title translations. Tenant-scoped backfill can generate missing Spanish variants. | New live ticket title translation still depends on ingestion creating the title in the submitter language or on a later backfill/translation job. |
| Ticket structured fields: department, category, affected system, success criteria, action requested | Covered for known configured values and translation rows | Covered for known configured values and translation rows | Static labels are localized. Known option values are displayed with English/Spanish labels while stable stored values remain unchanged. `ticket_translations` can localize free-text ticket fields. Seeded demo tickets now get Spanish variants. | Custom tenant-authored option values need entries in `src/lib/config-option-labels.ts` or generated stored translations. |
| Ticket list / inbox display | Covered when translations exist | Covered when translations exist | Ticket list, expert inbox, and detail page select ticket/message translations when approved and fresh. | Missing translations fall back to source text. |
| Clarification questions | Covered | Not primary | Completeness agent uses submitter language and stores artifact language. | Legacy English artifacts need backfill if they should display in Spanish. |
| Clarification answers | Covered when Spanish line manager answers in Spanish | Translation only when row exists | Answers are user-authored and preserved. | English answers need generated/backfilled message translations for Spanish expert display. |
| AI summary | Not usually shown to line manager | Covered when generated in Spanish or translation exists | Summary artifacts carry language; display uses approved artifact translations when present. | Summarization currently needs a stronger target-language rule for Spanish experts on English tickets. |
| Response draft for expert | Not shown to line manager | Covered for expert preferred language | Response draft agent uses expert preferred language. | None known for new drafts. |
| Expert final response | Covered when submitter language differs and expert reviews translation | Covered in expert-authored language | Cross-language response preview stores reviewed submitter-language translation and notification email uses it. The client now exposes review whenever expert and submitter languages differ, including Spanish expert to English submitter. | If translation was not generated/reviewed, body can still fall back to expert source language. |
| Response notification email | Covered | Not primary | Notification email uses submitter preferred language and reviewed translated response body when provided. | If translation was not generated/reviewed, body can fall back to expert source language. |
| Knowledge base list/detail | Usually not line-manager-facing | Covered | KB entries display viewer-language translations when available. Expert review surfaces can show pending translations. | Missing translations fall back to canonical source. |
| KB search | Usually not line-manager-facing | Covered when translation exists | Search results localize title/snippet where translations exist. | Spanish query retrieval still primarily uses canonical embeddings; per-language embeddings may be future work. |
| Seed/demo data | Covered after rerun seed or backfill | Covered after rerun seed or backfill | Demo KB, ticket messages, ticket titles/fields, and AI artifacts now have Spanish seed translations. A tenant-scoped backfill script can fill missing Spanish KB, ticket, message, and artifact translations. | Existing environments need the seed or a dry-run/backfill for selected tenants. |

## Spanish Line Manager Gap List

These are the gaps most likely to affect the primary customer use case:

1. Custom tenant-config option values can still be English if they are not in the bilingual label map and do not have stored translation rows.
2. Expert response body depends on the expert using/reviewing the cross-language translation flow.
3. Legacy or manually inserted English ticket content needs translation rows to display in Spanish.
4. New live English-authored tickets need either immediate translation generation during ingestion or a scheduled/manual tenant backfill before Spanish users see translated ticket content.

## Implemented From Recommended Next Changes

1. Added bilingual display labels for known tenant config option values.
   - Keep stable internal values.
   - Departments, categories, affected systems, action requested options, severity, and concern types render in the signed-in user's language when the value is known.
   - Custom values intentionally fall back to the source string until a bilingual label or stored translation is provided.

2. Added tenant-scoped translation backfill support.
   - Command: `TENANT_SLUG=<slug> pnpm db:backfill-translations`.
   - Defaults to dry-run.
   - Requires `CONFIRM_PRODUCTION_TENANT_SLUG=<slug>` when `DRY_RUN=false`.
   - Reports KB, ticket display, ticket message, and AI artifact translation counts.
   - Stores generated results in `knowledge_entry_translations`, `ticket_translations`, `ticket_message_translations`, and `ai_artifact_translations`.
   - Does not translate on page load.

3. Tightened cross-language response UI.
   - Show translation review whenever expert language differs from submitter language.
   - E2e coverage now checks both English expert -> Spanish submitter and Spanish expert -> English submitter.

4. Added Spanish line-manager e2e coverage.
   - Onboarding language selection.
   - Submit a ticket in Spanish.
   - See Spanish post-submit state.
   - Existing response-translation coverage verifies cross-language expert response review for Spanish submitters.

## Remaining Recommended Changes

1. Add automatic post-ingestion translation generation for new English-authored tickets when Spanish users need to view them.
   - A background job should generate `ticket_translations` and `ticket_message_translations`.
   - This should reuse the same source hashes as display/backfill so stale translations are detectable.

2. Decide how to model fully bilingual tenant-authored config going forward.
   - Current support is a code-level known-value label map.
   - If tenants can customize option labels frequently, move these labels into tenant config or a database-backed option table with stable value keys and per-language display labels.

3. Add direct line-manager e2e coverage for viewing a completed Spanish expert response.
   - Existing tests verify response translation preview visibility.
   - A deeper test should submit or seed a responded ticket and assert that the Spanish line manager sees the translated response body.