Documentación del Sistema de Gestión de Contenidos (CMS) de Intlayer

El CMS de Intlayer es una aplicación que te permite externalizar el contenido de un proyecto Intlayer.

Para ello, Intlayer introduce el concepto de 'diccionarios distantes'.

Entendiendo los diccionarios distantes

Intlayer diferencia entre diccionarios 'locales' y 'distantes'.

• Un diccionario 'local' es un diccionario que se declara en tu proyecto Intlayer. Como el archivo de declaración de un botón, o tu barra de navegación. Externalizar tu contenido no tiene sentido en este caso porque se supone que este contenido no debe cambiar con frecuencia.

• Un diccionario 'distante' es un diccionario que se gestiona a través del CMS de Intlayer. Puede ser útil para permitir que tu equipo gestione el contenido directamente en tu sitio web, y también tiene como objetivo utilizar funciones de pruebas A/B y optimización automática para SEO.

Editor visual vs CMS

El editor Intlayer Visual es una herramienta que te permite gestionar tu contenido en un editor visual para diccionarios locales. Una vez que se realiza un cambio, el contenido será reemplazado en la base de código. Eso significa que la aplicación se reconstruirá y la página se recargará para mostrar el nuevo contenido.

En contraste, el CMS de Intlayer es una herramienta que te permite gestionar tu contenido en un editor visual para diccionarios distantes. Una vez que se realiza un cambio, el contenido no afectará tu base de código. Y el sitio web mostrará automáticamente el contenido modificado.

Integración

Para más detalles sobre cómo instalar el paquete, consulta la sección correspondiente a continuación:

Integración con Next.js

Para la integración con Next.js, consulta la guía de configuración.

Integración con Create React App

Para la integración con Create React App, consulta la guía de configuración.

Integración con Vite + React

Para la integración con Vite + React, consulta la guía de configuración.

Configuración

En tu archivo de configuración de Intlayer, puedes personalizar los ajustes del CMS:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... otras configuraciones  editor: {    /**     * Requerido     *     * La URL de la aplicación.     * Esta es la URL a la que apunta el editor visual.     */    applicationURL: process.env.INTLAYER_APPLICATION_URL,    /**     * Requerido     *     * El ID de cliente y el secreto de cliente son necesarios para habilitar el editor.     * Permiten identificar al usuario que está editando el contenido.     * Se pueden obtener creando un nuevo cliente en el Panel de Intlayer - Proyectos (https://intlayer.org/dashboard/projects).     * clientId: process.env.INTLAYER_CLIENT_ID,     * clientSecret: process.env.INTLAYER_CLIENT_SECRET,     */    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    /**     * Opcional     *     * En caso de que esté alojando el Intlayer CMS por su cuenta, puede configurar la URL del CMS.     *     * La URL del Intlayer CMS.     * Por defecto, está configurada a https://intlayer.org     */    cmsURL: process.env.INTLAYER_CMS_URL,    /**     * Opcional     *     * En caso de que esté alojando el Intlayer CMS por su cuenta, puede configurar la URL del backend.     *     * La URL del Intlayer CMS.     * Por defecto, está configurada a https://back.intlayer.org     */    backendURL: process.env.INTLAYER_BACKEND_URL,  },};export default config;

Si no tienes un ID de cliente y un secreto de cliente, puedes obtenerlos creando un nuevo cliente en el Panel de Intlayer - Proyectos.

Para ver todos los parámetros disponibles, consulta la documentación de configuración.

Uso del CMS

Enviar tu configuración

Para configurar el Intlayer CMS, puedes usar los comandos del intlayer CLI.

npx intlayer config push

Si usas variables de entorno en tu archivo de configuración intlayer.config.ts, puedes especificar el entorno deseado usando el argumento --env:

npx intlayer config push --env production

Este comando sube tu configuración al Intlayer CMS.

Subir un diccionario

Para transformar tus diccionarios de localización en un diccionario remoto, puedes usar los comandos del intlayer CLI.

npx intlayer dictionary push -d my-first-dictionary-key

Si usas variables de entorno en tu archivo de configuración intlayer.config.ts, puedes especificar el entorno deseado usando el argumento --env:

npx intlayer dictionary push -d my-first-dictionary-key --env production

Este comando sube tus diccionarios de contenido inicial, haciéndolos disponibles para su obtención y edición asíncrona a través de la plataforma Intlayer.

Editar el diccionario

Luego podrás ver y gestionar tu diccionario en el Intlayer CMS.

Sincronización en vivo

La sincronización en vivo permite que tu aplicación refleje los cambios de contenido del CMS en tiempo de ejecución. No se requiere reconstrucción ni redepliegue. Cuando está habilitada, las actualizaciones se transmiten a un servidor de sincronización en vivo que actualiza los diccionarios que tu aplicación lee.

Live Sync requiere una conexión continua al servidor y está disponible en el plan enterprise.

Habilita Live Sync actualizando tu configuración de Intlayer:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... otras configuraciones  editor: {    /**     * Habilita la recarga en caliente de las configuraciones de localización cuando se detectan cambios.     * Por ejemplo, cuando se añade o actualiza un diccionario, la aplicación actualiza     * el contenido mostrado en la página.     *     * Debido a que la recarga en caliente requiere una conexión continua al servidor,     * solo está disponible para clientes del plan `enterprise`.     *     * Por defecto: false     */    liveSync: true,  },  build: {    /**     * Controla cómo se importan los diccionarios:     *     * - "live": Los diccionarios se obtienen dinámicamente usando la API de Live Sync.     *   Reemplaza useIntlayer por useDictionaryDynamic.     *     * Nota: El modo live usa la API de Live Sync para obtener los diccionarios. Si la llamada a la API     * falla, los diccionarios se importan dinámicamente.     * Nota: Solo los diccionarios con contenido remoto y la bandera "live" usan el modo live.     * Los demás usan el modo dinámico para mejorar el rendimiento.     */    importMode: "live",  },};export default config;

Inicie el servidor Live Sync para envolver su aplicación:

Ejemplo usando Next.js:

{  "scripts": {    // ... otros scripts    "build": "next build",    "dev": "next dev",    "start": "npx intlayer live --process 'next start'",  },}

Ejemplo usando Vite:

{  "scripts": {    // ... otros scripts    "build": "vite build",    "dev": "vite dev",    "start": "npx intlayer live --process 'vite start'",  },}

El servidor Live Sync envuelve su aplicación y aplica automáticamente el contenido actualizado a medida que llega.

Para recibir notificaciones de cambios desde el CMS, el servidor Live Sync mantiene una conexión SSE con el backend. Cuando el contenido cambia en el CMS, el backend envía la actualización al servidor Live Sync, que escribe los nuevos diccionarios. Su aplicación reflejará la actualización en la siguiente navegación o recarga del navegador, sin necesidad de reconstrucción.

Diagrama de flujo (CMS/Backend -> Servidor Live Sync -> Servidor de Aplicación -> Frontend):

Cómo funciona:

Flujo de trabajo de desarrollo (local)

docs/ko/intlayer_CMS.md

• En desarrollo, todos los diccionarios remotos se obtienen cuando la aplicación se inicia, para que puedas probar actualizaciones rápidamente.
• Para probar Live Sync localmente con Next.js, envuelve tu servidor de desarrollo:

{  "scripts": {    // ... otros scripts    "dev": "npx intlayer live --process 'next dev'",    // "dev": "npx intlayer live --process 'vite dev'", // Para Vite  },}

Habilita la optimización para que Intlayer aplique las transformaciones de importación en vivo durante el desarrollo:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  editor: {    applicationURL: "http://localhost:5173",    liveSyncURL: "http://localhost:4000",    liveSync: true,  },  build: {    optimize: true,    importMode: "live",  },};export default config;

Esta configuración envuelve tu servidor de desarrollo con el servidor Live Sync, obtiene los diccionarios remotos al iniciar y transmite actualizaciones desde el CMS vía SSE. Actualiza la página para ver los cambios.

Notas y restricciones:

• Añade el origen de live sync a la política de seguridad de tu sitio (CSP). Asegúrate de que la URL de live sync esté permitida en connect-src (y en frame-ancestors si es relevante).
• Live Sync no funciona con salida estática. Para Next.js, la página debe ser dinámica para recibir actualizaciones en tiempo de ejecución (por ejemplo, usa generateStaticParams, generateMetadata, getServerSideProps o getStaticProps adecuadamente para evitar restricciones de solo estático).

Esta configuración envuelve tu servidor de desarrollo con el servidor Live Sync, obtiene diccionarios remotos al iniciar y transmite actualizaciones desde el CMS vía SSE. Actualiza la página para ver los cambios.

Notas y restricciones:

• Añade el origen de live sync a la política de seguridad de tu sitio (CSP). Asegúrate de que la URL de live sync esté permitida en connect-src (y en frame-ancestors si es relevante).
• Live Sync no funciona con salida estática. Para Next.js, la página debe ser dinámica para recibir actualizaciones en tiempo de ejecución (por ejemplo, usa generateStaticParams, generateMetadata, getServerSideProps o getStaticProps adecuadamente para evitar restricciones de solo estático).
• La URL de la aplicación debe coincidir con la que configuraste en la configuración del editor (applicationURL).

• La URL del CMS

• Asegúrate de que la configuración del proyecto se haya enviado al CMS de Intlayer.

• El editor visual utiliza un iframe para mostrar tu sitio web. Asegúrate de que la Política de Seguridad de Contenidos (CSP) de tu sitio web permita la URL del CMS como frame-ancestors ('https://intlayer.org' por defecto). Revisa la consola del editor para cualquier error.