🈺 useLocales

🎯 Propósito

useLocales es un composable que carga archivos de traducción JSON para páginas o componentes en el idioma activo de la aplicación, con un sistema robusto de fallback para garantizar que siempre haya datos disponibles, especialmente en español.

---

⚙️ Funcionalidades clave

• 🌐 Carga el archivo de traducción correspondiente al idioma actual.
• 🔄 Si el archivo no existe, hace fallback al archivo en español.
• 🧩 Si el archivo existe pero tiene claves faltantes, completa esas claves con la versión en español.
• 🔍 El merge es recursivo y profundo, incluyendo la gestión correcta de arrays de objetos con clave id.
• 📋 En arrays con objetos con id, mantiene el orden original del fallback para los elementos faltantes, evitando que se añadan al final.
• 📦 Retorna un objeto con la propiedad data que contiene la estructura traducida final lista para usar.

---

🚀 Uso básico

import { useLocales } from "@/composables/useLocales";

async function cargarTraducciones() {
  const { data } = await useLocales<"home">("home");
  console.log(data.tituloPagina);
}

---

🗂️ Estructura esperada de los archivos JSON

{
  "cards": [
    {
      "id": 1,
      "title": "Título en el idioma",
      "description": "Descripción en el idioma"
    }
  ],
  "header": {
    "welcome": "Texto de bienvenida"
  }
}

---

🔍 Casos de uso y comportamiento ante faltantes

1. ❌ Archivo de traducción para el idioma actual no existe

• Se detecta que no se puede importar el archivo de traducción del idioma activo.
• Se carga automáticamente el archivo en español (es) como fallback completo.
• Si tampoco existe el español, se retorna un objeto vacío {} y se muestra error en consola.

---

2. ⚠️ Archivo de traducción existe, pero faltan claves específicas

• Se carga el archivo del idioma activo.

• Se carga el archivo español (es) como fallback.

• Se hace un merge recursivo donde:

  • Los valores del idioma activo tienen prioridad.
  • Las claves faltantes o vacías en el idioma activo se completan con la versión en español.

• Esto incluye claves en objetos anidados y arrays con objetos con id.

---

3. 📉 Falta un dato concreto dentro de un objeto

Ejemplo:

{
  "title": "", // vacío en idioma activo
  "description": "Texto"
}

• title vacío o string vació será completado con el valor en español.
• description se mantiene del idioma activo.

---

4. 🗃️ Falta un elemento completo dentro de un array

Ejemplo:

"cards": [
  {
    "id": 1,
    "title": "Título 1",
    "description": "Descripción 1"
  },
  // falta el objeto con id 2
  {
    "id": 3,
    "title": "Título 3",
    "description": "Descripción 3"
  }
]

• El objeto con id: 2 que falte se inserta en la misma posición que tiene en el archivo español.
• Así se mantiene el orden correcto, y no se añade al final.

---

5. ⚙️ Manejo de arrays sin id

• Si el array no contiene objetos con propiedad id, se hace un merge posicional.
• Se completan los elementos faltantes por índice, pero puede que no preserve la lógica exacta si el orden cambia.
• Se recomienda usar id en arrays de objetos para evitar problemas.

---

💡 Recomendaciones

• 🔄 Mantener la estructura consistente entre archivos JSON de diferentes idiomas.
• 🔑 Asegurarse que los objetos en arrays tengan la propiedad id para que la fusión respete posiciones.
• 🇪🇸 Usar español (es) como idioma fallback base para garantizar que siempre haya texto disponible.

---

🎉 Beneficios

• 🚫 Minimiza errores de traducción incompleta en la UI.
• 🌍 Permite añadir nuevos idiomas sin perder la base en español.
• 🧹 Reduce código repetido y lógica de fallback en componentes.

---