Dokumentacja Systemu Zarządzania Treścią Intlayer (CMS)

Intlayer CMS to aplikacja, która pozwala na zewnętrzne zarządzanie treścią projektu Intlayer.

W tym celu Intlayer wprowadza koncepcję „zdalnych słowników”.

Spis treści

Zrozumienie zdalnych słowników

Intlayer rozróżnia „lokalne” i „zdalne” słowniki.

• „Lokalny” słownik to słownik zadeklarowany w Twoim projekcie Intlayer. Na przykład plik deklaracji przycisku lub pasek nawigacyjny. Zewnętrzne zarządzanie taką treścią nie ma sensu, ponieważ ta zawartość nie powinna się często zmieniać.

• „Zdalny” słownik to słownik zarządzany za pomocą Intlayer CMS. Może być przydatny, aby umożliwić Twojemu zespołowi bezpośrednie zarządzanie treścią na Twojej stronie internetowej, a także ma na celu wykorzystanie funkcji testów A/B oraz automatycznej optymalizacji SEO.

Edytor wizualny a CMS

Edytor Intlayer Visual to narzędzie, które pozwala zarządzać treścią w edytorze wizualnym dla lokalnych słowników. Po wprowadzeniu zmiany, zawartość zostanie zastąpiona w bazie kodu. Oznacza to, że aplikacja zostanie przebudowana, a strona przeładowana, aby wyświetlić nową treść.

W przeciwieństwie do tego, Intlayer CMS to narzędzie, które pozwala zarządzać treścią w edytorze wizualnym dla zdalnych słowników. Po wprowadzeniu zmiany, zawartość nie wpłynie na bazę kodu. Strona internetowa automatycznie wyświetli zmienioną treść.

Integracja

Aby uzyskać więcej szczegółów na temat instalacji pakietu, zobacz odpowiednią sekcję poniżej:

Integracja z Next.js

Aby zintegrować z Next.js, zapoznaj się z przewodnikiem instalacji.

Integracja z Create React App

Aby zintegrować z Create React App, zapoznaj się z przewodnikiem instalacji.

Integracja z Vite + React

Aby zintegrować z Vite + React, zapoznaj się z przewodnikiem instalacji.

Konfiguracja

Uruchom następujące polecenie, aby zalogować się do Intlayer CMS:

npx intlayer login

Spowoduje to otwarcie domyślnej przeglądarki w celu ukończenia procesu uwierzytelniania i otrzymania niezbędnych poświadczeń (Client ID i Client Secret) do korzystania z usług Intlayer.

W pliku konfiguracyjnym Intlayer możesz dostosować ustawienia CMS:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... inne ustawienia konfiguracyjne
  editor: {
    /**
     * Wymagane
     *
     * URL aplikacji.
     * To jest URL, na który wskazuje edytor wizualny.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Wymagane
     *
     * Client ID oraz client secret są wymagane do włączenia edytora.
     * Pozwalają one zidentyfikować użytkownika, który edytuje zawartość.
     * Można je uzyskać tworząc nowego klienta w 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,

    /**
     * Opcjonalne
     *
     * W przypadku, gdy hostujesz Intlayer CMS samodzielnie, możesz ustawić URL CMS.
     *
     * URL Intlayer CMS.
     * Domyślnie ustawiony jest na https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Opcjonalne
     *
     * W przypadku, gdy hostujesz Intlayer CMS samodzielnie, możesz ustawić URL backendu.
     *
     * URL backendu Intlayer CMS.
     * Domyślnie ustawiony jest na https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Jeśli nie masz client ID i client secret, możesz je uzyskać, tworząc nowego klienta w Intlayer Dashboard - Projects.

Aby zobaczyć wszystkie dostępne parametry, zapoznaj się z dokumentacją konfiguracji.

Korzystanie z CMS

Wypchnij swoją konfigurację

Aby skonfigurować Intlayer CMS, możesz użyć poleceń intlayer CLI.

npx intlayer config push

Jeśli używasz zmiennych środowiskowych w pliku konfiguracyjnym intlayer.config.ts, możesz określić żądane środowisko za pomocą argumentu --env:

npx intlayer config push --env production

To polecenie przesyła Twoją konfigurację do Intlayer CMS.

Wypchnij słownik

Aby przekształcić swoje słowniki lokalizacyjne w zdalny słownik, możesz użyć poleceń intlayer CLI.

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

Jeśli używasz zmiennych środowiskowych w pliku konfiguracyjnym intlayer.config.ts, możesz określić żądane środowisko za pomocą argumentu --env:

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

To polecenie przesyła Twoje początkowe słowniki treści, udostępniając je do asynchronicznego pobierania i edycji za pośrednictwem platformy Intlayer.

Edytuj słownik

Następnie będziesz mógł zobaczyć i zarządzać swoim słownikiem w Intlayer CMS.

Synchronizacja na żywo

Synchronizacja na żywo pozwala Twojej aplikacji odzwierciedlać zmiany treści CMS w czasie rzeczywistym. Nie jest wymagane ponowne budowanie ani wdrażanie. Po włączeniu aktualizacje są przesyłane do serwera synchronizacji na żywo, który odświeża słowniki odczytywane przez Twoją aplikację.

Włącz synchronizację na żywo, aktualizując konfigurację Intlayer:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... inne ustawienia konfiguracyjne
  editor: {
    /**
     * Włącza hot reloading konfiguracji lokalizacji, gdy wykryte zostaną zmiany.
     * Na przykład, gdy słownik zostanie dodany lub zaktualizowany, aplikacja aktualizuje
     * wyświetlaną na stronie zawartość.
     *
     * Ponieważ hot reloading wymaga ciągłego połączenia z serwerem,
     * jest dostępny tylko dla klientów planu `enterprise`.
     *
     * Domyślnie: false
     */
    liveSync: true,
  },
  dictionary: {
    /**
     * Kontroluje sposób importowania słowników:
     *
     * - "live": Słowniki są pobierane dynamicznie za pomocą API Live Sync.
     *   Zastępuje useIntlayer funkcją useDictionaryDynamic.
     *
     * Uwaga: Tryb live korzysta z API Live Sync do pobierania słowników. Jeśli wywołanie API
     * zakończy się niepowodzeniem, słowniki są importowane dynamicznie.
     * Uwaga: Tryb live jest używany tylko dla słowników zdalnych i oznaczonych flagą "live".
     * Pozostałe używają trybu dynamicznego dla wydajności.
     */
    importMode: "fetch",
  },
};

export default config;

Uruchom serwer Live Sync, aby otoczyć swoją aplikację:

Przykład użycia samodzielnego serwera:

{  "scripts": {    // ... inne skrypty    "live:start": "npx intlayer live",  },}

Możesz również używać swojego serwera aplikacji równolegle, korzystając z argumentu --process.

Przykład użycia Next.js:

{  "scripts": {    // ... inne skrypty    "build": "next build",    "dev": "next dev",    "start": "npx intlayer live --with 'next start'",  },}

Przykład użycia Vite:

{  "scripts": {    // ... inne skrypty    "build": "vite build",    "dev": "vite dev",    "start": "npx intlayer live --with 'vite start'",  },}

Serwer Live Sync otacza Twoją aplikację i automatycznie stosuje zaktualizowaną zawartość w momencie jej pojawienia się.

Aby otrzymywać powiadomienia o zmianach z CMS, serwer Live Sync utrzymuje połączenie SSE z backendem. Gdy zawartość w CMS ulega zmianie, backend przekazuje aktualizację do serwera Live Sync, który zapisuje nowe słowniki. Twoja aplikacja odzwierciedli aktualizację przy następnej nawigacji lub przeładowaniu przeglądarki, nie jest wymagane ponowne budowanie.

Schemat przepływu (CMS/Backend -> Serwer Live Sync -> Serwer aplikacji -> Frontend):

Jak to działa:

Przebieg pracy podczas developmentu (lokalnie)

• Podczas developmentu wszystkie zdalne słowniki są pobierane przy starcie aplikacji, dzięki czemu możesz szybko testować aktualizacje.
• Aby przetestować Live Sync lokalnie z Next.js, opakuj swój serwer deweloperski:

{  "scripts": {    // ... inne skrypty    "dev": "npx intlayer live --with 'next dev'",    // "dev": "npx intlayer live --with 'vite dev'", // Dla Vite  },}

Włącz optymalizację, aby Intlayer stosował transformacje importu Live podczas developmentu:

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;

To ustawienie owija Twój serwer deweloperski serwerem Live Sync, pobiera zdalne słowniki podczas uruchamiania i przesyła aktualizacje z CMS za pomocą SSE. Odśwież stronę, aby zobaczyć zmiany.

Uwagi i ograniczenia:

• Dodaj pochodzenie live sync do polityki bezpieczeństwa swojej strony (CSP). Upewnij się, że adres URL live sync jest dozwolony w connect-src (oraz frame-ancestors, jeśli ma to zastosowanie).
• Live Sync nie działa ze statycznym outputem. W Next.js strona musi być dynamiczna, aby otrzymywać aktualizacje w czasie wykonywania (np. użyj generateStaticParams, generateMetadata, getServerSideProps lub getStaticProps odpowiednio, aby uniknąć pełnych ograniczeń statycznych).
• W CMS każdy słownik ma flagę live. Tylko słowniki z live=true są pobierane przez API live sync; pozostałe są importowane dynamicznie i pozostają niezmienione w czasie wykonywania.
• Flaga live jest oceniana dla każdego słownika podczas budowania. Jeśli zdalna zawartość nie była oznaczona jako live=true podczas budowania, musisz przebudować projekt, aby włączyć Live Sync dla tego słownika.
• Serwer live sync musi mieć możliwość zapisu do .intlayer. W kontenerach upewnij się, że masz dostęp do zapisu do /.intlayer.

Debug

Jeśli napotkasz jakiekolwiek problemy z CMS, sprawdź następujące kwestie:

• Aplikacja jest uruchomiona.

• Konfiguracja editor jest poprawnie ustawiona w pliku konfiguracyjnym Intlayer.

  • Wymagane pola:
    • URL aplikacji powinien odpowiadać temu, który ustawiłeś w konfiguracji edytora (applicationURL).
    • URL CMS

• Upewnij się, że konfiguracja projektu została przesłana do Intlayer CMS.

• Edytor wizualny używa iframe do wyświetlania Twojej strony internetowej. Upewnij się, że Polityka Bezpieczeństwa Treści (CSP) Twojej strony pozwala na URL CMS jako frame-ancestors (domyślnie 'https://intlayer.org'). Sprawdź konsolę edytora pod kątem błędów.