Документация по системе управления контентом Intlayer (CMS)

Intlayer CMS, это приложение, которое позволяет вам вынести контент проекта Intlayer во внешнее управление.

Для этого Intlayer вводит концепцию «удалённых словарей».

Понимание удалённых словарей

Intlayer различает «локальные» и «удалённые» словари.

• «Локальный» словарь, это словарь, который объявлен в вашем проекте Intlayer. Например, файл объявления кнопки или ваша навигационная панель. Вынесение такого контента во внешнее управление не имеет смысла, так как этот контент не предполагается часто менять.

• «Удалённый» словарь, это словарь, который управляется через Intlayer CMS. Это может быть полезно, чтобы ваша команда могла управлять контентом непосредственно на вашем сайте, а также для использования функций A/B тестирования и автоматической SEO-оптимизации.

Визуальный редактор против CMS

Редактор Intlayer Visual, это инструмент, который позволяет управлять вашим контентом в визуальном редакторе для локальных словарей. После внесения изменений контент будет заменён в кодовой базе. Это означает, что приложение будет пересобрано, и страница перезагрузится для отображения нового контента.

В отличие от этого, Intlayer CMS, это инструмент, который позволяет управлять вашим контентом в визуальном редакторе для удалённых словарей. После внесения изменений контент не повлияет на вашу кодовую базу. И сайт автоматически отобразит изменённый контент.

Интеграция

Для получения более подробной информации о том, как установить пакет, смотрите соответствующий раздел ниже:

Интеграция с Next.js

Для интеграции с Next.js обратитесь к руководству по настройке.

Интеграция с Create React App

Для интеграции с Create React App обратитесь к руководству по настройке.

Интеграция с Vite + React

Для интеграции с Vite + React обратитесь к руководству по настройке.

Конфигурация

Выполните следующую команду для входа в Intlayer CMS:

npx intlayer login

Это откроет ваш браузер по умолчанию для завершения процесса аутентификации и получения необходимых учетных данных (Client ID и Client Secret) для использования сервисов Intlayer.

В вашем конфигурационном файле Intlayer вы можете настроить параметры CMS:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... другие настройки конфигурации
  editor: {
    /**
     * Обязательно
     *
     * URL приложения.
     * Это URL, на который нацелен визуальный редактор.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Обязательно
     *
     * Для включения редактора требуются client ID и client secret.
     * Они позволяют идентифицировать пользователя, который редактирует контент.
     * Их можно получить, создав нового клиента в Intlayer Dashboard - Projects (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,

    /**
     * Необязательно
     *
     * В случае самостоятельного размещения Intlayer CMS, вы можете указать URL CMS.
     *
     * URL Intlayer CMS.
     * По умолчанию установлен https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Необязательно
     *
     * В случае самостоятельного размещения Intlayer CMS, вы можете указать URL бэкенда.
     *
     * URL Intlayer CMS.
     * По умолчанию установлен https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Если у вас нет client ID и client secret, вы можете получить их, создав нового клиента в Intlayer Dashboard - Projects.

Чтобы увидеть все доступные параметры, обратитесь к документации по конфигурации.

Использование CMS

Отправка вашей конфигурации

Для настройки Intlayer CMS вы можете использовать команды intlayer CLI.

npx intlayer config push

Если вы используете переменные окружения в вашем файле конфигурации intlayer.config.ts, вы можете указать нужное окружение с помощью аргумента --env:

npx intlayer config push --env production

Эта команда загружает вашу конфигурацию в Intlayer CMS.

Отправка словаря

Чтобы преобразовать ваши локальные словари в удалённый словарь, вы можете использовать команды intlayer CLI.

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

Если вы используете переменные окружения в вашем файле конфигурации intlayer.config.ts, вы можете указать нужное окружение с помощью аргумента --env:

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

Эта команда загружает ваши исходные словари контента, делая их доступными для асинхронного получения и редактирования через платформу Intlayer.

Редактирование словаря

После этого вы сможете просматривать и управлять вашим словарём в Intlayer CMS.

Живая синхронизация

Живая синхронизация позволяет вашему приложению отражать изменения контента CMS в режиме реального времени. Пересборка или повторный деплой не требуются. Когда функция включена, обновления передаются на сервер живой синхронизации, который обновляет словари, используемые вашим приложением.

Живая синхронизация требует постоянного подключения к серверу и доступна в тарифном плане enterprise.

Включите живую синхронизацию, обновив конфигурацию Intlayer:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... другие настройки конфигурации
  editor: {
    /**
     * Включает горячую перезагрузку конфигураций локалей при обнаружении изменений.
     * Например, когда словарь добавляется или обновляется, приложение обновляет
     * отображаемый на странице контент.
     *
     * Поскольку горячая перезагрузка требует постоянного подключения к серверу,
     * она доступна только для клиентов с тарифным планом `enterprise`.
     *
     * По умолчанию: false
     */
    liveSync: true,
  },
  dictionary: {
    /**
     * Управляет способом импорта словарей:
     *
     * - "live": словари загружаются динамически с использованием Live Sync API.
     *   Заменяет useIntlayer на useDictionaryDynamic.
     *
     * Примечание: Режим live использует Live Sync API для загрузки словарей. Если вызов API
     * не удаётся, словари загружаются динамически.
     * Примечание: Режим live используется только для словарей с удалённым содержимым и флагом "live".
     * Другие используют динамический режим для повышения производительности.
     */
    importMode: "fetch",
  },
};

export default config;

Запустите сервер Live Sync, чтобы обернуть ваше приложение:

Пример с использованием Next.js:

{  "scripts": {    // ... другие скрипты    "build": "next build",    "dev": "next dev",    "start": "npx intlayer live --with 'next start'",  },}

Пример с использованием Vite:

{  "scripts": {    // ... другие скрипты    "build": "vite build",    "dev": "vite dev",    "start": "npx intlayer live --with 'vite start'",  },}

Сервер Live Sync оборачивает ваше приложение и автоматически применяет обновлённый контент по мере его поступления.

Чтобы получать уведомления об изменениях из CMS, сервер Live Sync поддерживает SSE-соединение с бэкендом. Когда контент в CMS изменяется, бэкенд пересылает обновление серверу Live Sync, который записывает новые словари. Ваше приложение отобразит обновление при следующей навигации или перезагрузке браузера, пересборка не требуется.

Блок-схема (CMS/Backend -> Live Sync Server -> Application Server -> Frontend):

Как это работает:

Рабочий процесс разработки (локально)

• В процессе разработки все удалённые словари загружаются при запуске приложения, чтобы вы могли быстро тестировать обновления.
• Чтобы протестировать Live Sync локально с Next.js, оберните ваш dev-сервер:

{  "scripts": {    // ... другие скрипты    "dev": "npx intlayer live --with 'next dev'",    // "dev": "npx intlayer live --with 'vite dev'", // Для Vite  },}

Включите оптимизацию, чтобы Intlayer применял трансформации Live импорта во время разработки:

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;

Эта настройка оборачивает ваш dev-сервер сервером Live Sync, загружает удалённые словари при запуске и транслирует обновления из CMS через SSE. Обновите страницу, чтобы увидеть изменения.

Примечания и ограничения:

• Добавьте источник live sync в политику безопасности вашего сайта (CSP). Убедитесь, что URL live sync разрешён в connect-src (и в frame-ancestors, если это актуально).
• Live Sync не работает со статическим выводом. Для Next.js страница должна быть динамической, чтобы получать обновления во время выполнения (например, используйте generateStaticParams, generateMetadata, getServerSideProps или getStaticProps соответствующим образом, чтобы избежать ограничений полностью статического вывода).
• В CMS у каждого словаря есть флаг live. Только словари с live=true загружаются через API live sync; остальные импортируются динамически и остаются неизменными во время выполнения.
• Флаг live оценивается для каждого словаря во время сборки. Если удалённый контент не был помечен как live=true во время сборки, необходимо выполнить повторную сборку, чтобы включить Live Sync для этого словаря.
• Сервер live sync должен иметь возможность записывать в .intlayer. В контейнерах убедитесь, что есть права на запись в /.intlayer.

Отладка

Если вы столкнулись с проблемами в CMS, проверьте следующее:

• Приложение запущено.

• Конфигурация editor корректно настроена в вашем конфигурационном файле Intlayer.
  • Обязательные поля:
• URL приложения должен совпадать с тем, который вы указали в конфигурации редактора (applicationURL).

• URL CMS

• Убедитесь, что конфигурация проекта была отправлена в Intlayer CMS.

• Визуальный редактор использует iframe для отображения вашего сайта. Убедитесь, что политика безопасности контента (CSP) вашего сайта разрешает URL CMS в качестве frame-ancestors (по умолчанию 'https://intlayer.org'). Проверьте консоль редактора на наличие ошибок.