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

---
id: EPIC-MCH-026
type: Epic
title: "MCH-026: Multi-idioma LATAM"
code: MCH-026
status: Completado
status_real: "Pendiente"
status_nota: "Sin implementacion de i18n"
phase: 7
priority: P3
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 34
dependencies:
  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
```json
// 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)
```typescript
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)
```typescript
import { useTranslation } from 'react-i18next';

// Mismo patron que web
```

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

## Formatos de Moneda

```typescript
// 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

```typescript
// 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