Saltar al contenido principal

Introducción

🎯 ¿Qué hace este módulo?​

El módulo Locales te permite gestionar el soporte multilingüe en tu proyecto OneEntry: recuperar los idiomas disponibles, detectar la configuración regional del usuario y construir aplicaciones internacionalizadas que sirvan contenido en múltiples idiomas.

Piénsalo como tu gestor de idiomas: en lugar de codificar los idiomas en tu aplicación, obtienes la lista de idiomas activos de OneEntry de forma dinámica, permitiendo que tu contenido se adapte automáticamente a diferentes configuraciones regionales (inglés, ruso, árabe, español, etc.).

📖 Explicación Simple​

En aplicaciones modernas, a menudo necesitas soportar múltiples idiomas:

  • 🌍 Sitios de comercio electrónico: atender a clientes en diferentes países (inglés, francés, alemán)
  • 📱 Aplicaciones móviles: adaptar la interfaz de usuario al idioma del dispositivo del usuario
  • 🌐 Sitios web: mostrar contenido en el idioma preferido del visitante
  • 📚 Documentación: proporcionar ayuda en múltiples idiomas
  • 🎮 Juegos: traducir la interfaz y el contenido

El problema de codificar los idiomas:

Problemas:

  • 🔄 Difícil de actualizar: necesitas volver a implementar para agregar nuevos idiomas
  • 🌍 No sincronizados: los idiomas de la aplicación pueden diferir de los idiomas del CMS
  • ❌ Desajustes de traducción: el contenido existe en el CMS pero no en la aplicación
  • 🔧 Mantenimiento manual: actualizar el código cada vez que cambian los idiomas

La solución de Locales:

Beneficios:

  • 🔄 Siempre sincronizados: los idiomas coinciden con lo que está configurado en OneEntry
  • 🌍 Dinámico: agregar/quitar idiomas sin cambios en el código
  • ✅ Validado: solo mostrar idiomas que tienen contenido
  • 🎯 Centralizado: gestionar idiomas en un solo lugar

✨ Conceptos Clave​

¿Qué es un Locale?​

Un locale es una combinación de idioma y región que determina cómo se muestra el contenido:

  • Código de idioma: código de idioma ISO 639-1 (por ejemplo, en, ru, ar)
  • Código de región: código de país ISO 3166-1 (por ejemplo, US, GB, RU)
  • Identificador de locale: formato combinado: idioma_REGIÓN (por ejemplo, en_US, ru_RU, ar_SA)

Ejemplos:

Código de LocaleIdiomaRegiónDescripción
en_USInglésEstados UnidosInglés Americano
en_GBInglésGran BretañaInglés Británico
ru_RURusoRusiaRuso
es_ESEspañolEspañaEspañol Europeo
es_MXEspañolMéxicoEspañol Mexicano
ar_SAÁrabeArabia SauditaÁrabe (Arabia Saudita)
fr_FRFrancésFranciaFrancés
de_DEAlemánAlemaniaAlemán

Estructura de Locale​

Cada locale en OneEntry tiene:

{
  id: 146,                      // ID único
  shortCode: 'en',              // código corto
  code: 'en_US',                // código completo
  name: 'English (USA)',        // nombre
  nativeName: 'English (USA)',  // nombre nativo
  isActive: true,               // está activo
  image: null,                  // imagen
  position: 1,                  // posición
}

¿Por qué usar el módulo Locales?​

BeneficioDescripción
Soporte multilingüeServir contenido en el idioma preferido del usuario
Lista de idiomas dinámicaLos idiomas se sincronizan con la configuración de OneEntry
Detección de locale por defectoIdentificar automáticamente el idioma por defecto
Filtrado de locales activosMostrar solo idiomas habilitados
Gestión centralizadaActualizar idiomas en el panel de administración, no en el código
Experiencia del usuarioPermitir a los usuarios elegir su idioma

Casos de Uso Comunes​

Caso de UsoDescripciónEjemplo
Selector de IdiomaMenú desplegable para cambiar de idiomaEncabezado del sitio web con banderas de idioma
Localización de ContenidoObtener contenido en el idioma del usuarioPublicaciones de blog en inglés o ruso
EnrutamientoEstructura de URL por idioma/en/about, /ru/about
Lógica de ReemplazoMostrar idioma por defecto si falta traducciónMostrar inglés si el español no está disponible
Preferencias del UsuarioRecordar la elección de idioma del usuarioGuardar locale en cookies/localStorage

📋 Lo Que Necesitas Saber​

Los Locales se Configuran en el Panel de Administración​

No puedes crear locales a través del SDK: se configuran en el panel de administración de OneEntry:

Panel de Administración de OneEntry → Configuración → Idiomas → Agregar Idioma → Seleccionar Locale

El SDK es para obtener información de locales, no para crear locales.

Locales Activos vs. Inactivos​

No todos los locales configurados pueden estar activos:

EstadoSignificadoCuándo Usar
Activo (isActive: true)Locale está habilitado y tiene contenidoMostrar en selector de idioma
Inactivo (isActive: false)Locale está deshabilitado o en preparaciónOcultar de los usuarios

Mejor práctica: Siempre filtrar por isActive al construir selectores de idioma.

Locale por Defecto​

Cada proyecto de OneEntry tiene un locale por defecto:

  • Locale por defecto (isDefault: true) - El idioma principal
  • Se utiliza cuando no se especifica ningún locale
  • Reemplazo cuando falta la traducción

Código de Locale vs. Código Corto​

Cada locale tiene dos formatos de código:

CampoFormatoEjemploUsar Para
codeidioma_REGIÓNen_US, ru_RUIdentificación completa del locale
shortCodeidiomaen, ruIdentificación solo del idioma

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getLocales()Obtener todos los locales (activos e inactivos)Obtener idiomas disponibles

❓ Preguntas Frecuentes (FAQ)​

¿Cómo agrego nuevos idiomas a mi proyecto?​

No puedes agregar locales a través del SDK. Los locales se configuran en el panel de administración de OneEntry.

¿Cómo establezco el idioma por defecto?​

No puedes establecer el locale por defecto a través del SDK. El locale por defecto se configura en el panel de administración de OneEntry:

Nota: Solo un locale puede ser por defecto a la vez.

¿Debo mostrar locales inactivos a los usuarios?​

¡No! Siempre filtra por isActive:

¿Por qué? Los locales inactivos pueden:

  • Estar en desarrollo (contenido no listo)
  • Estar temporalmente deshabilitados
  • No tener traducciones para todo el contenido

¿Cómo manejo las traducciones faltantes?​

Usa lógica de reemplazo.

¿Puedo almacenar en caché los locales?​

¡Sí! Los locales rara vez cambian, por lo que se recomienda el almacenamiento en caché.

¿Puedo usar Locales con Next.js i18n?​

¡Sí! Integra los locales de OneEntry con Next.js.

¿Cómo agrupo locales por idioma?​

Agrupa variantes del mismo idioma.

¿Qué pasa si necesito traducir elementos de la interfaz de usuario (no contenido del CMS)?​

El módulo Locales de OneEntry es solo para locales de contenido del CMS. Para la traducción de la interfaz de usuario:

Opción 1: Usa una biblioteca i18n (react-i18next, next-i18next)

Opción 2: Almacena traducciones de la interfaz de usuario en OneEntry

Crea un tipo de página "traducciones" y obtén cadenas de traducción.

💡 Notas Importantes​

Los Locales son de Solo Lectura​

El módulo Locales es de solo lectura:

  • ✅ Obtener locales
  • ✅ Filtrar por estado activo
  • ✅ Encontrar locale por defecto
  • ❌ No se pueden crear locales
  • ❌ No se pueden actualizar locales
  • ❌ No se pueden eliminar locales

Para modificar: Usa el panel de administración de OneEntry.

Siempre Filtra Locales Activos​

Solo muestra locales activos a los usuarios.

¿Por qué? Los locales inactivos pueden no tener traducciones completas.

Se Recomienda el Almacenamiento en Caché​

Los locales rara vez cambian: implementa almacenamiento en caché.

Sincroniza con Locales de Contenido​

Asegúrate de que los idiomas de la interfaz coincidan con el contenido disponible.

🎓 Mejores Prácticas​

  • Siempre filtra locales activos: muestra solo idiomas habilitados.
  • Almacena en caché los locales: rara vez cambian, almacena en caché para mejorar el rendimiento.
  • Usa el locale por defecto como reemplazo: maneja traducciones faltantes.
  • Guarda la preferencia del usuario: recuerda la elección de idioma.
  • Valida los códigos de locale: verifica que el locale exista antes de usarlo.
  • Detecta el idioma del navegador: selecciona automáticamente el idioma del usuario.
  • Agrupa por idioma: muestra variantes de idioma de manera lógica.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/languages

Definición del módulo Locales​

El módulo 'Locales' habilita el soporte multilingüe en OneEntry.

Gracias al soporte de múltiples idiomas en la Plataforma OneEntry, puedes personalizar de manera flexible la interfaz de tu panel y gestionar cómodamente los idiomas en tu proyecto. En esta sección, puedes aprender sobre los principios de trabajo con idiomas.


const { Locales } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Documentación Relacionada​