Skip to main content
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: 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