Documentation du Système de Gestion de Contenu (CMS) Intlayer

Le CMS Intlayer est une application qui vous permet d'externaliser le contenu d'un projet Intlayer.

Pour cela, Intlayer introduit le concept de « dictionnaires distants ».

Table of Contents

Comprendre les dictionnaires distants

Intlayer fait une distinction entre les dictionnaires « locaux » et « distants ».

• Un dictionnaire « local » est un dictionnaire déclaré dans votre projet Intlayer. Par exemple, le fichier de déclaration d’un bouton ou votre barre de navigation. Externaliser votre contenu n’a pas de sens dans ce cas, car ce contenu n’est pas censé changer fréquemment.

• Un dictionnaire « distant » est un dictionnaire géré via le CMS Intlayer. Cela peut être utile pour permettre à votre équipe de gérer directement votre contenu sur votre site web, et vise également à utiliser des fonctionnalités de tests A/B et d’optimisation automatique SEO.

Éditeur visuel vs CMS

L’éditeur Intlayer Visual est un outil qui vous permet de gérer votre contenu dans un éditeur visuel pour les dictionnaires locaux. Une fois qu’une modification est effectuée, le contenu sera remplacé dans la base de code. Cela signifie que l’application sera reconstruite et que la page sera rechargée pour afficher le nouveau contenu.

En revanche, le CMS Intlayer est un outil qui vous permet de gérer votre contenu dans un éditeur visuel pour les dictionnaires distants. Une fois qu’une modification est effectuée, le contenu n’impactera pas votre base de code. Et le site web affichera automatiquement le contenu modifié.

Intégration

Pour plus de détails sur la façon d’installer le package, consultez la section correspondante ci-dessous :

Intégration avec Next.js

Pour l’intégration avec Next.js, référez-vous au guide d’installation.

Intégration avec Create React App

Pour l’intégration avec Create React App, référez-vous au guide d’installation.

Intégration avec Vite + React

Pour l’intégration avec Vite + React, référez-vous au guide d’installation.

Configuration

Exécutez la commande suivante pour vous connecter à l'Intlayer CMS :

npx intlayer login

Cela ouvrira votre navigateur par défaut pour compléter le processus d'authentification et recevoir les identifiants nécessaires (Client ID et Client Secret) pour utiliser les services Intlayer.

Dans votre fichier de configuration Intlayer, vous pouvez personnaliser les paramètres du CMS :

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... autres paramètres de configuration
  editor: {
    /**
     * Obligatoire
     *
     * L'URL de l'application.
     * C'est l'URL ciblée par l'éditeur visuel.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Obligatoire
     *
     * L'ID client et le secret client sont nécessaires pour activer l'éditeur.
     * Ils permettent d'identifier l'utilisateur qui édite le contenu.
     * Ils peuvent être obtenus en créant un nouveau client dans le tableau de bord Intlayer - Projets (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,

    /**
     * Optionnel
     *
     * Dans le cas où vous hébergez vous-même le CMS Intlayer, vous pouvez définir l'URL du CMS.
     *
     * L'URL du CMS Intlayer.
     * Par défaut, elle est définie sur https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Optionnel
     *
     * Dans le cas où vous hébergez vous-même le CMS Intlayer, vous pouvez définir l'URL du backend.
     *
     * L'URL du backend Intlayer.
     * Par défaut, elle est définie sur https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Si vous ne disposez pas d'un ID client et d'un secret client, vous pouvez les obtenir en créant un nouveau client dans le Tableau de bord Intlayer - Projets.

Pour voir tous les paramètres disponibles, référez-vous à la documentation de configuration.

Utilisation du CMS

Poussez votre configuration

Pour configurer le CMS Intlayer, vous pouvez utiliser les commandes du intlayer CLI.

npx intlayer config push

Si vous utilisez des variables d'environnement dans votre fichier de configuration intlayer.config.ts, vous pouvez spécifier l'environnement souhaité en utilisant l'argument --env :

npx intlayer config push --env production

Cette commande téléverse votre configuration vers le CMS Intlayer.

Pousser un dictionnaire

Pour transformer vos dictionnaires de locale en un dictionnaire distant, vous pouvez utiliser les commandes du intlayer CLI.

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

Si vous utilisez des variables d'environnement dans votre fichier de configuration intlayer.config.ts, vous pouvez spécifier l'environnement souhaité en utilisant l'argument --env :

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

Cette commande télécharge vos dictionnaires de contenu initiaux, les rendant disponibles pour une récupération et une édition asynchrones via la plateforme Intlayer.

Modifier le dictionnaire

Vous pourrez alors voir et gérer votre dictionnaire dans le CMS Intlayer.

Synchronisation en direct

La synchronisation en direct permet à votre application de refléter les modifications du contenu CMS en temps réel. Aucune reconstruction ou redéploiement n'est nécessaire. Lorsqu'elle est activée, les mises à jour sont diffusées vers un serveur de synchronisation en direct qui actualise les dictionnaires que votre application utilise.

Pour le guide de configuration complet (activation, démarrage du serveur Live Sync, flux de travail en développement local et contraintes), consultez la documentation Live Sync.

Installation

npm install @intlayer/api

Fonctionnement : authenticator + endpoints

Le SDK est divisé en deux imports distincts à dessein, pour maintenir la taille de votre bundle réduite :

1. createIntlayerCMS — crée un authenticator léger. Il ne transporte que les credentials et le token d'accès géré ; il ne connaît rien sur aucun domaine spécifique.
2. dictionaryEndpoint, projectEndpoint, … — des endpoint binders par domaine, chacun importé depuis son propre chemin (@intlayer/api/dictionary, @intlayer/api/project, …). Vous passez l'authenticator à l'endpoint dont vous avez besoin.

Parce que chaque endpoint est importé séparément, votre bundle inclut uniquement les domaines que vous utilisez réellement — importer dictionaryEndpoint ne tire jamais le client du projet, de l'IA ou d'un autre domaine.

import { createIntlayerCMS } from "@intlayer/api";// La configuration est optionnelle : lorsqu'elle est omise, les credentials sont lus depuis// `@intlayer/config/built`, qui résout les variables d'environnement INTLAYER_CLIENT_ID et// INTLAYER_CLIENT_SECRET.export const cmsAuthenticator = createIntlayerCMS();

WARNING

Les credentials du CMS (clientId / clientSecret) accordent un accès en écriture à votre contenu. Ne créez l'authenticator que du côté serveur (server actions, route handlers, scripts, CI). Ne l'importez jamais dans du code côté client ni n'exposez vos credentials au navigateur.

Si vous préférez ne pas vous fier à la configuration au moment de la construction, passez les credentials explicitement :

import { createIntlayerCMS } from "@intlayer/api";export const cmsAuthenticator = createIntlayerCMS({  editor: {    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    // Optionnel, pour les backends auto-hébergés :    // backendURL: process.env.INTLAYER_BACKEND_URL,  },});

Obtenez vos credentials en créant une nouvelle clé d'accès dans le Tableau de bord Intlayer - Projets.

Connecter votre projet à une instance auto-hébergée

Pointez votre configuration Intlayer vers votre propre backend et tableau de bord au lieu de intlayer.org :

import type { IntlayerConfig } from "intlayer";

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

    /**
     * URL du tableau de bord CMS auto-hébergé.
     * Par défaut : https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // ex. http://localhost:3000

    /**
     * URL de l'API backend auto-hébergée.
     * Par défaut : https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // ex. http://localhost:3100
  },
};

export default config;

Définissez les variables d'environnement correspondantes dans votre projet :

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

Créez des identifiants d'accès dans votre tableau de bord auto-hébergé à http://localhost:3000/projects.

SDK @intlayer/api : pointer vers un backend auto-hébergé

Lors de l'utilisation du SDK de manière programmatique, passez backendURL explicitement à createIntlayerCMS :

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

Fonctionnalités optionnelles

Ces fonctionnalités nécessitent des comptes externes et fonctionnent normalement même sans leurs clés dans le fichier .env auto-hébergé :

Persistance des données et mises à niveau

Trois volumes Docker contiennent tout l'état persistant : mongo-data, redis-data et minio-data. Ils survivent aux redémarrages et aux mises à niveau des conteneurs. Relancer le programme d'installation télécharge les dernières images et effectue un docker compose up -d progressif.

Ports exposés sur l'hôte :

Pour une référence complète de toutes les variables d'environnement disponibles et des options avancées (proxy inverse, domaines personnalisés, sauvegarde/restauration), consultez le Guide d'auto-hébergement.

Synchronisation en direct

La Synchronisation en direct permet à votre application de refléter les changements de contenu CMS à l'exécution — aucune reconstruction ou redéploiement requis. Lorsqu'elle est activée, les mises à jour sont diffusées vers un serveur Live Sync qui actualise les dictionnaires que votre application lit.

Pour le guide de configuration complet (configuration, démarrage du serveur Live Sync, le flux de travail de développement local et les contraintes), consultez la documentation Live Sync.

Auto-hébergement

Intlayer peut s'exécuter entièrement sur votre propre infrastructure. Une seule commande bootstrap la pile complète (dashboard, API, base de données, stockage d'objets et email) avec Docker Compose :

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

Pour le guide de configuration complet, la référence des variables d'environnement, les instructions de mise à jour et les procédures de sauvegarde/restauration, consultez le Guide d'auto-hébergement.

Débogage

Si vous rencontrez des problèmes avec le CMS, vérifiez les points suivants :

• L'application est en cours d'exécution.

• La configuration de editor est correctement définie dans votre fichier de configuration Intlayer.
  • Champs requis :
• L'URL de l'application doit correspondre à celle que vous avez définie dans la configuration de l'éditeur (applicationURL).

• L'URL du CMS

• Assurez-vous que la configuration du projet a été poussée vers le CMS Intlayer.

• L'éditeur visuel utilise un iframe pour afficher votre site web. Assurez-vous que la politique de sécurité du contenu (Content Security Policy, CSP) de votre site autorise l'URL du CMS en tant que frame-ancestors ('https://app.intlayer.org' par défaut). Vérifiez la console de l'éditeur pour toute erreur.