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

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

ما هو Intlayer؟

Intlayer هي مكتبة تدويل (i18n) مبتكرة ومفتوحة المصدر مصممة لتبسيط دعم اللغات المتعددة في تطبيقات الويب الحديثة.

باستخدام Intlayer، يمكنك:

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

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

الخطوة 1: تثبيت التبعيات

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

npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

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

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

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

الخطوة 2: تكوين مشروعك

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

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: دمج Intlayer في تكوين Vite الخاص بك

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

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});

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

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

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

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

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

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

الخطوة 5: إعلان المحتوى الخاص بك

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

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}).

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

الخطوة 6: استخدام Intlayer في LitElement الخاص بك

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

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: تغيير لغة المحتوى الخاص بك

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

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: عرض محتوى Markdown و HTML

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

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

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: إضافة توجيه محلي (Routing) إلى تطبيقك

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

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

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

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer(), intlayerProxy()],
});

(اختياري) الخطوة 10: تغيير عنوان URL عند تغيير اللغة

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

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: تبديل سمات اللغة والاتجاه في HTML

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

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: استخراج محتوى مكوناتك

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

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

لإعداده، يمكنك إضافة قسم compiler في ملف 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).