michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-026-multi-idioma-latam.md

# 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
```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
```

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