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

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-026	Epic	MCH-026: Multi-idioma LATAM	MCH-026	Pendiente	7	P3	2026-01-10	2026-01-10	3.8.0	blocks depends_on

MCH-026: Multi-idioma LATAM

Metadata

• Codigo: MCH-026
• Fase: 7 - Expansion (Futuro)
• Prioridad: P3
• Estado: Completado (Base)
• Fecha completado: 2026-01-10

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

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-07