ترجمة موقع الويب الخاص بك المبني بـ Vite و Lit باستخدام Intlayer | التدويل (i18n)

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

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

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

انظر إلى نموذج التطبيق على GitHub.

دليل خطوة بخطوة لإعداد Intlayer في تطبيق Vite و Lit

1. 1

   تثبيت التبعيات

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

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   npx intlayer init --interactive
   

   علامة --interactive اختيارية. استخدم intlayer-cli init إذا كنت وكيل ذكاء اصطناعي.

   سيقوم هذا الأمر باكتشاف بيئتك وتثبيت الحزم المطلوبة. على سبيل المثال:

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   npm install intlayer lit-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • lit-intlayer الحزمة التي تدمج Intlayer مع تطبيقات Lit. توفر خطافات (hooks) تعتمد على ReactiveController مثل (useIntlayer و useLocale وما إلى ذلك) بحيث يتم إعادة صيرورة عناصر Lit تلقائيًا عند تغيير اللغة.

   • vite-intlayer تتضمن إضافة Vite لدمج Intlayer مع أداة حزم Vite، كمال توفر برمجيات وسيطة لاكتشاف اللغة المفضلة للمستخدم، وإدارة ملفات تعريف الارتباط، والتعامل مع إعادة توجيه عناوين URL.

2. 2

   تكوين مشروعك

   البنية

   في هذه البنية، يوفر lit-intlayer تكاملات العناصر المخصصة ووحدات التحكم التفاعلية لإدارة الترجمات داخل Web Components. توجد إعلانات المحتوى في src/ بجانب العناصر.

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   .
   ├── src
   │   ├── app.content.ts
   │   ├── index.css
   │   ├── locale-switcher.ts
   │   ├── main.ts
   │   └── my-element.ts                 # Main Lit element
   ├── index.html
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   التكوين

   أنشئ ملف تكوين لتكوين لغات تطبيقك:

   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

   دمج Intlayer في تكوين Vite الخاص بك

   أضف إضافة intlayer في التكوين الخاص بك.

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

   تُستخدم إضافة intlayer() لـ Vite لدمج Intlayer مع Vite. تضمن بناء ملفات إعلان المحتوى ومراقبتها في وضع التطوير. كما تحدد متغيرات بيئة Intlayer داخل تطبيق Vite. بالإضافة إلى ذلك، توفر أسماء مستعارة لتحسين الأداء.

4. 4

   تشغيل Intlayer في نقطة الإدخال الخاصة بك

   استدعِ installIntlayer() قبل تسجيل أي عناصر مخصصة بحيث يكون الكائن المنفرد للغة العالمية جاهزًا عند اتصال العنصر الأول.

   src/main.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { installIntlayer } from "lit-intlayer";
   
   // يجب استدعاؤه قبل توصيل أي عنصر LitElement بـ DOM.
   installIntlayer();
   
   // استيراد وتسجيل العناصر المخصصة الخاصة بك.
   import "./my-element.js";
   

   إذا كنت تستخدم أيضًا إعلانات محتوى md() (Markdown)، فقم بتثبيت عارض markdown أيضًا:

   src/main.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";
   
   installIntlayer();
   installIntlayerMarkdown();
   
   import "./my-element.js";
   

5. 5

   إعلان المحتوى الخاص بك

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

   src/app.content.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Lit",
   
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       litLogo: t({
         en: "Lit logo",
         fr: "Logo Lit",
         es: "Logo Lit",
       }),
   
       count: t({
         en: "count is {{count}}",
         fr: "le compte est {{count}}",
         es: "el recuento es {{count}}",
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Lit logos to learn more",
         fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Lit 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 في LitElement الخاص بك

   استخدم useIntlayer داخل LitElement. يقوم بإرجاع وكيل ReactiveController يقوم تلقائيًا بإعادة الصيرورة كلما تغيرت اللغة النشطة - لا يلزم إعداد إضافي.

   src/my-element.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { LitElement, html } from "lit";
   import { customElement, property } from "lit/decorators.js";
   import { useIntlayer } from "lit-intlayer";
   
   @customElement("my-element")
   export class MyElement extends LitElement {
     @property({ type: Number })
     count = 0;
   
     // يقوم useIntlayer بتسجيل نفسه كـ ReactiveController.
     // يتم إعادة صيرورة العنصر تلقائيًا عند تغيير اللغة.
     private content = useIntlayer(this, "app");
   
     override render() {
       const { content } = this;
   
       return html`
         <h1>${content.title}</h1>
   
         <img src="/vite.svg" alt=${content.viteLogo.value} />
         <img src="/lit.svg" alt=${content.litLogo.value} />
   
         <button @click=${() => this.count++}>
           ${content.count({ count: this.count })}
         </button>
   
         <p>${content.readTheDocs}</p>
       `;
     }
   }
   

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

   typescript

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   html`<img alt=${content.viteLogo.value} />`;
   html`<img alt=${content.viteLogo.toString()} />`;
   html`<img alt=${String(content.viteLogo)} />`;
   

7. 7

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

   اختياري

   لتغيير لغة المحتوى الخاص بك، استخدم أسلوب setLocale الذي يوفره متحكم useLocale.

   src/locale-switcher.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "lit-intlayer";
   
   @customElement("locale-switcher")
   export class LocaleSwitcher extends LitElement {
     private locale = useLocale(this);
   
     private _onChange(e: Event) {
       const select = e.target as HTMLSelectElement;
       this.locale.setLocale(select.value as any);
     }
   
     override render() {
       return html`
         <select @change=${this._onChange}>
           ${this.locale.availableLocales.map(
             (loc) => html`
               <option value=${loc} ?selected=${loc === this.locale.locale}>
                 ${getLocaleName(loc)}
               </option>
             `
           )}
         </select>
       `;
     }
   }
   

8. 8

   عرض محتوى Markdown و HTML

   اختياري

   يدعم Intlayer إعلانات محتوى md() و html(). في Lit، يتم حقن المخرجات المجمعة كـ HTML خام عبر توجيه unsafeHTML.

   قم بعرض HTML المجمع في عنصرك:

   src/my-element.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { unsafeHTML } from "lit/directives/unsafe-html.js";
   import { useIntlayer } from "lit-intlayer";
   import { compileMarkdown } from "lit-intlayer/markdown";
   
   @customElement("my-element")
   export class MyElement extends LitElement {
     private content = useIntlayer(this, "app");
   
     override render() {
       return html`
         <div class="edit-note">
           ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}
         </div>
       `;
     }
   }
   

   TIP

   يستدعي String(content.editNote) الدالة toString() على IntlayerNode التي تعيد سلسلة Markdown الخام. مررها إلى compileMarkdown للحصول على سلسلة HTML، ثم قم بالصيرورة باستخدام توجيه unsafeHTML الخاص بـ Lit.

9. 9

   إضافة توجيه محلي (Routing) إلى تطبيقك

   اختياري

   لإنشاء مسارات فريدة لكل لغة (مفيد لـ SEO)، يمكنك استخدام موجه من جانب العميل بجوار أدوات Intlayer المساعدة localeMap / localeFlatMap وإضافة Vite intlayerProxy لاكتشاف اللغة من جانب الخادم.

   أولاً، أضف intlayerProxy إلى تكوين Vite الخاص بك:

   لاحظ أنه لاستخدام intlayerProxy في الإنتاج، تحتاج إلى نقل vite-intlayer من devDependencies إلى dependencies.

   منذ Intlayer v9، يتم تجميع intlayerProxy() مباشرة في المكون الإضافي intlayer() وتفعيله افتراضياً من خلال خيار routing.enableProxy (true بشكل افتراضي). تسجيله بشكل منفصل كما هو موضح أدناه أصبح اختيارياً الآن — يتم الاحتفاظ به للتوافقية العكسية والإعدادات التي تحتاج إلى التحكم في ترتيب المكونات الإضافية. عيّن routing.enableProxy: false للتجاوز. انظر إلى ملاحظات إصدار v9.

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [intlayer(), intlayerProxy()],
   });
   

10. 10

    تغيير عنوان URL عند تغيير اللغة

    اختياري

    لتحديث عنوان URL للمتصفح عند تغيير اللغة، استخدم useRewriteURL بجانب مبدل اللغة:

    src/locale-switcher.ts

    نسخ المحتوى

    نسخ الكود

    نسخ الكود إلى الحافظة

    import { LitElement, html } from "lit";
    import { customElement } from "lit/decorators.js";
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale, useRewriteURL } from "lit-intlayer";
    
    @customElement("locale-switcher")
    export class LocaleSwitcher extends LitElement {
      private locale = useLocale(this);
    
      // يعيد كتابة عنوان URL الحالي تلقائيًا عند تغيير اللغة.
      private _rewriteURL = useRewriteURL(this);
    
      private _onChange(e: Event) {
        const select = e.target as HTMLSelectElement;
        this.locale.setLocale(select.value as any);
      }
    
      override render() {
        return html`
          <select @change=${this._onChange}>
            ${this.locale.availableLocales.map(
              (loc) => html`
                <option value=${loc} ?selected=${loc === this.locale.locale}>
                  ${getLocaleName(loc)}
                </option>
              `
            )}
          </select>
        `;
      }
    }
    

11. 11

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

    اختياري

    قم بتحديث سمات lang و dir لعلامة <html> لتتوافق مع اللغة الحالية من أجل إمكانية الوصول و SEO.

    src/my-element.ts

    نسخ المحتوى

    نسخ الكود

    نسخ الكود إلى الحافظة

    import { LitElement, html } from "lit";
    import { customElement } from "lit/decorators.js";
    import { getHTMLTextDir } from "intlayer";
    import { useLocale } from "lit-intlayer";
    
    @customElement("my-element")
    export class MyElement extends LitElement {
      private locale = useLocale(this, {
        onLocaleChange: (loc) => {
          document.documentElement.lang = loc;
          document.documentElement.dir = getHTMLTextDir(loc);
        },
      });
    
      override render() {
        return html`<!-- محتواك -->`;
      }
    }
    

12. 12

    استخراج محتوى مكوناتك

    اختياري

    إذا كان لديك كود برمجي موجود، فقد يكون تحويل آلاف الملفات مستهلكًا للوقت.

    لتسهيل هذه العملية، تقترح Intlayer استخدام مجمع (compiler) / مستخرج (extractor) لتحويل مكوناتك واستخراج المحتوى.

    لإعداده، يمكنك إضافة قسم compiler في ملف intlayer.config.ts الخاص بك:

    intlayer.config.ts

    نسخ المحتوى

    نسخ الكود

    نسخ الكود إلى الحافظة

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... بقية التكوين الخاص بك
      compiler: {
        /**
         * يشير إلى ما إذا كان يجب تمكين المجمع.
         */
        enabled: true,
    
        /**
         * يحدد مسار ملفات المخرجات
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * يشير إلى ما إذا كان يجب حفظ المكونات بعد تحويلها.
         * بهذه الطريقة، يمكن تشغيل المجمع مرة واحدة فقط لتحويل التطبيق، ثم يمكن إزالته.
         */
        saveComponents: false,
    
        /**
         * بادئة مفتاح القاموس
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

(اختياري) خريطة الموقع و robots.txt (توليد وقت البناء)

يوفّر Intlayer الدالتين generateSitemap وgetMultilingualUrls لتنسيق مخرجات جاهزة للزحّافات (sitemap.xml متعدد اللغات وrobots.txt) وكتابتها تلقائياً إلى public/. عادةً تشغّل سكربت Node صغير قبل Vite (مثلاً خطافات npm predev / prebuild).

خريطة الموقع

يولّد مولّد خرائط المواقع إعدادات اللغات ويضيف البيانات الوصفية المناسبة.

تدعم الخريطة مساحة الاسم xhtml:link (hreflang). بدلاً من قائمة عناوين مسطحة، يربط Intlayer بين جميع النسخ اللغوية لكل صفحة في الاتجاهين (مثل /about و/fr/about أو /about?lang=fr وفقًا لوضع التوجيه).

Robots.txt

استخدم getMultilingualUrls لتشمل قواعد Disallow كل المتغيرات المحلية للمسارات الحساسة.

1. أضف generate-seo.mjs في جذر المشروع

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

يجب تثبيت حزمة intlayer. عيّن SITE_URL في بيئة الإنتاج (مثلاً في CI).

يُفضّل generate-seo.mjs لـ ESM في Node. إن استخدمت generate-seo.js ففعّل "type": "module" في package.json أو ESM بطريقة أخرى.

2. شغّل السكربت قبل Vite

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

عدّل الأوامر إن كنت تستخدم pnpm أو yarn. يمكن استدعاء السكربت من CI أيضاً.

تكوين TypeScript

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

{
  "compilerOptions": {
    // ...
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

يتطلب Lit تفعيل experimentalDecorators و useDefineForClassFields: false لدعم المزخرفات (decorators).

تكوين Git

يوصى بتجاهل الملفات التي تم إنشاؤها بواسطة Intlayer. يتيح لك هذا تجنب دفعها إلى مستودع Git الخاص بك.

للقيام بذلك، يمكنك إضافة التعليمات التالية إلى ملف .gitignore الخاص بك:

# تجاهل الملفات التي تم إنشاؤها بواسطة Intlayer
.intlayer

إضافة VS Code

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

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

توفر هذه الإضافة:

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

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

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

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

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