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

www.youtube.com

Open embedded page in fullscreen

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'.

Tabla de Contenidos

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

Ejecuta el siguiente comando para iniciar sesión en el Intlayer CMS:

npx intlayer login

Esto abrirá tu navegador predeterminado para completar el proceso de autenticación y recibir las credenciales necesarias (Client ID y Client Secret) para usar los servicios de Intlayer.

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://app.intlayer.org/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 runtime. 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.

Para la guía de configuración completa (activación, inicio del servidor Live Sync, flujo de trabajo de desarrollo local y restricciones), consulta la documentación de Live Sync.

Servicios iniciados

npm install @intlayer/api

Chromium (para la generación de capturas de pantalla con Puppeteer) está incluido en la imagen del backend — no se necesita ningún contenedor adicional.

Conectar tu proyecto a una instancia auto-alojada

Apunta tu configuración de Intlayer a tu propio backend y panel de control en lugar de intlayer.org:

1. createIntlayerCMS — crea un autenticador ligero. Solo lleva las credenciales y el token de acceso gestionado; no sabe nada sobre ningún dominio específico.
2. dictionaryEndpoint, projectEndpoint, … — vinculadores de endpoint por dominio, cada uno importado desde su propia ruta (@intlayer/api/dictionary, @intlayer/api/project, …). Pasas el autenticador al endpoint que necesitas.

Debido a que cada endpoint se importa por separado, tu bundle incluye solo los dominios que realmente usas — importar dictionaryEndpoint nunca incluye el proyecto, AI, u ningún otro cliente de dominio.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,

    /**
     * URL del panel de control CMS auto-alojado.
     * Por defecto: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // ej. http://localhost:3000

    /**
     * URL de la API backend auto-alojada.
     * Por defecto: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // ej. http://localhost:3100
  },
};

export default config;

WARNING

Las credenciales del CMS (clientId / clientSecret) otorgan acceso de escritura a tu contenido. Solo crea el autenticador en el lado del servidor (server actions, route handlers, scripts, CI). Nunca las importes en código del lado del cliente ni expongas tus credenciales al navegador.

Establece las variables de entorno correspondientes en tu proyecto:

INTLAYER_CMS_URL=http://localhost:3000
INTLAYER_BACKEND_URL=http://localhost:3100
INTLAYER_CLIENT_ID=<your-client-id>
INTLAYER_CLIENT_SECRET=<your-client-secret>

Crea credenciales de acceso en tu panel de control auto-alojado en http://localhost:3000/projects.

SDK @intlayer/api: apuntar a un backend auto-alojado

import { createIntlayerCMS } from "@intlayer/api";
import { dictionaryEndpoint } from "@intlayer/api/dictionary";

const cms = createIntlayerCMS({
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
  },
});

const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();

Características opcionales

Persistencia de datos y actualizaciones

Puertos expuestos en el host:

Para una referencia completa de todas las variables de entorno disponibles y opciones avanzadas (proxy inverso, dominios personalizados, respaldo/restauración), consulta la Guía de Auto-alojamiento.

Extrayendo un método único

Cada método de endpoint ya está autenticado y es independiente (maneja su propio token), por lo que puedes extraer uno y pasarlo — por ejemplo para inyectarlo como una dependencia:

import { createIntlayerCMS } from "@intlayer/api";
import { dictionaryEndpoint } from "@intlayer/api/dictionary";

const dictionary = dictionaryEndpoint(createIntlayerCMS());

// Ya autenticado — refresca el token automáticamente en cada llamada
export const pushDictionaries = dictionary.pushDictionaries;

// Uso
await pushDictionaries([{ key: "home", content: { title: "Home" } }]);

Live sync

Live Sync permite que tu aplicación refleje los cambios de contenido del CMS en tiempo de ejecución — sin necesidad de reconstruir o redeplegar. Cuando está habilitado, las actualizaciones se transmiten a un servidor Live Sync que actualiza los diccionarios que tu aplicación lee.

Para la guía de configuración completa (configuración, iniciar el servidor Live Sync, el flujo de trabajo de desarrollo local y limitaciones), consulta la documentación de Live Sync.

Auto-hospedaje

Intlayer puede ejecutarse completamente en tu propia infraestructura. Una sola línea arranca el stack completo (dashboard, API, base de datos, almacenamiento de objetos y correo electrónico) con Docker Compose:

curl -fsSL https://intlayer.org/install.sh | sh

Para la guía de configuración completa, referencia de variables de entorno, instrucciones de actualización y procedimientos de copia de seguridad/restauración, consulta la Guía de Auto-hospedaje.

Depuración

Si encuentras problemas con el CMS, verifica lo siguiente:

• La aplicación está en ejecución.

• La configuración de editor está correctamente establecida en tu archivo de configuración de Intlayer.

  • Campos requeridos:
    • La URL de la aplicación debe coincidir con la que estableciste 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://app.intlayer.org' por defecto). Verifica la consola del editor para cualquier error.

Preguntas frecuentes