المؤلف:
    Aymeric PINEAU
    إنشاء:2026-03-31آخر تحديث:2026-05-31

    ترجمة موقع Vanilla JS الخاص بك باستخدام Intlayer | التدويل (i18n)

    ide.intlayer.org
    intlayer-vanilla-template.vercel.app

    جدول المحتويات

    لماذا Intlayer على البدائل؟

    بالمقارنة مع الحلول الرئيسية مثل i18next أو i18n.js، يعد Intlayer حلاً يأتي مزودًا بتحسينات متكاملة مثل:

    تم تحسين Intlayer للعمل بشكل مثالي مع Vanilla JavaScript من خلال تقديم إدارة محتوى مستقلة عن إطار العمل، ودعم TypeScript، وجميع الميزات اللازمة لتوسيع نطاق التدويل (i18n).

    بدلاً من تحميل ملفات JSON ضخمة إلى صفحاتك، قم بتحميل المحتوى الضروري فقط. يساعد Intlayer في تقليل أحجام البندل وصفحاتك بنسبة تصل إلى 50%.

    يؤدي تحديد نطاق محتوى تطبيقك * إلى تسهيل الصيانة * للتطبيقات واسعة النطاق. يمكنك تكرار أو حذف مجلد ميزات واحد دون العبء العقلي لمراجعة قاعدة بيانات المحتوى بالكامل. بالإضافة إلى ذلك، تتم كتابة Intlayer بالكامل لضمان دقة المحتوى الخاص بك.

    يؤدي تحديد موقع المحتوى المشترك * إلى تقليل السياق المطلوب * بواسطة نماذج اللغات الكبيرة (LLMs). يأتي Intlayer أيضًا مزودًا بمجموعة من الأدوات، مثل CLI لاختبار الترجمات المفقودة،LSP، MCP وagent skills، لجعل تجربة المطور (DX) أكثر سلاسة للذكاء الاصطناعي وكلاء.

    استخدم الأتمتة للترجمة في مسار CI/CD الخاص بك باستخدام LLM من اختيارك على حساب مزود الذكاء الاصطناعي الخاص بك. يقدم Intlayer أيضًا مترجمًا لأتمتة استخراج المحتوى، بالإضافة إلى منصة ويب للمساعدة في الترجمة في الخلفية.

    يمكن أن يؤدي ربط ملفات JSON الضخمة بالمكونات إلى حدوث مشكلات في الأداء والتفاعل. يعمل Intlayer على تحسين تحميل المحتوى الخاص بك في وقت الإنشاء.

    أكثر من مجرد حل i18n، يوفر Intlayer [محررًا مرئيًا] مستضافًا ذاتيًا](/ar/doc/concept/editor) وكامل CMS لمساعدتك في إدارة المحتوى متعدد اللغات في الوقت الفعلي، مما يجعل التعاون مع المترجمين ومؤلفي النصوص وأعضاء الفريق الآخرين سلسًا. يمكن تخزين المحتوى محليًا و/أو عن بعد.

    دليل خطوة بخطوة لإعداد Intlayer في تطبيق Vanilla JS

    1. تثبيت التبعيات

      قم بتثبيت الحزم اللازمة باستخدام npm:

      bash
      # إنشاء حزمة مستقلة من intlayer و vanilla-intlayer
# سيتم استيراد هذا الملف في ملف HTML الخاص بك
npx intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# تهيئة intlayer مع ملف التكوين
npx intlayer init --no-gitignore

# بناء القواميس
npx intlayer build

      • intlayer الحزمة الأساسية التي توفر أدوات التدويل لإدارة التكوين والترجمة والتصريح عن المحتوى والتحويل والبرمجة النصية وأوامر CLI.

      • vanilla-intlayer الحزمة التي تدمج Intlayer مع تطبيقات JavaScript / TypeScript البحتة. توفر كائناً منفرداً للنشر/الاشتراك (IntlayerClient) ومساعدين يعتمدون على الاستدعاءات (useIntlayer, useLocale, إلخ) بحيث يمكن لأي جزء من تطبيقك التفاعل مع تغييرات اللغة دون الاعتماد على إطار عمل واجهة مستخدم.

      ينتج تصدير الربط (bundling) من واجهة سطر أوامر intlayer standalone بناءً محسّناً من خلال تقليم الشجرة (tree-shaking) للحزم غير المستخدمة، واللغات، والمنطق غير الأساسي (مثل عمليات إعادة التوجيه أو البوادئ) الخاصة بتكوينك.

    2. تكوين مشروعك

      البنية

      في هذه البنية، توفر نواة intlayer واجهات برمجة تطبيقات JavaScript للإعلان عن القواميس واستهلاكها في بيئات JavaScript أو TypeScript القياسية دون إطار عمل للواجهة الأمامية.

      bash
      .
├── src
│   ├── app.content.mjs
│   └── main.js
├── index.html
├── intlayer.config.mjs
└── package.json

      التكوين

      قم بإنشاء ملف تكوين لتكوين لغات تطبيقك:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // لغاتك الأخرى
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      من خلال ملف التكوين هذا، يمكنك إعداد عناوين URL الموطنة، وإعادة توجيه البرامج الوسيطة، وأسماء ملفات تعريف الارتباط، وموقع وامتداد تصريحات المحتوى الخاصة بك، وتعطيل سجلات Intlayer في وحدة التحكم، والمزيد. للحصول على قائمة كاملة بالمعلمات المتاحة، راجع وثائق التكوين.

    3. استيراد الحزمة في HTML الخاص بك

      بمجرد إنشاء حزمة intlayer.js ، يمكنك استيرادها في ملف HTML الخاص بك:

      index.html
      <!DOCTYPE html>
<html lang="ar" dir="rtl">
  <head>
    <meta charset="UTF-8" />

    <!-- استيراد الحزمة -->
    <script src="./intlayer.js" defer></script>
    <!-- استيراد البرنامج النصي الرئيسي الخاص بك -->
    <script src="./src/main.js" defer></script>
  </head>
  <body>
    <h1 id="title"></h1>
    <p class="read-the-docs"></p>
  </body>
</html>

      تكشف الحزمة عن Intlayer و VanillaIntlayer ككائنات عالمية على window.

    4. تهيئة Intlayer في نقطة الدخول الخاصة بك

      في ملف src/main.js ، قم باستدعاء installIntlayer() قبل عرض أي محتوى بحيث يكون الكائن المنفرد للغة العالمية جاهزًا.

      src/main.js
      const { installIntlayer } = window.VanillaIntlayer;

// يجب استدعاؤه قبل عرض أي محتوى i18n.
installIntlayer();

      إذا كنت تريد أيضًا استخدام عرض markdown ، فقم باستدعاء installIntlayerMarkdown():

      src/main.js
      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

    5. التصريح عن المحتوى الخاص بك

      قم بإنشاء وإدارة تصريحات المحتوى الخاصة بك لتخزين الترجمات:

      src/app.content.ts
      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Haga clic en el logotipo de Vite para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

      يمكن تعريف تصريحات المحتوى الخاصة بك في أي مكان في تطبيقك طالما تم تضمينها في دليل contentDir (افتراضيًا ، ./src). وتطابق امتداد ملف تصريح المحتوى (افتراضيًا ، .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

      لمزيد من التفاصيل ، راجع وثائق تصريح المحتوى.

    6. استخدام Intlayer في JavaScript الخاص بك

      يوفر كائن window.VanillaIntlayer مساعدين لواجهة البرمجة: useIntlayer(key, locale?) يعيد المحتوى المترجم لمفتاح معين.

      src/main.js
      const { installIntlayer, useIntlayer } = window.VanillaIntlayer;

installIntlayer();

// الحصول على المحتوى الأولي للغة الحالية.
// قم بتسلسل .onChange() ليتم إخطارك كلما تغيرت اللغة.
const content = useIntlayer("app").onChange((newContent) => {
  // إعادة عرض أو تعديل عقد DOM المتأثرة فقط
  document.querySelector("h1").textContent = String(newContent.title);
  document.querySelector(".read-the-docs").textContent = String(
    newContent.readTheDocs
  );
});

// العرض الأولي
document.querySelector("h1").textContent = String(content.title);
document.querySelector(".read-the-docs").textContent = String(
  content.readTheDocs
);

      قم بالوصول إلى القيم النهائية كسلاسل من خلال تغليفها في String() ، مما يستدعي طريقة toString() للعقدة ويعيد النص المترجم.

      عندما تحتاج إلى القيمة لسمة HTML أصلية (مثل alt و aria-label) ، استخدم .value مباشرة:

      javascript
      img.alt = content.viteLogoLabel.value;

    7. تغيير لغة المحتوى الخاص بك

      اختياري

      لتغيير لغة المحتوى الخاص بك ، استخدم وظيفة setLocale التي كشفت عنها useLocale.

      src/locale-switcher.js
      const { getLocaleName } = window.Intlayer;
const { useLocale } = window.VanillaIntlayer;

export function setupLocaleSwitcher(container) {
  const { locale, availableLocales, setLocale, subscribe } = useLocale();

  const select = document.createElement("select");
  select.setAttribute("aria-label", "اللغة");

  const render = (currentLocale) => {
    select.innerHTML = availableLocales
      .map(
        (loc) =>
          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
            ${getLocaleName(loc)}
          </option>`
      )
      .join("");
  };

  render(locale);
  container.appendChild(select);

  select.addEventListener("change", () => setLocale(select.value));

  // الحفاظ على مزامنة القائمة المنسدلة عند تغير اللغة من مكان آخر
  return subscribe((newLocale) => render(newLocale));
}

    8. تبديل سمات لغة HTML والاتجاه

      اختياري

      قم بتحديث سمات lang و dir لعلامة <html> لمطابقة اللغة الحالية لتسهيل الوصول وتحسين محركات البحث.

      src/main.js
      const { getHTMLTextDir } = window.Intlayer;
const { installIntlayer, useLocale } = window.VanillaIntlayer;

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    9. تحميل القواميس بكسل لكل لغة

      اختياري

      إذا كنت ترغب في تحميل القواميس بكسل (lazy-load) لكل لغة ، يمكنك استخدام useDictionaryDynamic. هذا مفيد إذا كنت لا تريد حزم جميع الترجمات في ملف intlayer.js الأولي.

      src/app.js
      const { installIntlayer, useDictionaryDynamic } = window.VanillaIntlayer;

installIntlayer();

const unsubscribe = useDictionaryDynamic(
  {
    en: () => import("../.intlayer/dictionaries/en/app.mjs"),
    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
    es: () => import("../.intlayer/dictionaries/es/app.mjs"),
  },
  "app"
).onChange((content) => {
  document.querySelector("h1").textContent = String(content.title);
});
      ملاحظة: يتطلب useDictionaryDynamic توفر القواميس كملفات ESM منفصلة. يتم استخدام هذا النهج عادةً إذا كان لديك خادم ويب يقدم القواميس.

    تكوين TypeScript

    تأكد من أن تكوين TypeScript الخاص بك يتضمن الأنواع التي تم إنشاؤها تلقائيًا.

    tsconfig.json
    {
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

    امتداد VS Code

    لتحسين تجربة التطوير الخاصة بك مع Intlayer ، يمكنك تثبيت امتداد Intlayer VS Code الرسمي.

    التثبيت من VS Code Marketplace

    يوفر هذا الامتداد:

    • الإكمال التلقائي لمفاتيح الترجمة.
    • اكتشاف الأخطاء في الوقت الفعلي للترجمات المفقودة.
    • معاينات مضمنة للمحتوى المترجم.
    • إجراءات سريعة لإنشاء وتحديث الترجمات بسهولة.

    لمزيد من التفاصيل حول كيفية استخدام الامتداد ، راجع وثائق امتداد Intlayer VS Code.

    اذهب أبعد من ذلك

    للذهاب إلى أبعد من ذلك ، يمكنك تنفيذ المحرر المرئي أو استضافة محتواك خارجيًا باستخدام CMS.

    الأسئلة الشائعة

    نعم. هذا الدليل مخصص تحديدًا لهذه الحالة. تقوم بتضمين حزمة vanilla-intlayer مباشرة في HTML، وتهيئتها، وقراءة المحتوى عبر useIntlayer أو getIntlayer.

    أقل بكثير من الكتالوجات التقليدية، لأن الصفحة لا تُحمل أبدًا لغة لا تعرضها. يتم تسليم المحتوى بتنسيقات محسنة. انظر تحسين الحزم.

    إلى حد كبير نعم. اتبع دليل ترحيل i18next.

    نعم. تحافظ مكونة مزامنة JSON على ملفات /messages/{locale}/{namespace}.json الخاصة بك كمصدر الحقيقة وتُنشئ قواميس Intlayer منها، في كلا الاتجاهين. وتقوم مكونة مزامنة PO بنفس الشيء لكتالوجات gettext، وتسمح لك الملفات المقسمة حسب اللغة بتقسيم المحتوى حسب اللغة بدلاً من تجميع كل اللغات في ملف واحد.

    لا. قم بتشغيل npx intlayer extract وسيقرأ Intlayer ملفات المصدر الخاصة بك، ويسحب السلاسل النصية الموجهة للمستخدم ويكتب ملف .content بجانب كل منها، بحيث تراجع diff بدلاً من نسخ السلاسل إلى كتالوج يدويًا. راجع أمر extract.

    لأتمتة كاملة، يقوم Intlayer Compiler بالشيء نفسه في وقت البناء وينشئ القواميس عند كل تغيير.

    خمس أدوات، كلها اختيارية:

    • امتداد VS Code: الانتقال من مفتاح useIntlayer إلى ملف المحتوى المصرح به، استخراج المحتوى من المكون، وتشغيل build و fill و test و push و pull من لوحة الأوامر أو علامة تبويب Intlayer.
    • خادم LSP: نفس التجربة في أي محرر يدعم LSP، مع الانتقال إلى التعريف وعروض القيمة المترجمة عند التمرير والإكمال التلقائي للمفاتيح. يدعم أيضًا استدعاءات i18next و react-i18next و next-intl و use-intl.
    • خادم MCP: يكشف وثائق Intlayer و CLI إلى Cursor و VS Code و Claude Desktop و Claude Code و ChatGPT.
    • Agent skills: مهارات مخصصة مثل intlayer-config و intlayer-cli و intlayer-content.
    • ESLint plugin: قاعدة no-raw-text ترصد النصوص المكتوبة مباشرة بدون تدويل.
    Vite و Vanilla JSVite و Lit