> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-023 — Español como único idioma de la documentación

> DEC-I1 fijó el inglés como canónico y Mintlify bilingüe. El costo real es que cada cambio se paga dos veces, y el equipo que lee y decide trabaja en español.

Estado: Aceptado · Fecha: 2026-08-18 · **Revierte DEC-I1** · Afecta: DEC-I3, `standards/*`, el validador `translation`

## Contexto

DEC-I1 decidió que la documentación del repositorio —constitución, estándares, ADRs, specs— se
escribiera en **inglés**, y que Mintlify fuera **bilingüe EN/ES**. La razón era defendible: el
inglés es el idioma del código y de la industria, y un espejo en español permitía que cualquiera
revisara el material completo.

Después de generar todo el sistema de specs, el costo de esa decisión ya no es teórico:

* **278 páginas, de las cuales la mitad son espejos.** No hay 278 documentos; hay 139 documentos
  escritos dos veces.
* **Cada cambio se paga dos veces.** Subir un spec de `0.2.0` a `1.0.0` toca dos archivos. Responder
  una pregunta abierta toca dos archivos. El validador `translation` existe justamente porque ese
  segundo archivo se queda atrás solo.
* **La revisión ocurre en español de todos modos.** Las 70 preguntas abiertas, el registro de
  decisiones y todo el paquete legal se escribieron en español porque es donde se piensa. El árbol
  en inglés era la traducción, no al revés — aunque el rótulo dijera lo contrario.
* **El cuello de botella no es escribir, es decidir.** Cero specs están `approved`. Duplicar el
  esfuerzo de escritura mientras las decisiones esperan es gastar en el lado equivocado.

Lo que la decisión original protegía era la posibilidad de sumar a alguien que no lea español, y la
coherencia entre la documentación y el código, que sí está en inglés. Lo primero es un costo
diferido y pequeño: traducir cuando esa persona exista es más barato que mantener el espejo cada
día hasta entonces. Lo segundo es real y no se resuelve eligiendo un idioma para todo, sino
separando **prosa** de **código**.

## Decisión

**El español es el único idioma de `docs/internal`.** El árbol en inglés se elimina; el espejo en
español pasa a ser el documento, no la traducción. El sitio deja de ser bilingüe y queda en español.

**El inglés se conserva para todo lo que es código o identificador.** Esta es la parte que hace que
la decisión no rompa nada: la prosa cambia de idioma, la codificación no. Se escriben en inglés, sin
traducir jamás:

| Qué                                     | Ejemplo                                                     |
| --------------------------------------- | ----------------------------------------------------------- |
| Schemas, tablas y columnas              | `loyalty.ledger_transaction`, `points_remaining`            |
| Nombres de eventos                      | `loyalty.points.earned`, `tier.grace_started`               |
| Rutas de endpoint y permisos            | `POST /v1/loyalty/redemptions`, `loyalty.redemption.create` |
| Códigos de catálogo paramétrico         | `earn`, `redeem`, `pending`, `available`                    |
| Estados de spec y campos de frontmatter | `draft`, `review`, `approved`, `depends_on`                 |
| Identificadores y sus prefijos          | `FS-LOY-0002`, `DEC-B5`, `ADR-017`, `TS-001`                |
| Rutas de archivos y carpetas            | `docs/internal/standards/data.md`                           |
| Términos con significado técnico exacto | bounded context, outbox, tenant, member, slice, port        |

La última fila es la que exige criterio. La regla es: **si traducirlo obligaría a traducir también
el código, no se traduce.** "Contacto comercializable" es prosa y se traduce; `marketable_contact`
es una columna y no. `member` se mantiene en inglés porque es un rol modelado en el sistema y el
glosario ya prohíbe llamarlo "usuario".

**Los diagramas siguen la misma regla**: los rótulos, títulos y notas van en español; los nombres de
componentes, tablas, eventos y endpoints que aparecen dentro del diagrama van en inglés, porque son
los mismos identificadores que existen en el código.

**Las rutas del sitio y los nombres de archivo se mantienen en inglés.** Son identificadores: los
citan los PRs, los enlaces y los agentes. Renombrarlos a español rompería cada enlace sin ganar
nada legible.

## Consecuencias

**+** Un solo documento por tema. 139 archivos en vez de 278, y ningún par que pueda divergir.
**+** El validador `translation` deja de existir, junto con la clase de defecto que detectaba.
**+** El esfuerzo de escritura se reduce a la mitad y se redirige a lo que está bloqueado: aprobar
specs y responder las preguntas abiertas.
**+** Quien revisa lee el documento autoritativo, no una traducción con un banner que le recuerda
que no lo es.

**−** Sumar a alguien que no lea español costará una traducción en ese momento. Es un costo
aceptado y diferido, no evitado.
**−** El material queda en un idioma distinto al del código. Se mitiga con la tabla de arriba, que
convierte la mezcla en una regla explícita en vez de una inconsistencia.
**−** Se pierde el árbol en inglés ya escrito. Está en el historial de git si alguna vez se necesita
como punto de partida.

## Alcance

Esta decisión cubre **`docs/internal`**. El sitio público (`docs/public`) es una decisión comercial
distinta —depende de a quién le vendemos y quién integra— y sigue bajo DEC-I3 hasta que se decida
por separado. `AGENTS.md` y `CLAUDE.md` se mantienen en inglés: son archivos de instrucción para
agentes, no documentación del producto.

## Trabajo de seguimiento

* Eliminar `docs/internal/en/` y el árbol canónico en inglés; promover `es/` a la raíz.
* `docs.json`: un solo idioma, cinco tabs — Panorama, Fundamentos, Módulos, Ejecución, Legal.
* Quitar el validador `translation` de `tools/scripts/validate-specs.mjs`.
* `AGENTS.md`, `CLAUDE.md` y las reglas de Cursor: reemplazar la regla "documentación en inglés".
* `modules/overview.md` §8: reescribir la sección de idiomas con la tabla de esta decisión.
* `diagrams/diagram-specs.md`: rótulos en español, identificadores en inglés.
* `glossary.md`: la tabla de arriba pasa a ser parte del vocabulario obligatorio.

## Alternativas consideradas

**Mantener el bilingüe y automatizar la traducción.** Un agente puede traducir cada cambio y el
validador `translation` ya detecta el desfase. Perdió porque no elimina el problema, lo abarata:
sigue habiendo dos archivos que pueden discrepar, sigue habiendo un banner de "traducción" en la
mitad del sitio, y una traducción automática de un documento normativo introduce ambigüedad
exactamente donde menos se puede tolerar.

**Invertir la dirección: inglés como espejo generado del español.** Conserva la puerta abierta a un
lector en inglés sin duplicar el trabajo de pensar. Perdió porque el costo de mantenimiento es el
mismo que arriba y porque nadie lee hoy ese espejo. Si esa persona aparece, esta alternativa es el
camino de vuelta más corto.

**Español también en el sitio público.** Fuera de alcance aquí a propósito: es una decisión de
mercado, no de ingeniería, y merece decidirse mirando a quién le vendemos.

## Changelog

| Versión | Fecha      | Cambio           | Por qué                                                                                                 | Autor                  |
| ------- | ---------- | ---------------- | ------------------------------------------------------------------------------------------------------- | ---------------------- |
| 1.0.0   | 2026-08-18 | Decisión inicial | El espejo bilingüe duplicaba el esfuerzo de escritura mientras el cuello de botella eran las decisiones | daniel + claude-opus-5 |