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

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.

Accesso programmatico con l'SDK @intlayer/api

Oltre alla CLI e all'editor visivo, Intlayer fornisce un SDK tipizzato nel pacchetto @intlayer/api. Ti permette di usare il CMS come un database di contenuti headless: puoi recuperare progetti, recuperare dizionari e fare push o aggiornarli direttamente dalla tua applicazione, dai tuoi script o dalla tua pipeline CI.

L'SDK gestisce l'autenticazione per te. Finché il tuo clientId e il tuo clientSecret sono disponibili (nella configurazione di Intlayer o nell'ambiente), ottiene e aggiorna automaticamente un token di accesso OAuth2 e firma ogni richiesta.

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.

Recuperare i progetti

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

const cmsAuthenticator = createIntlayerCMS();

// Elenca i progetti accessibili con le tue credenziali
const { data: projects } =
  await projectEndpoint(cmsAuthenticator).getProjects();

// Leggi gli insight di localizzazione aggregati del progetto selezionato
const { data: insights } =
  await projectEndpoint(cmsAuthenticator).getProjectInsights();

Recuperare i dizionari

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

const cmsAuthenticator = createIntlayerCMS();

// Elenca tutti i dizionari remoti del progetto
const { data: dictionaries } =
  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();

// Oppure ottieni un singolo dizionario tramite la sua chiave
const { data: dictionary } = await dictionaryEndpoint(
  cmsAuthenticator
).getDictionary("my-first-dictionary-key");

Push e aggiornamento dei dizionari

Usa il CMS come database per riscrivere i contenuti:

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

const cmsAuthenticator = createIntlayerCMS();

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

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

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

Suggerimento: riutilizza l'endpoint associato per evitare ripetizioni:

typescript

Copia contenuto

Copiare il codice

Copiare il codice nella clipboard

const dictionary = dictionaryEndpoint(cmsAuthenticator);
await dictionary.pushDictionaries([myDictionary]);
const { data } = await dictionary.getDictionaries();

Estrarre un singolo metodo

Ogni metodo dell'endpoint è già autenticato e autonomo (gestisce il proprio token), quindi puoi estrarne uno e passarlo altrove, ad esempio per iniettarlo come dipendenza:

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

const dictionary = dictionaryEndpoint(createIntlayerCMS());

// Già autenticato, aggiorna automaticamente il token a ogni chiamata
export const pushDictionaries = dictionary.pushDictionaries;

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

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