توثيق نظام إدارة المحتوى Intlayer (CMS)

www.youtube.com

Open embedded page in fullscreen

نظام إدارة المحتوى Intlayer هو تطبيق يسمح لك بإخراج محتواك من مشروع 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

سيؤدي هذا إلى فتح المتصفح الافتراضي الخاص بك لإكمال عملية المصادقة والحصول على بيانات الاعتماد اللازمة (معرف العميل وسر العميل) لاستخدام خدمات Intlayer.

في ملف تهيئة Intlayer الخاص بك، يمكنك تخصيص إعدادات نظام إدارة المحتوى:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... إعدادات التهيئة الأخرى
  editor: {
    /**
     * مطلوب
     *
     * عنوان URL الخاص بالتطبيق.
     * هذا هو العنوان الذي يستهدفه المحرر المرئي.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * مطلوب
     *
     * معرف العميل والسر السري للعميل مطلوبان لتمكين المحرر.
     * يسمحان بتحديد هوية المستخدم الذي يقوم بتحرير المحتوى.
     * يمكن الحصول عليهما بإنشاء عميل جديد في لوحة تحكم Intlayer - المشاريع (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 بنفسك، يمكنك تعيين عنوان URL الخاص بنظام إدارة المحتوى.
     *
     * عنوان URL الخاص بنظام إدارة المحتوى Intlayer.
     * بشكل افتراضي، يتم تعيينه إلى https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * اختياري
     *
     * في حال كنت تستضيف نظام إدارة المحتوى Intlayer بنفسك، يمكنك تعيين عنوان URL الخاص بالواجهة الخلفية.
     *
     * عنوان URL الخاص بنظام إدارة المحتوى Intlayer.
     * بشكل افتراضي، يتم تعيينه إلى https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

إذا لم يكن لديك معرف عميل وسر عميل، يمكنك الحصول عليهما بإنشاء عميل جديد في لوحة تحكم Intlayer - المشاريع.

لرؤية جميع المعلمات المتاحة، راجع توثيق التهيئة.

استخدام نظام إدارة المحتوى

دفع التهيئة الخاصة بك

لتكوين نظام إدارة محتوى Intlayer، يمكنك استخدام أوامر intlayer CLI.

npx intlayer config push

إذا كنت تستخدم متغيرات البيئة في ملف التهيئة intlayer.config.ts، يمكنك تحديد البيئة المطلوبة باستخدام الوسيطة --env:

npx intlayer config push --env production

يقوم هذا الأمر برفع تهيئتك إلى نظام إدارة محتوى Intlayer.

دفع قاموس

لتحويل قواميس اللغة المحلية الخاصة بك إلى قاموس بعيد، يمكنك استخدام أوامر 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.

الوصول البرمجي باستخدام SDK @intlayer/api

بالإضافة إلى واجهة سطر الأوامر والمحرر المرئي، يأتي Intlayer مع SDK مكتوب بشكل آمن من حيث النوع في حزمة @intlayer/api. يتيح لك التعامل مع نظام إدارة المحتوى كـ قاعدة بيانات محتوى بدون رأس: يمكنك جلب المشاريع وجلب القواميس، وتحديثها مباشرة من تطبيقك الخاص أو البرامج النصية أو خط أنابيب 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" },
});

// Upsert مجموعة من القواميس (إنشاء أو تحديثها في استدعاء واحد)
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();

استخراج طريقة واحدة

كل طريقة endpoint مصادق عليها بالفعل وقائمة بذاتها (تحمل معالجة الرمز الخاص بها)، لذا يمكنك استخراج واحدة وتمريرها حوله — على سبيل المثال لحقنها كتبعية:

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" } }]);

التزامن الحي

يتيح التزامن الحي لتطبيقك عكس تغييرات محتوى نظام إدارة المحتوى أثناء وقت التشغيل. لا حاجة لإعادة البناء أو إعادة النشر. عند التمكين، يتم بث التحديثات إلى خادم التزامن الحي الذي يقوم بتحديث القواميس التي يقرأها تطبيقك.

للحصول على دليل الإعداد الكامل (التفعيل، تشغيل خادم Live Sync، سير عمل التطوير المحلي، والقيود)، راجع توثيق Live Sync.

الاستضافة الذاتية (Self-Hosting)

يمكن تشغيل Intlayer بالكامل على بنيتك التحتية الخاصة. يؤدي أمر واحد إلى تشغيل المكدس الكامل (لوحة التحكم، وواجهة برمجة التطبيقات، وقاعدة البيانات، وتخزين الكائنات، والبريد الإلكتروني) باستخدام Docker Compose:

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

للاطلاع على دليل الإعداد الكامل، ومرجع متغيرات البيئة، وتعليمات الترقية، وإجراءات النسخ الاحتياطي والاستعادة، راجع دليل الاستضافة الذاتية.

تصحيح الأخطاء

إذا واجهت أي مشاكل مع نظام إدارة المحتوى (CMS)، تحقق من الأمور التالية:

• التطبيق يعمل.

• تم إعداد تكوين المحرر بشكل صحيح في ملف تكوين Intlayer الخاص بك.

  • الحقول المطلوبة:
    • يجب أن يتطابق عنوان URL الخاص بالتطبيق مع العنوان الذي قمت بتعيينه في تكوين المحرر (applicationURL).
    • عنوان URL الخاص بنظام إدارة المحتوى (CMS)

• تأكد من أن تكوين المشروع تم دفعه إلى نظام إدارة محتوى Intlayer.

• يستخدم المحرر المرئي إطار iframe لعرض موقعك الإلكتروني. تأكد من أن سياسة أمان المحتوى (CSP) لموقعك تسمح بعنوان URL الخاص بنظام إدارة المحتوى كـ frame-ancestors ('https://app.intlayer.org' بشكل افتراضي). تحقق من وحدة تحكم المحرر لأي أخطاء.