church-translate/docs/PLAN-spanish-variants.md

# Plan — three Spanish variants for live preaching

## The ask
Operator, relaying a native Spanish speaker: the Spanish output is Latin
American, and three variants are wanted — **Latin American, Spain, Mexican** —
"fine tuned exactly to how it's supposed to be". No native speaker will be
provided; research from the web instead. Nothing may be left out.

## Finding 1 — the taxonomy overlaps
es-MX is INSIDE es-419, not beside it. Their differences are lexical only
(*computadora/ordenador*, *carro/coche*, *ícono/icono*). es-ES is the one that
differs GRAMMATICALLY. So the three deliverables are not three equal problems:

| variant | differs from es-419 by | difficulty |
|---|---|---|
| es_419 Latin American | — (this is today's output) | none |
| es_MX Mexican | word choice | low, deterministic |
| es_ES Spain | **the whole 2nd-person-plural system** | high |

Reference editions, so each variant has an authority rather than my preference:
- **es_ES** → Reina-Valera 1960 (uses `vosotros`) / LBLA
- **es_419** → NBLA (explicitly uses `ustedes` for Latin America) / NVI
- **es_MX** → NBLA + Mexican lexicon

## Finding 2 — why es-ES cannot be a find-and-replace
Spanish 3rd-person-plural is IDENTICAL for "ustedes" (you all) and "ellos"
(they). `hablan` is both. So a target-side rule `hablan → habláis` corrupts
every genuine third-person sentence: "they were there" becomes "you all were
there". In scripture. Silently. This is the exact failure class the whole
fidelity effort exists to prevent, so a naive transform is not shippable.

## Finding 3 — the English source resolves the ambiguity
This is the key idea and it may remove the need for any model change.

The ambiguity is unresolvable in the Spanish. It is already resolved in the
ENGLISH, which we still have:

    "Open YOUR Bibles."        -> 2nd person -> ustedes-form -> convert
    "THEY were there."         -> 3rd person -> ellos-form   -> leave alone

So: convert to `vosotros` ONLY when the English sentence contains 2nd-person
address AND contains NO 3rd-person-plural marker. Mixed sentences ("tell them
that you are loved") are left in es-419 form — which a Spaniard understands
perfectly, it just reads Latin American. **Conservative by construction: the
failure mode is "not converted", never "wrongly converted".**

## Design

    NLLB -> guard -> cache -> [es-419 base]
                                 |-- es_MX : lexical layer
                                 |-- es_ES : gated vosotros transform
                                 `-- es_419: as-is

Same shape as `pt-variants.js` (por_Latn / por_PT share one NLLB result), and it
reuses `NLLB_ALIAS` so the extra variants cost no extra inference.

New pseudo-codes `spa_MX` and `spa_ES`, both aliased to `spa_Latn` at the MT
boundary only — exactly how `por_PT` already works.

### es_ES transform components
1. **Gate** (on the English source): 2nd-person markers present, 3rd-person-plural
   markers absent.
2. **Pronouns/possessives**: ustedes→vosotros, su(s)→vuestro(s)/vuestra(s),
   les→os, se (reflexive 2pl)→os, a ustedes→a vosotros.
3. **Verb morphology**: 3pl→2pl. `-an→-áis`; `-en→-éis` for -er verbs but
   `-en→-ís` for -ir verbs, so the verb's class must be known — a table, not a
   rule. Irregulars (ser, ir, tener, hacer, poder, querer, decir, venir, saber,
   dar, ver, poner, salir, traer, oír, haber) need explicit entries.
4. **Imperatives**: `abran→abrid`, `vengan→venid`, `miren→mirad` — highest
   frequency in preaching and the most audible difference.

### es_MX layer
Lexical only. Word-level, no morphology, no gate needed.

## What must not regress
- Latency: no extra inference. All layers are string work over a shared result.
- `applyOverrides` still runs last so an operator pin outranks everything.
- The English caption and archive keep what was actually said.
- Voice: `speech-text.js` has Spanish book-name rules (`ES_BOOKS`) that fire on
  `1 Corintios` → `Primera de Corintios`. New variants must not produce forms
  outside that list or the voice reads "uno Juan".
- Each variant needs its own voice choice — es_ES should get a Castilian voice
  (miro/sharvard, measured male), es_MX the Mexican `ald`.

## Open questions for the audit
1. Is the source-side gate actually safe? Where does it misfire?
2. Verb-table coverage: what fraction of real sermon Spanish is reachable?
3. Does adding two pseudo-languages break the shared-cache invariant?
4. Is `vosotros` even wanted? RVR1960 uses it and is read across Latin America.
5. Does the listener page cope with three Spanish entries in the picker?