Dokumentasi Sistem Manajemen Konten (CMS) Intlayer

Intlayer CMS adalah sebuah Aplikasi yang memungkinkan Anda untuk mengeksternalisasi konten dari proyek Intlayer.

Untuk itu, Intlayer memperkenalkan konsep 'kamus jauh'.

Daftar Isi

Memahami kamus jauh

Intlayer membedakan antara kamus 'lokal' dan 'remote'.

• Kamus 'lokal' adalah kamus yang dideklarasikan dalam proyek Intlayer Anda. Seperti file deklarasi sebuah tombol, atau bilah navigasi Anda. Mengeksternalisasi konten Anda tidak masuk akal dalam kasus ini karena konten tersebut tidak seharusnya sering berubah.

• Kamus 'remote' adalah kamus yang dikelola melalui Intlayer CMS. Ini bisa berguna untuk memungkinkan tim Anda mengelola konten secara langsung di situs web Anda, dan juga bertujuan untuk menggunakan fitur pengujian A/B dan optimasi SEO otomatis.

Editor visual vs CMS

Editor Visual Intlayer adalah alat yang memungkinkan Anda mengelola konten Anda dalam editor visual untuk kamus lokal. Setelah perubahan dilakukan, konten akan diganti dalam code-base. Itu berarti aplikasi akan dibangun ulang dan halaman akan dimuat ulang untuk menampilkan konten baru.

Sebaliknya, Intlayer CMS adalah alat yang memungkinkan Anda mengelola konten Anda dalam editor visual untuk kamus jarak jauh. Setelah perubahan dilakukan, konten tidak akan memengaruhi code-base Anda. Dan situs web akan secara otomatis menampilkan konten yang telah diubah.

Integrasi

Untuk detail lebih lanjut tentang cara menginstal paket, lihat bagian terkait di bawah ini:

Integrasi dengan Next.js

Untuk integrasi dengan Next.js, lihat panduan pengaturan.

Integrasi dengan Create React App

Untuk integrasi dengan Create React App, lihat panduan pengaturan.

Integrasi dengan Vite + React

Untuk integrasi dengan Vite + React, lihat panduan pengaturan.

Konfigurasi

Jalankan perintah berikut untuk masuk ke Intlayer CMS:

npx intlayer login

Ini akan membuka browser default Anda untuk menyelesaikan proses autentikasi dan menerima kredensial yang diperlukan (Client ID dan Client Secret) untuk menggunakan layanan Intlayer.

Dalam file konfigurasi Intlayer Anda, Anda dapat menyesuaikan pengaturan CMS:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... pengaturan konfigurasi lainnya
  editor: {
    /**
     * Wajib
     *
     * URL dari aplikasi.
     * Ini adalah URL yang ditargetkan oleh editor visual.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Wajib
     *
     * Client ID dan client secret diperlukan untuk mengaktifkan editor.
     * Mereka memungkinkan identifikasi pengguna yang sedang mengedit konten.
     * Mereka dapat diperoleh dengan membuat client baru di 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,

    /**
     * Opsional
     *
     * Jika Anda meng-host sendiri Intlayer CMS, Anda dapat mengatur URL CMS.
     *
     * URL dari Intlayer CMS.
     * Secara default, diatur ke https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Opsi
     *
     * Jika Anda meng-host sendiri Intlayer CMS, Anda dapat mengatur URL backend.
     *
     * URL dari Intlayer CMS.
     * Secara default, diatur ke https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Jika Anda belum memiliki client ID dan client secret, Anda dapat memperolehnya dengan membuat client baru di Intlayer Dashboard - Projects.

Untuk melihat semua parameter yang tersedia, lihat dokumentasi konfigurasi.

Menggunakan CMS

Push konfigurasi Anda

Untuk mengonfigurasi Intlayer CMS, Anda dapat menggunakan perintah intlayer CLI.

npx intlayer config push

Jika Anda menggunakan variabel lingkungan dalam file konfigurasi intlayer.config.ts Anda, Anda dapat menentukan lingkungan yang diinginkan menggunakan argumen --env:

npx intlayer config push --env production

Perintah ini mengunggah konfigurasi Anda ke Intlayer CMS.

Push kamus

Untuk mengubah kamus lokal Anda menjadi kamus jarak jauh, Anda dapat menggunakan perintah intlayer CLI.

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

Jika Anda menggunakan variabel lingkungan dalam file konfigurasi intlayer.config.ts Anda, Anda dapat menentukan lingkungan yang diinginkan menggunakan argumen --env:

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

Perintah ini mengunggah kamus konten awal Anda, sehingga tersedia untuk pengambilan dan pengeditan secara asinkron melalui platform Intlayer.

Edit kamus

Kemudian Anda akan dapat melihat dan mengelola kamus Anda di Intlayer CMS.

Akses programatis dengan SDK @intlayer/api

Selain CLI dan editor visual, Intlayer menyediakan SDK yang ter-type dalam paket @intlayer/api. Ini memungkinkan Anda memperlakukan CMS sebagai database konten headless: Anda dapat mengambil proyek, mengambil dictionary, dan mendorong atau memperbarui mereka langsung dari aplikasi, skrip, atau pipeline CI Anda sendiri.

SDK menangani autentikasi untuk Anda. Selama clientId dan clientSecret Anda tersedia (dalam konfigurasi Intlayer atau environment), SDK memperoleh dan menyegarkan token akses OAuth2 secara otomatis serta menandatangani setiap permintaan.

Instalasi

npm install @intlayer/api

Cara kerjanya: authenticator + endpoints

SDK dibagi menjadi dua import terpisah dengan tujuan, untuk membuat bundle Anda tetap kecil:

1. createIntlayerCMS — membuat authenticator yang ringan. Ini hanya membawa kredensial dan token akses yang dikelola; ia tidak mengetahui apa pun tentang domain tertentu.
2. dictionaryEndpoint, projectEndpoint, … — endpoint binders per-domain, masing-masing diimpor dari subpath-nya sendiri (@intlayer/api/dictionary, @intlayer/api/project, …). Anda melewatkan authenticator ke endpoint yang Anda butuhkan.

Karena setiap endpoint diimpor secara terpisah, bundle Anda hanya mencakup domain yang benar-benar Anda gunakan — mengimpor dictionaryEndpoint tidak akan pernah menarik klien project, AI, atau domain lainnya.

import { createIntlayerCMS } from "@intlayer/api";// Konfigurasi bersifat opsional: ketika dihilangkan, kredensial dibaca dari// `@intlayer/config/built`, yang menyelesaikan variabel lingkungan INTLAYER_CLIENT_ID dan// INTLAYER_CLIENT_SECRET.export const cmsAuthenticator = createIntlayerCMS();

WARNING

Kredensial CMS (clientId / clientSecret) memberikan akses tulis ke konten Anda. Selalu buat authenticator hanya di sisi server (server actions, route handlers, scripts, CI). Jangan pernah mengimpor ke kode sisi klien atau membuka kredensial Anda ke browser.

Jika Anda lebih suka tidak mengandalkan konfigurasi waktu build, teruskan kredensial secara eksplisit:

import { createIntlayerCMS } from "@intlayer/api";export const cmsAuthenticator = createIntlayerCMS({  editor: {    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    // Opsional, untuk backend yang di-host sendiri:    // backendURL: process.env.INTLAYER_BACKEND_URL,  },});

Dapatkan kredensial Anda dengan membuat kunci akses baru di Intlayer Dashboard - Projects.

Fetch projects

import { createIntlayerCMS } from "@intlayer/api";import { projectEndpoint } from "@intlayer/api/project";const cmsAuthenticator = createIntlayerCMS();// Daftar proyek yang dapat diakses dengan kredensial Andaconst { data: projects } =  await projectEndpoint(cmsAuthenticator).getProjects();// Baca wawasan lokalisasi agregat dari proyek yang dipilihconst { data: insights } =  await projectEndpoint(cmsAuthenticator).getProjectInsights();

Fetch dictionaries

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cmsAuthenticator = createIntlayerCMS();// Daftar setiap kamus jarak jauh dari proyekconst { data: dictionaries } =  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();// Atau dapatkan satu kamus berdasarkan kunciconst { data: dictionary } = await dictionaryEndpoint(  cmsAuthenticator).getDictionary("my-first-dictionary-key");

Push and update dictionaries

Use the CMS as a database to write content back:

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cmsAuthenticator = createIntlayerCMS();// Buat kamus baruawait dictionaryEndpoint(cmsAuthenticator).addDictionary({  key: "my-first-dictionary-key",  content: { title: "Hello world" },});// Upsert batch kamus (buat atau perbarui dalam satu panggilan)await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([  { key: "home", content: { title: "Home" } },  { key: "about", content: { title: "About" } },]);// Perbarui kamus yang adaawait dictionaryEndpoint(cmsAuthenticator).updateDictionary({  id: "<dictionary-id>",  key: "home",  content: { title: "Updated title" },});

Tip: gunakan kembali endpoint yang terikat untuk menghindari pengulangan:

typescript

Salin konten

Salin kode

Salin kode ke clipboard

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

Mengekstrak satu method

Setiap endpoint method sudah terauthentikasi dan standalone (membawa penanganan token-nya sendiri), jadi Anda dapat mengekstraknya dan meneruskannya — misalnya untuk melakukannya sebagai dependency:

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const dictionary = dictionaryEndpoint(createIntlayerCMS());// Sudah terauthentikasi — menyegarkan token secara otomatis pada setiap panggilanexport const pushDictionaries = dictionary.pushDictionaries;// Penggunaanawait pushDictionaries([{ key: "home", content: { title: "Home" } }]);

Sinkronisasi langsung

Sinkronisasi Langsung memungkinkan aplikasi Anda mencerminkan perubahan konten CMS secara real-time. Tidak perlu membangun ulang atau menerapkan ulang. Saat diaktifkan, pembaruan dikirimkan ke server Sinkronisasi Langsung yang menyegarkan kamus yang dibaca aplikasi Anda.

Untuk panduan pengaturan lengkap (mengaktifkan, menjalankan server Live Sync, alur kerja pengembangan lokal, dan batasan), lihat dokumentasi Live Sync.

Self-Hosting

Intlayer dapat berjalan sepenuhnya pada infrastruktur Anda sendiri. Satu baris perintah bootstrap stack lengkap (dashboard, API, database, object storage, dan email) dengan Docker Compose:

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

Untuk panduan setup lengkap, referensi variabel environment, instruksi upgrade, dan prosedur backup/restore, lihat Self-Hosting Guide.

Debug

Jika Anda mengalami masalah dengan CMS, periksa hal-hal berikut:

• Aplikasi sedang berjalan.

• Konfigurasi editor sudah diatur dengan benar dalam file konfigurasi Intlayer Anda.

  • Field yang diperlukan:
    • URL aplikasi harus sesuai dengan yang Anda atur dalam konfigurasi editor (applicationURL).
    • URL CMS

• Pastikan konfigurasi proyek telah dipush ke Intlayer CMS.

• Visual editor menggunakan iframe untuk menampilkan situs web Anda. Pastikan Content Security Policy (CSP) situs web Anda mengizinkan URL CMS sebagai frame-ancestors ('https://app.intlayer.org' secara default). Periksa konsol editor untuk setiap kesalahan.