Документация по системе управления контентом 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.

Программный доступ с помощью SDK @intlayer/api

Помимо CLI и визуального редактора, Intlayer поставляется с типизированным SDK в пакете @intlayer/api. Он позволяет вам рассматривать CMS как бесголовую базу данных контента: вы можете получать проекты, получать словари, а также отправлять или обновлять их непосредственно из вашего собственного приложения, скриптов или CI-конвейера.

SDK обрабатывает аутентификацию за вас. Пока ваши clientId и clientSecret доступны (в вашей конфигурации Intlayer или переменных окружения), он автоматически получает и обновляет токен доступа OAuth2 и подписывает каждый запрос.

Установка

npm install @intlayer/api

Как это работает: аутентификатор + эндпоинты

SDK разделён на два отдельных импорта специально, чтобы сохранить размер вашего бандла небольшим:

1. createIntlayerCMS — создаёт легковесный аутентификатор. Он содержит только учётные данные и управляемый токен доступа; он ничего не знает о каком-либо конкретном домене.
2. dictionaryEndpoint, projectEndpoint, … — биндинги эндпоинтов для каждого домена, каждый импортируется из своего подпути (@intlayer/api/dictionary, @intlayer/api/project, …). Вы передаёте аутентификатор нужному эндпоинту.

Поскольку каждый эндпоинт импортируется отдельно, ваш бандл включает только те домены, которые вы фактически используете — импорт dictionaryEndpoint никогда не подтягивает проект, ИИ или любой другой клиент домена.

import { createIntlayerCMS } from "@intlayer/api";// Конфигурация необязательна: если она пропущена, учётные данные считываются из// `@intlayer/config/built`, который разрешает переменные окружения INTLAYER_CLIENT_ID и// INTLAYER_CLIENT_SECRET.export const cmsAuthenticator = createIntlayerCMS();

WARNING

Учётные данные CMS (clientId / clientSecret) предоставляют доступ на запись к вашему контенту. Создавайте аутентификатор только на серверной стороне (серверные действия, обработчики маршрутов, скрипты, CI). Никогда не импортируйте его в клиентский код и не раскрывайте свои учётные данные в браузере.

Если вы предпочитаете не полагаться на конфигурацию времени сборки, передайте учётные данные явно:

import { createIntlayerCMS } from "@intlayer/api";export const cmsAuthenticator = createIntlayerCMS({  editor: {    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    // Необязательно, для самостоятельно размещённых бэкендов:    // backendURL: process.env.INTLAYER_BACKEND_URL,  },});

Получите свои учётные данные, создав новый ключ доступа в Панели управления Intlayer - Проекты.

Получение проектов

import { createIntlayerCMS } from "@intlayer/api";import { projectEndpoint } from "@intlayer/api/project";const cmsAuthenticator = createIntlayerCMS();// Список проектов, доступных с вашими учётными даннымиconst { data: projects } =  await projectEndpoint(cmsAuthenticator).getProjects();// Чтение агрегированных данных о локализации выбранного проектаconst { data: insights } =  await projectEndpoint(cmsAuthenticator).getProjectInsights();

Получение словарей

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cmsAuthenticator = createIntlayerCMS();// Вывести каждый удалённый словарь проектаconst { data: dictionaries } =  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();// Или получить один словарь по ключуconst { data: dictionary } = await dictionaryEndpoint(  cmsAuthenticator).getDictionary("my-first-dictionary-key");

Отправка и обновление словарей

Используйте CMS как базу данных для записи контента:

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cmsAuthenticator = createIntlayerCMS();// Создать новый словарьawait dictionaryEndpoint(cmsAuthenticator).addDictionary({  key: "my-first-dictionary-key",  content: { title: "Hello world" },});// Обновить или вставить партию словарей (создать или обновить их за один вызов)await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([  { key: "home", content: { title: "Home" } },  { key: "about", content: { title: "About" } },]);// Обновить существующий словарьawait dictionaryEndpoint(cmsAuthenticator).updateDictionary({  id: "<dictionary-id>",  key: "home",  content: { title: "Updated title" },});

Совет: повторно используйте связанный эндпоинт, чтобы избежать повторений:

typescript

Копировать содержимое

Копировать код

Копировать код в буфер обмена

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

Извлечение отдельного метода

Каждый метод эндпоинта уже аутентифицирован и самодостаточен (он обрабатывает свой собственный токен), поэтому вы можете извлечь его и передавать — например, для инъекции в качестве зависимости:

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const dictionary = dictionaryEndpoint(createIntlayerCMS());// Уже аутентифицирован — автоматически обновляет токен при каждом вызовеexport const pushDictionaries = dictionary.pushDictionaries;// Использованиеawait pushDictionaries([{ key: "home", content: { title: "Home" } }]);

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

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

Полное руководство по настройке (включение, запуск сервера Live Sync, рабочий процесс локальной разработки и ограничения) см. в документации Live Sync.

Самостоятельное размещение (Self-Hosting)

Intlayer может работать полностью на вашей собственной инфраструктуре. Одна команда поднимает весь стек (дашборд, API, база данных, хранилище объектов и электронная почта) с помощью Docker Compose:

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

Полное руководство по настройке, справочник по переменным окружения, инструкции по обновлению и процедуры резервного копирования/восстановления см. в Руководстве по самостоятельному размещению.

Отладка

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

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

• Конфигурация editor корректно настроена в вашем конфигурационном файле Intlayer.

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

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

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