ADR-035 — Internationalization

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-035-i18n.md

ADR-035: Internationalization

Estado

Accepted — 2026-08-23
Amended — 2026-08-23: locales de producto en-US y es (mismo patrón IVPrior).

Contexto

ICP V1 = Estados Unidos (DOC-001). El equipo y parte de los usuarios operan en español. IVPrior publica Help EN+ES con la misma sustancia. Un solo locale en Help/UI pinta contra la pared.

Decisión

  1. Locales de producto: en (en-US) y es. UI extractable, emails de plantilla, Help Center. Default de Organization: en-US (ICP US).
  2. Fechas/números: timezone y currency de Organization (America/New_York / USD por defecto).
  3. Strings de UI en archivos de mensajes por locale (messages/en.json, messages/es.json cuando exista i18n de app) — no copy hardcodeado en 40 sitios.
  4. Help: apps/help/content/{en,es}/{module}/{slug}.md. Misma sustancia; el par ES es gate (ADR-080).
  5. No traducir schema, APIs ni identificadores de dominio (Organization, Invoice, PromiseToPay).
  6. Developer Docs (apps/docs): shell bilingüe /en y /es (mismo patrón IVPrior). El markdown del repo (ADRs, DOCs, OpenAPI) es una sola fuente; se traduce el chrome (nav, títulos de guía en messages/{en,es}.json), no se duplica cada ADR.
  7. LATAM/UK como mercado (compliance, mailbox) = amendment + review (ADR-020, ADR-026).

Consecuencias

  • Agentes escriben copy de pantalla y Help en EN y ES en el mismo slice.
  • Artefactos Spec Kit / OpenSpec siguen en español (constitution §VII).
  • Código, commits y APIs: inglés.