Localización de Snippets

Elemental CMS proporciona un sistema flexible para gestionar snippets en múltiples idiomas. Esta guía explica cómo funcionan los snippets con las características de localización y traducción.

Cómo Funcionan los Snippets con Idiomas

A diferencia de las páginas, los snippets en Elemental CMS son agnósticos al idioma por diseño. Esto significa:

Los snippets se comparten entre todos los idiomas
No hay carpetas o archivos específicos por idioma para snippets
La traducción ocurre dentro del contenido del snippet

Sistema de Traducción

Elemental CMS usa Flask-Babel para internacionalización. Los snippets pueden incluir contenido traducible usando los siguientes métodos:

1. Usando Funciones de Traducción

En el contenido HTML de tu snippet, puedes usar funciones de traducción de Flask-Babel:

<div class="welcome-message">
    {{ _("Bienvenido a nuestro sitio web") }}
</div>

<div class="navigation">
    <a href="/">{{ _("Inicio") }}</a>
    <a href="/about">{{ _("Acerca de") }}</a>
    <a href="/contact">{{ _("Contacto") }}</a>
</div>

2. Usando Claves de Traducción

También puedes usar claves de traducción para escenarios más complejos:

<div class="product-card">
    <h3>{{ _("product.title") }}</h3>
    <p>{{ _("product.description") }}</p>
    <button>{{ _("product.add_to_cart") }}</button>
</div>

Contexto de Idioma en Snippets

Cuando los snippets se renderizan, tienen acceso al contexto del idioma actual a través de la especificación de la página:

Accediendo a Información del Idioma

Los snippets pueden acceder a información del idioma a través del contexto page:

<div class="language-specific-content">
    <p>Idioma actual: {{ page.language }}</p>
    <p>Código de idioma: {{ lang_code }}</p>
</div>

Contenido Condicional Basado en Idioma

Puedes renderizar contenido diferente basado en el idioma actual:

{% if page.language == 'es' %}
    <div class="spanish-content">
        <h2>{{ _("Bienvenido") }}</h2>
        <p>{{ _("Contenido en español") }}</p>
    </div>
{% elif page.language == 'en' %}
    <div class="english-content">
        <h2>{{ _("Welcome") }}</h2>
        <p>{{ _("Content in English") }}</p>
    </div>
{% endif %}

Gestión de Archivos de Traducción

Los archivos de traducción se gestionan en el directorio elementalcms/translations/:

Archivos de traducción: Archivos .po que contienen cadenas de traducción
Traducciones compiladas: Archivos .mo para uso en tiempo de ejecución
Carpetas de idioma: Cada idioma tiene su propia carpeta (ej., es/, en/)

Agregando Nuevos Idiomas

Para agregar soporte para un nuevo idioma:

Crea una nueva carpeta de idioma en elementalcms/translations/
Crea subcarpeta LC_MESSAGES/
Agrega archivo messages.po con traducciones
Compila a messages.mo usando Flask-Babel

Mejores Prácticas

1. Usar Claves de Traducción

En lugar de codificar texto directamente, usa claves de traducción para mejor mantenibilidad:

<!-- Bueno -->
<h1>{{ _("page.title") }}</h1>

<!-- Evitar -->
<h1>Bienvenido a nuestro sitio</h1>

2. Mantener Snippets Neutros al Idioma

Diseña snippets que funcionen en todos los idiomas usando funciones de traducción:

<div class="navigation-menu">
    <nav>
        <a href="/">{{ _("nav.home") }}</a>
        <a href="/about">{{ _("nav.about") }}</a>
        <a href="/services">{{ _("nav.services") }}</a>
        <a href="/contact">{{ _("nav.contact") }}</a>
    </nav>
</div>

3. Usar Traducciones con Contexto

Proporciona contexto para que los traductores entiendan el uso:

<!-- En tu snippet -->
<button>{{ _("button.submit") }}</button>

<!-- En messages.po -->
msgid "button.submit"
msgstr "Enviar"

# Contexto: Botón de envío en formularios
msgctxt "form"
msgid "button.submit"
msgstr "Enviar"

Configuración

Configuración relacionada con idiomas en tu configuración:

{
    "cmsCoreContext": {
        "LANGUAGE_MODE": "multi",
        "DEFAULT_LANGUAGE": "es",
        "AVAILABLE_LANGUAGES": ["es", "en", "fr"]
    }
}

Opciones de Modo de Idioma

single: Modo de idioma único (sin soporte de traducción)
multi: Modo multi-idioma con soporte de traducción

Trabajando con Snippets Traducidos

Creando Snippets con Traducciones

Al crear snippets que se usarán en múltiples idiomas:

Crea el snippet usando elemental-cms snippets create
Edita el contenido HTML para incluir funciones de traducción
Agrega cadenas de traducción a tus archivos .po
Compila las traducciones
Prueba en diferentes idiomas

Ejemplo: Snippet de Navegación Multi-idioma

Aquí hay un ejemplo de un snippet de navegación que funciona en múltiples idiomas:

<!-- nav-bar.html -->
<nav class="main-navigation">
    <ul>
        <li><a href="/">{{ _("nav.home") }}</a></li>
        <li><a href="/about">{{ _("nav.about") }}</a></li>
        <li><a href="/services">{{ _("nav.services") }}</a></li>
        <li><a href="/contact">{{ _("nav.contact") }}</a></li>
    </ul>
</nav>

Entradas del archivo de traducción:

# Inglés (messages.po)
msgid "nav.home"
msgstr "Home"

msgid "nav.about"
msgstr "About"

msgid "nav.services"
msgstr "Services"

msgid "nav.contact"
msgstr "Contact"

# Español (messages.po)
msgid "nav.home"
msgstr "Inicio"

msgid "nav.about"
msgstr "Acerca de"

msgid "nav.services"
msgstr "Servicios"

msgid "nav.contact"
msgstr "Contacto"

Probando Traducciones

Para probar tus snippets traducidos:

Cambia el idioma de tu navegador o usa URLs específicas por idioma
Verifica que todas las funciones de traducción se rendericen correctamente
Confirma que el fallback al idioma por defecto funciona
Prueba con diferentes longitudes de contenido (algunos idiomas necesitan más espacio)

Problemas Comunes y Soluciones

Traducciones Faltantes

Si falta una traducción, Flask-Babel mostrará la cadena original. Para arreglar:

Agrega la traducción faltante a tu archivo .po
Compila las traducciones
Reinicia tu aplicación Flask

Traducción No Se Actualiza

Si las traducciones no se están actualizando:

Asegúrate de haber compilado los archivos .po a .mo
Limpia el caché de tu navegador
Reinicia la aplicación Flask
Verifica que el idioma esté correctamente configurado en la sesión

Características Avanzadas

Pluralización

Para contenido que cambia basado en cantidad:

<div class="item-count">
    {{ ngettext('%(num)d elemento', '%(num)d elementos', count) }}
</div>

Formato de Fechas y Números

Usa formato específico por localización:

<div class="date-display">
    {{ moment(date).format('LL') }}
</div>

Este sistema integral de localización te permite crear snippets verdaderamente internacionales que funcionan perfectamente en todos los idiomas soportados en tu instalación de Elemental CMS.