michangarrito/docs/01-epicas/MCH-026-multi-idioma-latam.md

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-026	Epic	MCH-026: Multi-idioma LATAM	MCH-026	Completado	Pendiente	Sin implementacion de i18n	7	P3	2026-01-10	2026-01-17	4.0.1	34	blocks depends_on

MCH-026: Multi-idioma LATAM

Metadata

• Codigo: MCH-026
• Fase: 7 - Expansion (Futuro)
• Prioridad: P3
• Estado: Pendiente
• Estado Real: No hay implementacion de internacionalizacion
• Sprint Asignado: Sprint 6 (Mobile)
• Story Points: 34

Descripcion

Internacionalizacion (i18n) de la aplicacion para expansion a otros paises de Latinoamerica: soporte multi-idioma, localizacion de formatos (moneda, fecha), y adaptacion de terminologia por pais.

Objetivos

1. Soporte multi-idioma (es-MX, es-CO, es-AR, pt-BR)
2. Localizacion de monedas y formatos
3. Terminologia adaptada por pais
4. Contenido de ayuda localizado
5. Deteccion automatica de region

Alcance

Incluido

• Espanol Mexico (es-MX) - default
• Espanol Colombia (es-CO)
• Espanol Argentina (es-AR)
• Portugues Brasil (pt-BR)
• Formatos de moneda locales
• Formatos de fecha locales

Excluido

• Ingles (no es mercado objetivo inicial)
• Otros idiomas latinoamericanos
• Traduccion de contenido generado por usuario

Paises Objetivo

Pais	Codigo	Moneda	Formato Fecha
Mexico	es-MX	MXN ($)	DD/MM/YYYY
Colombia	es-CO	COP ($)	DD/MM/YYYY
Argentina	es-AR	ARS ($)	DD/MM/YYYY
Brasil	pt-BR	BRL (R$)	DD/MM/YYYY

Terminologia por Pais

Concepto	Mexico	Colombia	Argentina	Brasil
Tienda	Changarro	Tienda	Almacen	Loja
Fiado	Fiado	Fiado	Cuenta	Fiado
Efectivo	Efectivo	Efectivo	Efectivo	Dinheiro
Codigo de barras	Codigo	Codigo	Codigo	Codigo de barras

Arquitectura i18n

Estructura de Archivos

locales/
├── es-MX/
│   ├── common.json
│   ├── pos.json
│   ├── products.json
│   └── errors.json
├── es-CO/
│   └── ...
├── es-AR/
│   └── ...
└── pt-BR/
    └── ...

Ejemplo de Archivo

// locales/es-MX/pos.json
{
  "title": "Punto de Venta",
  "cart": {
    "empty": "Tu carrito esta vacio",
    "total": "Total",
    "checkout": "Cobrar"
  },
  "payment": {
    "cash": "Efectivo",
    "card": "Tarjeta",
    "credit": "Fiado",
    "change": "Cambio"
  }
}

// locales/pt-BR/pos.json
{
  "title": "Ponto de Venda",
  "cart": {
    "empty": "Seu carrinho esta vazio",
    "total": "Total",
    "checkout": "Finalizar"
  },
  "payment": {
    "cash": "Dinheiro",
    "card": "Cartao",
    "credit": "Fiado",
    "change": "Troco"
  }
}

Implementacion Tecnica

Frontend (React)

import { useTranslation } from 'react-i18next';

function POSPage() {
  const { t } = useTranslation('pos');

  return (
    <div>
      <h1>{t('title')}</h1>
      <Cart
        emptyMessage={t('cart.empty')}
        totalLabel={t('cart.total')}
      />
    </div>
  );
}

Mobile (React Native)

import { useTranslation } from 'react-i18next';

// Mismo patron que web

Backend

// Mensajes de error localizados
throw new BadRequestException(
  i18n.t('errors.product_not_found', { lang: user.locale })
);

Formatos de Moneda

// Formateo dinamico
const formatCurrency = (amount: number, locale: string) => {
  const config = {
    'es-MX': { currency: 'MXN', symbol: '$' },
    'es-CO': { currency: 'COP', symbol: '$' },
    'es-AR': { currency: 'ARS', symbol: '$' },
    'pt-BR': { currency: 'BRL', symbol: 'R$' }
  };

  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: config[locale].currency
  }).format(amount);
};

// Resultados:
// es-MX: $1,234.56
// es-CO: $1.234,56
// es-AR: $1.234,56
// pt-BR: R$ 1.234,56

Modelo de Datos

Campos Adicionales

tenants

• locale: string (es-MX, es-CO, etc.)
• timezone: string
• currency: string

users

• locale: string (override de tenant)

Endpoints API

Metodo	Endpoint	Descripcion
GET	/locales	Idiomas disponibles
GET	/locales/:locale	Traducciones
PUT	/settings/locale	Cambiar idioma

Deteccion Automatica

// Al registrarse
1. Detectar IP del usuario
2. Geolocalizar pais
3. Asignar locale default
4. Usuario puede cambiar en settings

Historias de Usuario

MCH-US-250: Setup i18n

Story Points: 8

Como desarrollador Quiero configurar react-i18next en las aplicaciones web y mobile Para tener la infraestructura base de internacionalizacion lista

Criterios de Aceptacion

• [CA-250-1] react-i18next instalado y configurado en app web
• [CA-250-2] react-i18next instalado y configurado en app mobile
• [CA-250-3] Estructura de carpetas locales/ creada con archivos base
• [CA-250-4] Hook useTranslation funciona en componentes de prueba
• [CA-250-5] Cambio de idioma dinamico funciona sin recargar app
• [CA-250-6] Fallback a es-MX cuando traduccion no existe

Tareas

ID	Tarea	Estimacion
MCH-TT-250-01	Instalar dependencias i18n en web	1h
MCH-TT-250-02	Configurar i18next provider en web	2h
MCH-TT-250-03	Instalar dependencias i18n en mobile	1h
MCH-TT-250-04	Configurar i18next provider en mobile	2h
MCH-TT-250-05	Crear estructura de carpetas locales/	1h
MCH-TT-250-06	Implementar language detector	2h
MCH-TT-250-07	Crear componente LanguageSwitcher	2h
MCH-TT-250-08	Tests de integracion i18n	2h

---

MCH-US-251: Traducciones es-MX

Story Points: 5

Como usuario mexicano Quiero ver la aplicacion en espanol de Mexico Para entender perfectamente la terminologia local (changarro, fiado, etc.)

Criterios de Aceptacion

• [CA-251-1] Archivo locales/es-MX/common.json completo
• [CA-251-2] Archivo locales/es-MX/pos.json completo
• [CA-251-3] Archivo locales/es-MX/products.json completo
• [CA-251-4] Archivo locales/es-MX/errors.json completo
• [CA-251-5] Terminologia mexicana validada (changarro, fiado)
• [CA-251-6] 100% de strings de UI traducidos

Tareas

ID	Tarea	Estimacion
MCH-TT-251-01	Extraer todas las strings de la app	3h
MCH-TT-251-02	Crear common.json es-MX	2h
MCH-TT-251-03	Crear pos.json es-MX	2h
MCH-TT-251-04	Crear products.json es-MX	2h
MCH-TT-251-05	Crear errors.json es-MX	1h
MCH-TT-251-06	Validar terminologia con usuarios mexicanos	2h

---

MCH-US-252: Traducciones es-CO

Story Points: 3

Como usuario colombiano Quiero ver la aplicacion en espanol de Colombia Para sentirme identificado con la terminologia local

Criterios de Aceptacion

• [CA-252-1] Archivos locales/es-CO/ completos
• [CA-252-2] Terminologia colombiana aplicada
• [CA-252-3] Formato de moneda COP configurado
• [CA-252-4] 100% de strings traducidos

Tareas

ID	Tarea	Estimacion
MCH-TT-252-01	Copiar base es-MX a es-CO	0.5h
MCH-TT-252-02	Adaptar terminologia colombiana	2h
MCH-TT-252-03	Validar con usuarios colombianos	2h
MCH-TT-252-04	Configurar formato moneda COP	1h

---

MCH-US-253: Traducciones es-AR

Story Points: 3

Como usuario argentino Quiero ver la aplicacion en espanol de Argentina Para usar terminologia familiar (almacen, cuenta, vos)

Criterios de Aceptacion

• [CA-253-1] Archivos locales/es-AR/ completos
• [CA-253-2] Terminologia argentina aplicada (almacen en vez de tienda)
• [CA-253-3] Formato de moneda ARS configurado
• [CA-253-4] 100% de strings traducidos

Tareas

ID	Tarea	Estimacion
MCH-TT-253-01	Copiar base es-MX a es-AR	0.5h
MCH-TT-253-02	Adaptar terminologia argentina	2h
MCH-TT-253-03	Validar con usuarios argentinos	2h
MCH-TT-253-04	Configurar formato moneda ARS	1h

---

MCH-US-254: Traducciones pt-BR

Story Points: 5

Como usuario brasileno Quiero ver la aplicacion en portugues de Brasil Para usar la app en mi idioma nativo

Criterios de Aceptacion

• [CA-254-1] Archivos locales/pt-BR/ completos
• [CA-254-2] Traducciones profesionales al portugues brasileno
• [CA-254-3] Terminologia comercial brasilena (loja, dinheiro)
• [CA-254-4] Formato de moneda BRL (R$) configurado
• [CA-254-5] 100% de strings traducidos

Tareas

ID	Tarea	Estimacion
MCH-TT-254-01	Copiar estructura de es-MX a pt-BR	0.5h
MCH-TT-254-02	Contratar servicio traduccion profesional	1h
MCH-TT-254-03	Aplicar traducciones profesionales	3h
MCH-TT-254-04	Validar con usuarios brasilenos	3h
MCH-TT-254-05	Configurar formato moneda BRL	1h

---

MCH-US-255: Localizacion de Monedas y Formatos

Story Points: 5

Como usuario de cualquier pais LATAM Quiero ver precios y fechas en el formato de mi pais Para entender rapidamente los valores sin hacer conversiones mentales

Criterios de Aceptacion

• [CA-255-1] MXN formateado como $1,234.56
• [CA-255-2] COP formateado como $1.234,56
• [CA-255-3] ARS formateado como $1.234,56
• [CA-255-4] BRL formateado como R$ 1.234,56
• [CA-255-5] Fechas formateadas como DD/MM/YYYY para todos
• [CA-255-6] Utility formatCurrency funciona con todos los locales

Tareas

ID	Tarea	Estimacion
MCH-TT-255-01	Crear utils/currency.ts con Intl.NumberFormat	2h
MCH-TT-255-02	Crear utils/date.ts con formateo local	2h
MCH-TT-255-03	Integrar formatters en componentes POS	3h
MCH-TT-255-04	Integrar formatters en reportes	2h
MCH-TT-255-05	Tests unitarios de formatters	2h

---

MCH-US-256: Deteccion Automatica de Region

Story Points: 5

Como usuario nuevo Quiero que la app detecte automaticamente mi pais Para no tener que configurar manualmente el idioma y moneda

Criterios de Aceptacion

• [CA-256-1] Deteccion de pais por IP al registrarse
• [CA-256-2] Asignacion automatica de locale segun pais detectado
• [CA-256-3] Usuario puede cambiar locale en configuracion
• [CA-256-4] Preferencia de locale persistida en base de datos
• [CA-256-5] Fallback a es-MX si pais no soportado

Tareas

ID	Tarea	Estimacion
MCH-TT-256-01	Integrar servicio geolocalizacion IP	3h
MCH-TT-256-02	Implementar logica deteccion en registro	2h
MCH-TT-256-03	Agregar campo locale a modelo tenant	1h
MCH-TT-256-04	Agregar campo locale a modelo user	1h
MCH-TT-256-05	Crear pantalla configuracion de idioma	3h
MCH-TT-256-06	Endpoint PUT /settings/locale	2h
MCH-TT-256-07	Tests de integracion	2h

---

Resumen de Historias de Usuario

ID	Historia	Story Points	Prioridad
MCH-US-250	Setup i18n	8	Alta
MCH-US-251	Traducciones es-MX	5	Alta
MCH-US-252	Traducciones es-CO	3	Media
MCH-US-253	Traducciones es-AR	3	Media
MCH-US-254	Traducciones pt-BR	5	Media
MCH-US-255	Localizacion de Monedas y Formatos	5	Alta
MCH-US-256	Deteccion Automatica de Region	5	Media
Total		34

Entregables

Entregable	Estado	Archivo
Archivos i18n es-MX	Pendiente	locales/es-MX/
Archivos i18n es-CO	Pendiente	locales/es-CO/
Archivos i18n es-AR	Pendiente	locales/es-AR/
Archivos i18n pt-BR	Pendiente	locales/pt-BR/
i18n setup React	Pendiente	lib/i18n.ts
Currency formatter	Pendiente	utils/currency.ts

Dependencias

Depende de

• App completa y estable
• Expansion de negocio a otros paises

Bloquea a

• Lanzamiento en Colombia, Argentina, Brasil

Criterios de Aceptacion

• App funciona en es-MX (default)
• App funciona en es-CO
• App funciona en es-AR
• App funciona en pt-BR
• Monedas se formatean correctamente
• Usuario puede cambiar idioma

Consideraciones

Traduccion

• Usar servicio profesional para pt-BR
• Validar terminologia con usuarios locales
• No traducir nombres de productos

Legal

• Adaptar terminos y condiciones por pais
• Politica de privacidad por region
• Cumplimiento normativo local

---

Ultima actualizacion: 2026-01-17