Política de idioma¶
Regla general¶
La documentación se escribe en dos capas:
| Artefacto | Idioma |
|---|---|
| Hub central, READMEs, onboarding, arquitectura, runbooks, ADRs y páginas de proyecto | Español |
| Contrato de API, OpenAPI, nombres de endpoints y campos JSON | Inglés |
| Código, nombres de variables, clases, funciones y tablas | Inglés |
| Comentarios de código | Inglés |
| Mensajes de commit y títulos de PR | Inglés |
Release notes y CHANGELOG.md |
Inglés |
| Textos de UI | Inglés como fuente, traducidos con i18n |
| Chats y comunicación interna | Español |
Por qué¶
- El equipo trabaja en español: la documentación humana debe ser fácil de leer.
- El código, los contratos y los releases son consumidos por herramientas y equipos externos: se mantienen en inglés.
- Separar ambos mundos evita traducciones inconsistentes y facilita el onboarding.
Reglas prácticas¶
- No traducir nombres técnicos:
platform-api,wallet,endpoint,deploy,rollback. - Los enlaces y rutas se mantienen tal cual.
- Los ejemplos de código y las respuestas JSON no se traducen.
- Los ADRs se escriben en español; las decisiones que afectan al contrato de API pueden citar el contrato en inglés.
- Si un README existente está en inglés y se reescribe, se pasa a español; si solo se agrega una sección, esa sección va en español.
Transición¶
Los documentos que ya están en inglés no se traducen de golpe. Se migran a español cuando se modifiquen de forma sustancial. La documentación nueva y el hub central se escriben directamente en español.
Excepciones¶
AGENTS.md: puede permanecer en inglés porque es una guía técnica para agentes. Si se traduce, debe hacerse completo.- Documentación legal o contratos con terceros: se rigen por el idioma del contrato.
- Nombres de productos y marcas: no se traducen.