Documentazione del Sistema di Gestione dei Contenuti (CMS) di Intlayer

www.youtube.com

Open embedded page in fullscreen

Il CMS di Intlayer è un'applicazione che ti permette di esternalizzare i contenuti di un progetto Intlayer.

Per questo, Intlayer introduce il concetto di 'dizionari remoti'.

Indice dei contenuti

Comprendere i dizionari remoti

Intlayer distingue tra dizionari 'locali' e 'remoti'.

• Un dizionario 'locale' è un dizionario dichiarato nel tuo progetto Intlayer. Come ad esempio il file di dichiarazione di un pulsante o la tua barra di navigazione. Esternalizzare i contenuti in questo caso non ha senso perché questi contenuti non dovrebbero cambiare spesso.

• Un dizionario 'remoto' è un dizionario gestito tramite il CMS di Intlayer. Potrebbe essere utile per permettere al tuo team di gestire direttamente i contenuti sul tuo sito web, e mira anche a utilizzare funzionalità di A/B testing e ottimizzazione SEO automatica.

Editor visivo vs CMS

L'editor Intlayer Visual è uno strumento che ti permette di gestire i tuoi contenuti in un editor visuale per dizionari locali. Una volta effettuata una modifica, il contenuto verrà sostituito nel codice sorgente. Ciò significa che l'applicazione verrà ricostruita e la pagina ricaricata per mostrare il nuovo contenuto.

Al contrario, il CMS di Intlayer è uno strumento che ti permette di gestire i tuoi contenuti in un editor visuale per dizionari remoti. Una volta effettuata una modifica, il contenuto non influenzerà il codice sorgente. E il sito web mostrerà automaticamente il contenuto modificato.

Integrazione

Per maggiori dettagli su come installare il pacchetto, consulta la sezione pertinente qui sotto:

Integrazione con Next.js

Per l'integrazione con Next.js, consulta la guida all'installazione.

Integrazione con Create React App

Per l'integrazione con Create React App, consulta la guida all'installazione.

Integrazione con Vite + React

Per l'integrazione con Vite + React, consulta la guida all'installazione.

Configurazione

Esegui il seguente comando per accedere all'Intlayer CMS:

npx intlayer login

Questo aprirà il tuo browser predefinito per completare il processo di autenticazione e ricevere le credenziali necessarie (Client ID e Client Secret) per utilizzare i servizi Intlayer.

Nel file di configurazione di Intlayer, puoi personalizzare le impostazioni del CMS:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... altre impostazioni di configurazione
  editor: {
    /**
     * Obbligatorio
     *
     * L'URL dell'applicazione.
     * Questo è l'URL a cui punta l'editor visuale.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Obbligatorio
     *
     * Client ID e client secret sono necessari per abilitare l'editor.
     * Permettono di identificare l'utente che sta modificando il contenuto.
     * Possono essere ottenuti creando un nuovo client nel Dashboard di Intlayer - Progetti (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,

    /**
     * Facoltativo
     *
     * Nel caso in cui stiate ospitando autonomamente l'Intlayer CMS, potete impostare l'URL del CMS.
     *
     * L'URL dell'Intlayer CMS.
     * Di default, è impostato su https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Opzionale
     *
     * Nel caso in cui stiate ospitando autonomamente l'Intlayer CMS, potete impostare l'URL del backend.
     *
     * L'URL dell'Intlayer CMS.
     * Di default, è impostato su https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Se non hai un client ID e un client secret, puoi ottenerli creando un nuovo client nel Intlayer Dashboard - Projects.

Per vedere tutti i parametri disponibili, fai riferimento alla documentazione di configurazione.

Utilizzo del CMS

Invia la tua configurazione

Per configurare l'Intlayer CMS, puoi utilizzare i comandi della intlayer CLI.

npx intlayer config push

Se utilizzi variabili d'ambiente nel file di configurazione intlayer.config.ts, puoi specificare l'ambiente desiderato usando l'argomento --env:

npx intlayer config push --env production

Questo comando carica la tua configurazione sull'Intlayer CMS.

Caricare un dizionario

Per trasformare i tuoi dizionari di localizzazione in un dizionario remoto, puoi utilizzare i comandi della intlayer CLI.

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

Se utilizzi variabili d'ambiente nel file di configurazione intlayer.config.ts, puoi specificare l'ambiente desiderato usando l'argomento --env:

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

Questo comando carica i tuoi dizionari di contenuti iniziali, rendendoli disponibili per il recupero asincrono e la modifica tramite la piattaforma Intlayer.

Modifica il dizionario

Successivamente potrai visualizzare e gestire il tuo dizionario nel Intlayer CMS.

Sincronizzazione live

La Sincronizzazione Live consente alla tua app di riflettere le modifiche ai contenuti del CMS in tempo reale. Non è necessario ricostruire o ridistribuire. Quando abilitata, gli aggiornamenti vengono trasmessi a un server di Sincronizzazione Live che aggiorna i dizionari letti dalla tua applicazione.

Per la guida completa alla configurazione (attivazione, avvio del server Live Sync, flusso di lavoro di sviluppo locale e limitazioni), consulta la documentazione di Live Sync.

Installazione

npm install @intlayer/api

Come funziona: authenticator + endpoints

L'SDK è suddiviso in due import separati di proposito, per mantenere il bundle piccolo:

1. createIntlayerCMS — crea un leggero authenticator. Contiene solo le credenziali e il token di accesso gestito; non conosce nulla di alcun dominio specifico.
2. dictionaryEndpoint, projectEndpoint, … — endpoint binder per dominio, ognuno importato dal suo sottopercorso (@intlayer/api/dictionary, @intlayer/api/project, …). Passi l'authenticator all'endpoint di cui hai bisogno.

Poiché ogni endpoint è importato separatamente, il tuo bundle include solo i domini che effettivamente utilizzi — importare dictionaryEndpoint non porta mai con sé il client del progetto, dell'AI o di alcun altro dominio.

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

// La configurazione è opzionale: quando omessa, le credenziali vengono lette da
// `@intlayer/config/built`, che risolve le variabili di ambiente
// INTLAYER_CLIENT_ID e INTLAYER_CLIENT_SECRET.
export const cmsAuthenticator = createIntlayerCMS();

WARNING

Le credenziali CMS (clientId / clientSecret) concedono accesso in scrittura ai tuoi contenuti. Crea sempre l'authenticator sul lato server (server actions, route handlers, script, CI). Non importarlo mai nel codice lato client o esporre le tue credenziali al browser.

Se preferisci non fare affidamento sulla configurazione al momento della build, passa le credenziali esplicitamente:

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

export const cmsAuthenticator = createIntlayerCMS({
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
    // Opzionale, per backend self-hosted:
    // backendURL: process.env.INTLAYER_BACKEND_URL,
  },
});

Ottieni le tue credenziali creando una nuova chiave di accesso in Intlayer Dashboard - Projects.

Connettere il tuo progetto a un'istanza self-hosted

import type { IntlayerConfig } from "intlayer";

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

    /**
     * URL del dashboard CMS self-hosted.
     * Predefinito: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // es. http://localhost:3000

    /**
     * URL dell'API backend self-hosted.
     * Predefinito: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // es. http://localhost:3100
  },
};

export default config;

SDK @intlayer/api: puntare a un backend self-hosted

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();

Funzionalità opzionali

Queste funzionalità richiedono account esterni e funzionano correttamente anche quando le loro chiavi sono assenti dal .env self-hosted:

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

const cmsAuthenticator = createIntlayerCMS();

// Creare un nuovo dizionario
await dictionaryEndpoint(cmsAuthenticator).addDictionary({
  key: "my-first-dictionary-key",
  content: { title: "Hello world" },
});

// Upsert un batch di dizionari (creali o aggiornali in una sola chiamata)
await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([
  { key: "home", content: { title: "Home" } },
  { key: "about", content: { title: "About" } },
]);

// Aggiornare un dizionario esistente
await dictionaryEndpoint(cmsAuthenticator).updateDictionary({
  id: "<dictionary-id>",
  key: "home",
  content: { title: "Updated title" },
});

Persistenza dei dati e aggiornamenti

Porte esposte sull'host:

Live sync

Live Sync consente all'app di riflettere i cambiamenti del contenuto CMS in fase di runtime — nessuna ricostruzione o ridistribuzione richiesta. Quando abilitato, gli aggiornamenti vengono trasmessi a un server Live Sync che aggiorna i dizionari letti dall'applicazione.

Per la guida di configurazione completa (configurazione, avvio del server Live Sync, workflow di sviluppo locale e vincoli), consulta la documentazione Live Sync.

Self-Hosting

Intlayer può funzionare interamente sulla tua infrastruttura. Un singolo comando inizializza l'intero stack (dashboard, API, database, object storage, e email) con Docker Compose:

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

Per la guida di configurazione completa, il riferimento delle variabili di ambiente, le istruzioni di aggiornamento e le procedure di backup/restore, consulta la Guida Self-Hosting.

Debug

Se riscontri problemi con il CMS, verifica quanto segue:

• L'applicazione è in esecuzione.

• La configurazione dell'editor è correttamente impostata nel file di configurazione di Intlayer.
  • Campi obbligatori:
• L'URL dell'applicazione deve corrispondere a quello impostato nella configurazione dell'editor (applicationURL).

• L'URL del CMS

• Assicurati che la configurazione del progetto sia stata inviata al CMS di Intlayer.

• L'editor visivo utilizza un iframe per visualizzare il tuo sito web. Assicurati che la Content Security Policy (CSP) del tuo sito consenta l'URL del CMS come frame-ancestors ('https://app.intlayer.org' per impostazione predefinita). Controlla la console dell'editor per eventuali errori.

Domande frequenti