Documentación en español · English
#Objetivo
Payment Emulator trata la internacionalización como infraestructura transversal de presentación/runtime, no como responsabilidad de entidades de dominio, gateways, server-state o transporte HTTP. La consola Nuxt soporta inglés (en) y español (es) canónicos mediante una única autoridad de locale SSR-safe sin cambiar diseño visual, contratos backend ni rutas funcionales.
#Contrato canónico y autoridad
export const APP_LOCALES = ['en', 'es'] as const
export type AppLocale = (typeof APP_LOCALES)[number]
export const DEFAULT_LOCALE: AppLocale = 'es'
export const FALLBACK_LOCALE: AppLocale = 'en'
Variantes regionales como en-GB, en-US, es-ES o es-CU se normalizan antes de entrar en la frontera de aplicación. Español continúa siendo el default para preservar el contrato de la URL pública /; ambos idiomas de consola están implementados.
El código de aplicación consulta o cambia idioma mediante:
useAppLocale()
├─ locale
├─ availableLocales
├─ setLocale()
└─ isLocaleSupported()
Nuxt I18n posee el Composer reactivo, los catálogos lazy y la cookie emulator_locale. Los componentes no escriben esa cookie, no utilizan localStorage como estado de idioma y no mutan $i18n directamente.
#Pipeline runtime
APP_LOCALES / AppLocale
↓
normalizeLocale()
↓
useAppLocale()
↓
Nuxt I18n
├── locale reactivo
├── catálogos lazy por feature
└── cookie emulator_locale
↓
proyecciones de presentación
├── <html lang>
├── locale PrimeVue
└── formatters Intl (Fase 6)
El middleware de rutas públicas da prioridad al idioma explícito de una URL localizada y delega la sincronización a useAppLocale().setLocale(); no inventa rutas nuevas.
#Routing
Las URLs públicas físicas existentes continúan siendo autoridad SEO:
/ landing española
/en landing inglesa
/docs/es/** documentación española
/docs/en/** documentación inglesa
Las rutas autenticadas como /login, /applications, /banks, /bank-accounts, /gateways, /scenarios y /users permanecen sin prefijo. Cambiar el idioma de UI no reescribe esas rutas funcionales.
#Ownership de mensajes
Los entrypoints lazy i18n/locales/en.ts y i18n/locales/es.ts componen mensajes core con catálogos cuyo owner físico es app/modules/<context>/<feature>/i18n/. La copia de negocio no se concentra en un único JSON global sin ownership. Los owners JSON tienen estructuras de claves EN/ES equivalentes. Landing posee public/landing/i18n/catalog.ts, con inglés tipado estructuralmente desde español, montado bajo public.landing; Docs posee su pareja JSON bajo public.docs. Ambos usan Nuxt I18n en runtime. Hay 13 owners de catálogos, incluidos core y Landing.
Los namespaces estables siguen los contextos de la aplicación: administration, banking, configuration, integrations, observability, payments y public; common queda reservado para conceptos realmente transversales.
#Sincronización PrimeVue — Fase 5
Vue I18n no traduce automáticamente el vocabulario interno de PrimeVue. Payment Emulator posee por ello adaptadores completos:
app/core/i18n/primevue/types.ts
app/core/i18n/primevue/en.ts
app/core/i18n/primevue/es.ts
app/core/i18n/primevue/index.ts
PrimeVueAppLocale obliga a cubrir en compile-time todo el contrato locale y ARIA de la versión PrimeVue instalada. Esto incluye filtros, paginator, fecha/calendario, FileUpload, feedback de Password, anuncios de búsqueda/selección y accesibilidad, incluso para superficies todavía no presentes en todas las rutas.
La sincronización runtime queda aislada en app/plugins/primevue-locale.ts:
useAppLocale().locale
↓
primeVueLocaleFor(locale)
↓
PrimeVue config.locale
El plugin aplica inmediatamente el locale ya resuelto para SSR y lo observa reactivamente. PrimeVue es solo consumidor: no posee persistencia, routing ni una segunda preferencia de idioma. El validator prohíbe mutar directamente PrimeVue.config.locale fuera de este sincronizador.
El inglés canónico es en-GB, por lo que PrimeVue usa semanas iniciadas en lunes y dd/mm/yy en lugar de sus defaults estadounidenses; español mantiene la misma forma de calendario.
#Frontera arquitectónica
AppLocale
├─ Vue/Nuxt I18n
├─ PrimeVue locale
├─ Intl formatters
└─ Presentation
└─ use{Entity}Collection / UI composables
└─ RestBaseQuery
└─ feature gateway
└─ RestTransport
Cambiar idioma no debe refetchear server-state neutral al locale ni alterar query keys de TanStack. Solo un endpoint que realmente devuelva contenido localizado puede incorporar locale a su request/identidad de caché.
#Fechas, números y moneda
La Fase 6 centraliza Intl.DateTimeFormat, Intl.NumberFormat, moneda, porcentaje y formatos relacionados detrás de helpers gobernados por AppLocale. Los valores canónicos de backend/dominio permanecen intactos; cambia únicamente su representación.
#Estados, errores y validaciones
Códigos backend semánticos como NOT_FOUND, CONFLICT, FORBIDDEN y UNAUTHENTICATED permanecen neutrales al idioma. useAppError().explain(error, localizedFallback) mapea códigos o status HTTP a claves de traducción y nunca expone mensajes humanos del backend. Los fallos desconocidos reciben el fallback seguro y localizado del consumidor.
Los errores inline conservan la causa semántica y calculan su texto visible. Los toasts persistentes reciben getters en useNotify().failed(), de modo que cambiar idioma actualiza una notificación existente sin otra petición. Los tests cubren fallo de red, timeout, 400/401/403/404/409/422/500 y errores desconocidos en ambos idiomas. La suite de navegador verifica login rechazado y errores seguros y reactivos de formularios/acciones. El estado del tour pertenece a cada aplicación Nuxt para impedir que solicitudes SSR compartan getters ligados al idioma.
#URLs públicas y SEO
Nuxt I18n posee el runtime de idioma con no_prefix; las rutas públicas físicas conservan / para español, /en para inglés y /docs/{es,en}/** para documentación. /login y las rutas autenticadas permanecen sin prefijo. El middleware público sincroniza el idioma explícito de la URL mediante useAppLocale() antes de renderizar; la identidad de la URL pública prevalece sobre la cookie de preferencia.
publicLocalePath(locale, path) es el helper puro de URLs públicas que consumen navegación pública, alternates SEO, alternates del sitemap y recuperación del error global. Canonical, hreflang, datos estructurados, SSR e hidratación se comprueban en ambos idiomas. useLocale.ts, los antiguos diccionarios públicos core y core/rest/explainFailure.ts están eliminados; los wrappers de compatibilidad no forman parte del runtime.
#Flujo de traducción
Para nueva copia, añadir claves semánticas equivalentes en los catálogos EN/ES de la feature propietaria, consumirlas mediante useI18n() o la fachada de presentación existente y mantener reactiva la configuración traducida. Para una feature nueva, registrar sus catálogos en ambos entrypoints lazy bajo su namespace. Para un idioma nuevo, ampliar APP_LOCALES, metadata, todos los catálogos incluido Landing, la proyección PrimeVue, la política Intl y los tests de URLs públicas/SEO. Nunca añadir idioma a query keys neutrales ni traducir valores de dominio enviados a la API.
#Verificación y gobernanza
npm run validate:architecture --workspace @payment-emulator/console ejecuta los validators de arquitectura e i18n más i18n:audit; se exigen cero violaciones sin exclusiones de migración. validate:i18n e i18n:audit también pueden ejecutarse por separado en ese workspace. La suite de Console cubre contrato/runtime/catálogos, composables reales, normalización REST, routing público, PrimeVue e Intl. CI completo añade typecheck, lint del repositorio, tests, builds de producción, Compose, smoke SSR/público/docs y E2E de navegador/pagos. Ejecutar smoke:stack antes de smoke:i18n:browser para crear su operador; el navegador se instala como declara .github/workflows/ci.yml.
El cierre utiliza dos rondas completas de CI: implementación S1 correcta, seguida de gobernanza S2 y otra ejecución completa. El artefacto phase-10-14-certification registra SHA final, URL de ejecución y COMPLETE para cada fase solo después de que pasen los jobs requeridos; la ejecución completa debe terminar en SUCCESS. La evidencia de navegador se publica como console-i18n-browser. Una ejecución verde de un SHA anterior no certifica el HEAD actual. La PR #4 permanece en borrador, abierta y sin fusionar durante este proceso.
El diagnóstico Docker encontró un 500 SSR por consumidores del eliminado useLocale() y la caída del worker porque BullMQ prohíbe dos puntos en nombres de cola. El primero se corrige con la frontera canónica de idioma; el segundo utiliza el prefix de BullMQ conservando el namespace existente de claves Redis. CI ejecuta tests reales de colas Redis, captura diagnósticos de contenedores y comprueba que los seis servicios siguen activos después del E2E sin relajar healthchecks.
El rollout detallado está gobernado por apps/console/.nuxt-refactor/.agents/i18n/implementation-plan.md. Cualquier cambio al contrato i18n productivo debe actualizar conjuntamente implementación, .agents, ambos idiomas de documentación y tests relevantes.