# Guía de Traducciones de Enums

Este documento describe cómo usar el sistema de traducciones para enums en la aplicación.

## ¿Qué son los Enums Traducibles?

Los enums del proyecto ahora incluyen métodos para obtener etiquetas traducidas al español:

- **PaymentStatus** - Estados de pago (Pendiente, Capturado, Fallido, etc.)
- **OrderStatus** - Estados de pedido (Pagado, Preparando, Enviado, etc.)
- **ArtworkStatus** - Estados de obra de arte (Disponible, Reservado, Vendido)
- **UserRole** - Roles de usuario (Cliente, Personal)
- **PaymentProvider** - Proveedores de pago (Mercado Pago, PayPal)

## Métodos Disponibles en Cada Enum

### label()

Retorna la etiqueta traducida al español:

```php
$paymentStatus = PaymentStatus::CAPTURED;
echo $paymentStatus->label(); // "Capturado"

$orderStatus = OrderStatus::PAID;
echo $orderStatus->label(); // "Pagado"

$role = UserRole::CUSTOMER;
echo $role->label(); // "Cliente"
```

### color()

Retorna una clase de color Bootstrap para usar en estilos:

```php
$paymentStatus = PaymentStatus::CAPTURED;
echo $paymentStatus->color(); // "success"

$orderStatus = OrderStatus::CANCELLED;
echo $orderStatus->color(); // "danger"

// Colores disponibles:
// - success (verde)
// - danger (rojo)
// - warning (amarillo)
// - info (azul)
// - primary (índigo)
// - secondary (gris)
```

### description() (solo en UserRole)

Retorna una descripción detallada del rol:

```php
$role = UserRole::STAFF;
echo $role->description(); // "Miembro del personal con acceso al panel de administración"
```

## Uso en Vistas Blade

### Opción 1: Directo desde el enum

```blade
<!-- Mostrar etiqueta -->
<span>{{ $payment->status->label() }}</span>

<!-- Mostrar con color -->
<span class="badge bg-{{ $payment->status->color() }}">
    {{ $payment->status->label() }}
</span>
```

### Opción 2: Usar el componente Status Badge

```blade
<!-- Componente reutilizable para mostrar estados -->
<x-status-badge :status="$payment->status" />

<!-- Con diferentes tamaños -->
<x-status-badge :status="$payment->status" size="sm" />
<x-status-badge :status="$payment->status" size="lg" />
```

### Opción 3: Usar el EnumTranslator helper

```php
use App\Support\Helpers\EnumTranslator;

// En una clase PHP
$label = EnumTranslator::label($payment->status); // "Capturado"
$color = EnumTranslator::color($payment->status); // "success"
$description = EnumTranslator::description($payment->status); // Descripción...

// Obtener todas las opciones para un select
$options = EnumTranslator::options(PaymentStatus::class);
// Resultado: ['pending' => 'Pendiente', 'authorized' => 'Autorizado', ...]
```

## Uso en Componentes Livewire

### Mostrar estado actual

```php
// En el componente Livewire
public function render()
{
    return view('livewire.checkout', [
        'orderStatus' => $this->order->status, // OrderStatus enum
    ]);
}
```

```blade
<!-- En la vista -->
<div>
    <p>Estado del pedido:</p>
    <x-status-badge :status="$orderStatus" />
</div>
```

### En formularios selectores

```php
use App\Support\Helpers\EnumTranslator;
use App\Domains\Sales\Enums\OrderStatus;

// En el componente
public $orderStatus;

public function getStatusOptions()
{
    return EnumTranslator::options(OrderStatus::class);
}
```

```blade
<!-- En la vista -->
<select wire:model="orderStatus">
    @foreach($this->getStatusOptions() as $value => $label)
        <option value="{{ $value }}">{{ $label }}</option>
    @endforeach
</select>
```

## Estructura de Traducciones

Las traducciones están organizadas en `resources/lang/es/enums.php`:

```php
return [
    'payment_status' => [
        'pending' => 'Pendiente',
        'captured' => 'Capturado',
        ...
    ],
    'order_status' => [
        'pending' => 'Pendiente',
        'paid' => 'Pagado',
        ...
    ],
    'colors' => [
        'pending' => 'warning',
        'captured' => 'success',
        ...
    ],
    'descriptions' => [
        'payment_status' => [
            'pending' => 'En espera de procesamiento',
            ...
        ],
    ],
];
```

## Agregar Nuevos Enums Traducibles

Para crear un nuevo enum traducible:

1. **Crear el enum** en `app/Domains/{Domain}/Enums/`:

```php
<?php
namespace App\Domains\Example\Enums;

enum ExampleStatus: string {
    case ACTIVE = "active";
    case INACTIVE = "inactive";

    public function label(): string
    {
        return match($this) {
            self::ACTIVE => 'Activo',
            self::INACTIVE => 'Inactivo',
        };
    }

    public function color(): string
    {
        return match($this) {
            self::ACTIVE => 'success',
            self::INACTIVE => 'danger',
        };
    }
}
```

2. **Agregar traducciones** en `resources/lang/es/enums.php`:

```php
'example_status' => [
    'active' => 'Activo',
    'inactive' => 'Inactivo',
],
```

3. **Usar en vistas**:

```blade
<x-status-badge :status="$example->status" />
```

## Colores Disponibles

| Color | Clase CSS | Uso |
|-------|-----------|-----|
| success | bg-green-100 text-green-800 | Estados completados, disponibles |
| danger | bg-red-100 text-red-800 | Errores, cancelaciones, vendido |
| warning | bg-yellow-100 text-yellow-800 | Estados pendientes, en espera |
| info | bg-blue-100 text-blue-800 | Estados informativos, autorizados |
| primary | bg-indigo-100 text-indigo-800 | Estados primarios de proceso |
| secondary | bg-gray-100 text-gray-800 | Estados secundarios, neutrales |

## Mejores Prácticas

✅ **Hacer:**
- Usar `$enum->label()` en vistas para mostrar estados
- Usar `<x-status-badge>` para componentes reutilizables
- Mantener los métodos label() en los enums para lógica de negocio
- Usar EnumTranslator::options() para llenar select/dropdowns

❌ **No hacer:**
- Hardcodear etiquetas en las vistas
- Usar `$enum->value` directamente (usa label() en su lugar)
- Mezclar traducciones con lógica de negocio

## Ejemplos Prácticos

### Tabla con Estados Traducidos

```blade
<table>
    <thead>
        <tr>
            <th>Pedido</th>
            <th>Estado</th>
        </tr>
    </thead>
    <tbody>
        @foreach($orders as $order)
            <tr>
                <td>{{ $order->id }}</td>
                <td>
                    <x-status-badge :status="$order->status" size="sm" />
                </td>
            </tr>
        @endforeach
    </tbody>
</table>
```

### Dashboard con Filtros

```blade
<div class="filters">
    <select>
        <option value="">Todos los estados</option>
        @foreach(EnumTranslator::options(OrderStatus::class) as $value => $label)
            <option value="{{ $value }}">{{ $label }}</option>
        @endforeach
    </select>
</div>
```

### Alertas por Estado

```blade
@if($payment->status === PaymentStatus::FAILED)
    <div class="alert alert-danger">
        Pago rechazado. {{ $payment->status->label() }}
    </div>
@elseif($payment->status === PaymentStatus::CAPTURED)
    <div class="alert alert-success">
        Pago completado: {{ $payment->status->label() }}
    </div>
@endif
```

## Actualizando el Sistema

Cuando necesites cambiar etiquetas o agregar nuevos enums:

1. Edita el archivo del enum en `app/Domains/{Domain}/Enums/`
2. Actualiza el archivo de traducciones si corresponde
3. Prueba los cambios en las vistas que usan ese enum
4. Commit con un mensaje descriptivo: "Traducción: Agregar/actualizar estado X"

---

**Última actualización**: Marzo 10, 2026
**Sistema**: Traducciones de Enums v1.0