Documentação do Sistema de Gestão de Conteúdo (CMS) Intlayer

O Intlayer CMS é uma aplicação que permite externalizar o conteúdo de um projeto Intlayer.

Para isso, o Intlayer introduz o conceito de 'dicionários distantes'.

Índice

Entendendo os dicionários distantes

O Intlayer faz uma distinção entre dicionários 'locais' e 'distantes'.

• Um dicionário 'local' é um dicionário que é declarado no seu projeto Intlayer. Como o arquivo de declaração de um botão, ou sua barra de navegação. Externalizar seu conteúdo não faz sentido neste caso porque esse conteúdo não deve mudar com frequência.

• Um dicionário 'distante' é um dicionário que é gerenciado através do Intlayer CMS. Pode ser útil para permitir que sua equipe gerencie seu conteúdo diretamente no seu site, e também tem como objetivo usar recursos de testes A/B e otimização automática de SEO.

Editor visual vs CMS

O editor Intlayer Visual é uma ferramenta que permite gerenciar seu conteúdo em um editor visual para dicionários locais. Uma vez que uma alteração é feita, o conteúdo será substituído na base de código. Isso significa que a aplicação será reconstruída e a página será recarregada para exibir o novo conteúdo.

Em contraste, o Intlayer CMS é uma ferramenta que permite gerenciar seu conteúdo em um editor visual para dicionários distantes. Uma vez que uma alteração é feita, o conteúdo não impactará sua base de código. E o site exibirá automaticamente o conteúdo alterado.

Integração

Para mais detalhes sobre como instalar o pacote, veja a seção relevante abaixo:

Integração com Next.js

Para integração com Next.js, consulte o guia de configuração.

Integração com Create React App

Para integração com Create React App, consulte o guia de configuração.

Integração com Vite + React

Para integração com Vite + React, consulte o guia de configuração.

Configuração

Execute o seguinte comando para fazer login no Intlayer CMS:

npx intlayer login

Isso abrirá seu navegador padrão para concluir o processo de autenticação e receber as credenciais necessárias (Client ID e Client Secret) para usar os serviços do Intlayer.

No seu arquivo de configuração do Intlayer, você pode personalizar as configurações do CMS:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... outras configurações
  editor: {
    /**
     * Obrigatório
     *
     * A URL da aplicação.
     * Esta é a URL alvo do editor visual.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Obrigatório
     *
     * Client ID e client secret são necessários para ativar o editor.
     * Eles permitem identificar o usuário que está editando o conteúdo.
     * Podem ser obtidos criando um novo cliente no Painel do Intlayer - Projetos (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,

    /**
     * Opcional
     *
     * No caso de estar a hospedar o Intlayer CMS por conta própria, pode definir a URL do CMS.
     *
     * A URL do Intlayer CMS.
     * Por padrão, está definida para https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Opcional
     *
     * No caso de estar a hospedar o Intlayer CMS por conta própria, pode definir a URL do backend.
     *
     * A URL do Intlayer CMS.
     * Por padrão, está definida para https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Se não tiver um client ID e client secret, pode obtê-los criando um novo cliente no Intlayer Dashboard - Projects.

Para ver todos os parâmetros disponíveis, consulte a documentação de configuração.

Usando o CMS

Enviar a sua configuração

Para configurar o Intlayer CMS, pode usar os comandos do intlayer CLI.

npx intlayer config push

Se usar variáveis de ambiente no seu ficheiro de configuração intlayer.config.ts, pode especificar o ambiente desejado usando o argumento --env:

npx intlayer config push --env production

Este comando envia a sua configuração para o Intlayer CMS.

Enviar um dicionário

Para transformar os seus dicionários de localidade num dicionário remoto, pode usar os comandos do intlayer CLI.

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

Se usar variáveis de ambiente no seu ficheiro de configuração intlayer.config.ts, pode especificar o ambiente desejado usando o argumento --env:

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

Este comando envia os seus dicionários de conteúdo iniciais, tornando-os disponíveis para obtenção e edição assíncronas através da plataforma Intlayer.

Editar o dicionário

Depois, poderá ver e gerir o seu dicionário no Intlayer CMS.

Sincronização ao vivo

A Sincronização ao Vivo permite que a sua aplicação reflita as alterações de conteúdo do CMS em tempo de execução. Não é necessário reconstruir ou reimplantar. Quando ativada, as atualizações são transmitidas para um servidor de Sincronização ao Vivo que atualiza os dicionários que a sua aplicação lê.

Para o guia de configuração completo (ativação, início do servidor Live Sync, fluxo de trabalho de desenvolvimento local e restrições), consulte a documentação do Live Sync.

Instalação

npm install @intlayer/api

Como funciona: autenticador + endpoints

O SDK é dividido em duas importações separadas propositalmente, para manter seu bundle pequeno:

1. createIntlayerCMS — cria um autenticador leve. Ele apenas contém as credenciais e o token de acesso gerenciado; não sabe nada sobre nenhum domínio específico.
2. dictionaryEndpoint, projectEndpoint, … — vinculadores de endpoint por domínio, cada um importado de seu próprio subcaminho (@intlayer/api/dictionary, @intlayer/api/project, …). Você passa o autenticador para o endpoint que precisa.

Como cada endpoint é importado separadamente, seu bundle inclui apenas os domínios que você realmente usa — importar dictionaryEndpoint nunca puxa o cliente de projeto, IA ou qualquer outro domínio.

import { createIntlayerCMS } from "@intlayer/api";// A configuração é opcional: quando omitida, as credenciais são lidas de// `@intlayer/config/built`, que resolve as variáveis de ambiente// INTLAYER_CLIENT_ID e INTLAYER_CLIENT_SECRET.export const cmsAuthenticator = createIntlayerCMS();

WARNING

As credenciais do CMS (clientId / clientSecret) concedem acesso de escrita ao seu conteúdo. Sempre crie o autenticador apenas no lado do servidor (server actions, route handlers, scripts, CI). Nunca importe para código do lado do cliente ou exponha suas credenciais ao navegador.

Se preferir não depender da configuração em tempo de build, passe as credenciais explicitamente:

import { createIntlayerCMS } from "@intlayer/api";export const cmsAuthenticator = createIntlayerCMS({  editor: {    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    // Opcional, para backends auto-hospedados:    // backendURL: process.env.INTLAYER_BACKEND_URL,  },});

Obtenha suas credenciais criando uma nova chave de acesso no Intlayer Dashboard - Projects.

Conectando seu projeto a uma instância auto-hospedada

Aponte sua configuração do Intlayer para seu próprio backend e dashboard em vez 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 do dashboard CMS auto-hospedado.
     * Padrão: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // ex. http://localhost:3000

    /**
     * URL da API backend auto-hospedada.
     * Padrão: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // ex. http://localhost:3100
  },
};

export default config;

Defina as variáveis de ambiente correspondentes no seu projeto:

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

Crie credenciais de acesso no seu dashboard auto-hospedado em http://localhost:3000/projects.

SDK @intlayer/api: apontando para um backend auto-hospedado

Ao usar o SDK de forma programática, passe backendURL explicitamente para 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();

Recursos opcionais

Estes recursos requerem contas externas e funcionam corretamente quando suas chaves estão ausentes do .env auto-hospedado:

Persistência de dados e atualizações

Três volumes do Docker contêm todo o estado persistente: mongo-data, redis-data e minio-data. Eles sobrevivem a reinicializações e atualizações de contêineres. Executar o instalador novamente baixa as imagens mais recentes e realiza um docker compose up -d gradual.

Portas expostas no host:

Para uma referência completa de todas as variáveis de ambiente disponíveis e opções avançadas (proxy reverso, domínios personalizados, backup/restauração), consulte o Guia de Auto-hospedagem.

Live Sync

O Live Sync permite que seu aplicativo reflita as alterações de conteúdo do CMS em tempo de execução — sem necessidade de reconstrução ou reimplantação. Quando habilitado, as atualizações são transmitidas para um servidor Live Sync que atualiza os dicionários que seu aplicativo lê.

Para o guia de configuração completo (configuração, iniciando o servidor Live Sync, fluxo de trabalho de desenvolvimento local e restrições), consulte a documentação do Live Sync.

Auto-hospedagem

O Intlayer pode ser executado inteiramente em sua própria infraestrutura. Um comando único inicializa a pilha completa (dashboard, API, banco de dados, armazenamento de objetos e email) com Docker Compose:

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

Para o guia de configuração completo, referência de variáveis de ambiente, instruções de atualização e procedimentos de backup/restauração, consulte o Guia de Auto-hospedagem.

Depuração

Se encontrar problemas com o CMS, verifique o seguinte:

• A aplicação está em execução.

• A configuração editor está corretamente definida no seu arquivo de configuração do Intlayer.

  • Campos obrigatórios:
    • O URL da aplicação deve corresponder ao que você definiu na configuração do editor (applicationURL).
    • O URL do CMS

• Certifique-se de que a configuração do projeto foi enviada para o Intlayer CMS.

• O editor visual usa um iframe para exibir seu website. Certifique-se de que a Política de Segurança de Conteúdo (CSP) do seu website permite o URL do CMS como frame-ancestors ('https://app.intlayer.org' por padrão). Verifique o console do editor para qualquer erro.