ADR-0008 — Estrategia de internacionalización (i18n)

• Estado: propuesto
• Fecha: 2026-07-06
• Decide: lead / arquitecto de la metodología

Contexto

dai nació y se escribió en español. Para su difusión —el README es lo primero que se ve en npm y GitHub, y el público de open source es mayoritariamente anglófono— hace falta una versión en inglés. Pero traducir un proyecto tiene trampas: superficies muy distintas (docs, landing HTML, mensajes del CLI, skills que son prompts), y el riesgo de que las traducciones se desincronicen del original con cada cambio.

Dos cosas juegan a favor: (1) el tono ya es español neutro internacional (se sacó el voseo y los modismos a propósito), que traduce limpio; y (2) dai puede dogfood-earse —usar un agente para traducir de forma consistente— si se le fija la terminología.

La decisión es cómo estructurar el i18n para que sea mantenible y no genere drift.

Decisión

Adoptamos un modelo de fuente única + traducciones derivadas, por superficie:

1. Fuente de verdad: el español. Se escribió primero y es el canónico. Cada archivo traducido lleva una nota — "Translation of the Spanish source; if they diverge, the Spanish wins." — igual que METODOLOGIA marca a los HTML como vistas derivadas.

2. Estructura de carpetas. docs/es/ (fuente) y docs/en/ (traducción). En la raíz, README.es.md + README.en.md, y README.md con un selector de idioma arriba (🇪🇸 Español · 🇬🇧 English). El landing: una versión por idioma o un toggle en la página.

3. CLI: locale por variable, catálogo cero-dependencias. El idioma sale de DAI_LANG (default es; si no, se puede inferir de LANG). Los strings viven en un catálogo (cli/lib/i18n.mjs, objeto { es, en }) accedido por una función t(key,…). Sin librería de i18n — fiel al ethos de cero dependencias (ADR-0006).

4. Skills: se generan en el idioma elegido. dai init --lang en|es copia la variante del SKILL.md. La IA ya es multilingüe; solo cambia el idioma de las instrucciones.

5. Glosario de términos ES→EN fijo. Para que la terminología no varíe entre archivos: QUÉ→WHAT, CÓMO→HOW, estampar→stamp, trazabilidad→traceability, atrasado→stale, etc. Es el insumo que guía la traducción (humana o asistida).

6. Implementación por fases (no todo de una): (1) README + landing en inglés · (2) docs core (MANIFIESTO, METODOLOGIA, glosario, EJEMPLO, guías) · (3) CLI i18n + skills · (4) el resto (detalle/, ADRs, templates). Se prioriza por alcance, no por completitud.

Estado medido — 2026-09-10

El ADR sigue en propuesto; esto es el relevamiento que hace falta para poder ejecutarlo, tomado al auditar la convención de naming después de la 0.15.0.

Cuánto es el trabajo de la fase 3 (CLI)

Superficie	Volumen
ok() / info() / warn() / fail() en cli/dai.mjs	348 llamadas
process.stdout.write con texto en cli/dai.mjs	99
cli/lib/help.mjs (es todo texto al usuario)	524 líneas
throw new Error(...) / fail(...) en cli/lib/	67

Del orden de mil literales. Es mecánico, pero confirma lo que el ADR ya anticipaba: se hace de una sola vez, no a pedazos. El ciclo de release (0.15.0) le sumó volumen: los comandos nuevos, su ayuda y el manifiesto son texto al usuario de punta a punta.

Lo que ya está resuelto y no hay que rehacer

• Los identificadores del código están en inglés (auditado y corregido en la 0.15.x). El refactor de i18n toca strings, no nombres.
• Las salidas de máquina ya usan claves en inglés: el manifiesto de dai release plan --json y el payload del webhook genérico.
• El glosario ES→EN de §5 ya existe y se usó: atrasado → stale fue el término que se aplicó al renombrar counts.atrasadas.

La decisión de contrato que falta tomar, y su costo real

coverageStatus() devuelve valores en español —"al-dia", "atrasado", "sin-us", "sin-respuesta"— y esos valores salen por --json: son parte de la API que puede estar parseando el CI de alguien.

Lo interesante es que el costo interno de cambiarlos es casi cero: ya están separados de lo que se muestra (statusLabel() los traduce a ✅ al día y compañía), así que el i18n de la presentación no necesita tocarlos. La única razón para renombrarlos es que una API en inglés se lea en inglés.

Entonces la decisión es puramente de contrato, y hay tres caminos:

1. Dejarlos. Son un enum opaco; el consumidor los compara, no los lee. Costo cero, inconsistencia visible en cada --json.
2. Renombrarlos en una major (up-to-date, stale, no-story, unreachable). Limpio, pero obliga a una major solo por esto.
3. Emitir los dos por un tiempo (status en inglés + status_es deprecado), y sacar el viejo en la próxima major. Es el camino habitual para no romper, y el que menos duele si ya hay alguien parseando.

No se decide acá: se decide junto con la fase 3, porque hacer dos cambios de la salida --json en versiones distintas es peor que hacer uno solo.

Recomendación de orden

Mantener el orden del ADR y no empezar por el CLI. Un CLI traducido con un README en español no lo encuentra nadie: lo que abre la herramienta a usuarios anglófonos es la fase 1 (README + landing), porque es lo que se ve en npm y en GitHub. La fase 3 recién rinde cuando ya hay alguien de habla inglesa llegando.

Consecuencias

• ✅ Alcance internacional con el README/landing en inglés (fase 1) sin reescribir todo.
• ✅ Regla anti-drift clara: una sola fuente de verdad; las traducciones nunca "ganan".
• ✅ El CLI localiza sin sumar dependencias; DAI_LANG es opt-in (default español).
• ✅ La terminología queda estable entre superficies gracias al glosario ES→EN.
• ⚠️ Doble mantenimiento: cada cambio en un .md fuente obliga a re-traducir su par. Se mitiga traduciendo con un agente + el glosario, y aceptando lag temporal en en/.
• ⚠️ El CLI necesita un refactor de strings (de literales a t(key)) — es mecánico pero toca muchos puntos; se hace de una sola vez.
• ⚠️ Hay que decidir, al implementar, si el README.md raíz redirige (selector) o es una de las lenguas (npm muestra el README.md — probablemente convenga inglés ahí).

Alternativas consideradas

• Un framework de docs con i18n (Docusaurus / VitePress / mkdocs) — descartado por ahora: aporta i18n y versionado, pero cambia todo el setup de docs (hoy markdown plano + un HTML autocontenido) y suma tooling/dependencias pesadas para un proyecto en 0.x. Reconsiderable si la doc crece mucho.
• Inglés como fuente de verdad — descartado: el contenido se authoró en español; invertir la fuente ahora duplicaría el riesgo de error justo en el material canónico (manifiesto, metodología). El español queda como fuente hasta que haya razón fuerte para migrar.
• Traducción automática sin glosario ni fuente fija — descartado: garantiza drift terminológico (el mismo término traducido distinto en cada archivo) y pérdida de la precisión del método. La traducción se ancla a un glosario y a una fuente única.