ترجمة موقع Vanilla JS الخاص بك باستخدام Intlayer

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

لماذا تختار Intlayer مقارنة بالبدائل الأخرى؟

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

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

1. 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. 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. 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. 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. 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. 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. 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. 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. 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 الخاص بك يتضمن الأنواع التي تم إنشاؤها تلقائيًا.

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

امتداد VS Code

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

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

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

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

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

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

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