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

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

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.

Live Sync richiede una connessione continua al server ed è disponibile nel piano enterprise.

Abilita Live Sync aggiornando la configurazione di Intlayer:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... altre impostazioni di configurazione
  editor: {
    /**
     * Abilita il caricamento a caldo delle configurazioni locali quando vengono rilevate modifiche.
     * Ad esempio, quando un dizionario viene aggiunto o aggiornato, l'applicazione aggiorna
     * il contenuto visualizzato nella pagina.
     *
     * Poiché il caricamento a caldo richiede una connessione continua al server, è
     * disponibile solo per i clienti del piano `enterprise`.
     *
     * Predefinito: false
     */
    liveSync: true,
  },
  dictionary: {
    /**
     * Controlla come vengono importati i dizionari:
     *
     * - "live": I dizionari vengono recuperati dinamicamente utilizzando l'API Live Sync.
     *   Sostituisce useIntlayer con useDictionaryDynamic.
     *
     * Nota: La modalità live utilizza l'API Live Sync per recuperare i dizionari. Se la chiamata API
     * fallisce, i dizionari vengono importati dinamicamente.
     * Nota: Solo i dizionari con contenuto remoto e flag "live" utilizzano la modalità live.
     * Gli altri usano la modalità dinamica per le prestazioni.
     */
    importMode: "fetch",
  },
};

export default config;

Avvia il server Live Sync per avvolgere la tua applicazione:

Esempio con Next.js:

{  "scripts": {    // ... altri script    "build": "next build",    "dev": "next dev",    "start": "npx intlayer live --with 'next start'",  },}

Esempio con Vite:

{  "scripts": {    // ... altri script    "build": "vite build",    "dev": "vite dev",    "start": "npx intlayer live --with 'vite start'",  },}

Il server Live Sync avvolge la tua applicazione e applica automaticamente i contenuti aggiornati non appena arrivano.

Per ricevere notifiche di modifica dal CMS, il server Live Sync mantiene una connessione SSE con il backend. Quando il contenuto cambia nel CMS, il backend inoltra l'aggiornamento al server Live Sync, che scrive i nuovi dizionari. La tua applicazione rifletterà l'aggiornamento alla successiva navigazione o al reload del browser, non è necessario ricostruire.

Diagramma di flusso (CMS/Backend -> Server Live Sync -> Server Applicazione -> Frontend):

Come funziona:

Flusso di lavoro di sviluppo (locale)

• In fase di sviluppo, tutti i dizionari remoti vengono recuperati all'avvio dell'applicazione, così puoi testare rapidamente gli aggiornamenti.
• Per testare Live Sync localmente con Next.js, avvolgi il tuo server di sviluppo:

{  "scripts": {    // ... altri script    "dev": "npx intlayer live --with 'next dev'",    // "dev": "npx intlayer live --with 'vite dev'", // Per Vite  },}

Abilita l'ottimizzazione affinché Intlayer applichi le trasformazioni di importazione Live durante lo sviluppo:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    applicationURL: "http://localhost:5173",
    liveSyncURL: "http://localhost:4000",
    liveSync: true,
  },
  dictionary: {
    importMode: "fetch",
  },
  build: {
    optimize: true,
  },
};

export default config;

Questa configurazione avvolge il tuo server di sviluppo con il server Live Sync, recupera i dizionari remoti all'avvio e trasmette aggiornamenti dal CMS tramite SSE. Aggiorna la pagina per vedere le modifiche.

Note e vincoli:

• Aggiungi l'origine del live sync alla tua politica di sicurezza del sito (CSP). Assicurati che l'URL del live sync sia consentito in connect-src (e in frame-ancestors se pertinente).
• Live Sync non funziona con output statico. Per Next.js, la pagina deve essere dinamica per ricevere aggiornamenti in fase di esecuzione (ad esempio, usa generateStaticParams, generateMetadata, getServerSideProps o getStaticProps in modo appropriato per evitare vincoli di solo statico completo).
• Nel CMS, ogni dizionario ha un flag live. Solo i dizionari con live=true vengono recuperati tramite l'API di live sync; gli altri vengono importati dinamicamente e rimangono invariati a runtime.
• Il flag live viene valutato per ogni dizionario al momento della build. Se il contenuto remoto non era contrassegnato come live=true durante la build, è necessario ricostruire per abilitare Live Sync per quel dizionario.
• Il server di live sync deve poter scrivere nella cartella .intlayer. Nei container, assicurarsi che sia garantito l'accesso in scrittura a /.intlayer.

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.