ترجمة موقع Astro + Lit الخاص بك باستخدام Intlayer

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

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

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

دليل خطوة بخطوة لتهيئة Intlayer في Astro + Lit

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

1. 1

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

   قم بتثبيت الحزم اللازمة باستخدام مدير الحزم المفضل لديك:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer astro-intlayer lit lit-intlayer @astrojs/lit
   

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

   • astro-intlayer يتضمن ملحق تكامل Astro لدمج Intlayer مع حازم Vite، ووسيطاً برمجياً يحدد لغة كل طلب في Astro.locals.intlayer، وخطافات useIntlayer / useDictionary / useLocale. يحل نفس مسار الاستيراد إلى تنفيذ الخادم في واجهة .astro وإلى تنفيذ العميل (المدعوم بـ vanilla-intlayer) في كتل <script>.

   • lit حزمة Lit الأساسية لبناء مكونات ويب (Web Components) سريعة وخفيفة.

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

   • @astrojs/lit إضافة Astro الرسمية التي تتيح استخدام عناصر Lit المخصصة (custom elements) داخل صفحات Astro.

2. 2

   تهيئة مشروعك

   البنية

   في هذه البنية، يقوم تكامل intlayer() المسجل في astro.config.ts ببناء القواميس الخاصة بك وإضافة برمجية وسيطة (middleware) تحدد لغة كل طلب وتوفرها عبر Astro.locals.intlayer. تتواجد الصفحات تحت مقطع src/pages/[...locale]/، بحيث يتم تقديم اللغة الافتراضية بدون بادئة ويحصل كل خيار لغة آخر على عنوان URL مخصص له. تقرأ ملفات .astro المحتوى باستخدام خطافات useIntlayer / useLocale الخاصة بـ astro-intlayer للعرض على جانب الخادم، وتتلقى جزيرة Lit (src/components/lit/LitDemo.ts) اللغة المكتشفة من الخادم كخاصية (prop) وتمررها إلى lit-intlayer للجزء التفاعلي. وتوضع تصريحات المحتوى جنباً إلى جنب مع مكوناتك في src/.

   bash

   نسخ المحتوى

   نسخ الكود

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

   .
   ├── src
   │   ├── components
   │   │   └── lit
   │   │       ├── app.content.ts        # App content declaration
   │   │       └── LitDemo.ts            # Lit custom element (content + locale switcher)
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page mounting the custom element
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() and lit() integrations
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   التكوين

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

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         Locales.ARABIC,
         // لغاتك الأخرى
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

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

   توثيق التهيئة
3. 3

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

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

   astro.config.ts

   نسخ المحتوى

   نسخ الكود

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

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import lit from "@astrojs/lit";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer(), lit()],
   });
   

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

   يتيح تكامل lit() استخدام العناصر المخصصة (custom elements) لـ Lit داخل صفحات Astro.

4. 4

   تعريف المحتوى الخاص بك

   أنشئ وأدِر تعريفات المحتوى لتخزين الترجمات:

   src/components/lit/app.content.ts

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   
   const litDemoContent = {
     key: "lit-demo",
     content: {
       greeting: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         ar: "مرحبا بالعالم",
       }),
       description: t({
         en: "Welcome to my multilingual Astro + Lit site.",
         fr: "Bienvenue sur mon site Astro + Lit multilingue.",
         es: "Bienvenido a mi sitio Astro + Lit multilingüe.",
         ar: "مرحبا بكم في موقع Astro + Lit متعدد اللغات الخاص بي.",
       }),
     },
   } satisfies Dictionary;
   
   export default litDemoContent;
   

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

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

   توثيق تعريف المحتوى
5. 5

   استخدام المحتوى في Astro

   استخدم قواميسك في ملفات .astro باستخدام الخطافات المصدرة بواسطة astro-intlayer. تشترك هذه الخطافات في نفس تواقيع روابط إطار العمل: يُرجع useIntlayer("key") محتوى القاموس ويُرجع useLocale() اللغة الحالية، دون الحاجة إلى تمرير أي وسيطات.

   تأتي اللغة من الوسيط البرمجي astro-intlayer، والذي يسجله التكامل تلقائياً قبل src/middleware.ts الخاص بك. يحدد الوسيط اللغة لكل طلب، بدءاً من بادئة عنوان URL، ثم اللغة المحفوظة بواسطة العميل (ملف تعريف الارتباط أو الترويسة)، ثم Accept-Language، ويخزنها في Astro.locals.intlayer. تستخدم الصفحات المعروضة مسبقاً عنوان URL فقط، حيث يتم عرضها مرة واحدة لكل زائر.

   يجب عليك أيضاً إضافة بيانات تعريف SEO مثل hreflang والروابط الأساسية (canonical) إلى كل صفحة. يتم بعد ذلك استيراد عنصر Lit المخصص عبر <script> من جانب العميل ووضعه في النص الأساسي (body).

   src/pages/[...locale]/index.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     getPrefix,
     localeMap,
     defaultLocale,
     getHTMLTextDir,
   } from "intlayer";
   
   export const getStaticPaths = () => {
     return defaultLocale.map((locale) => ({
       params: { locale },
     }));
   };
   
   // اللغة المحددة بواسطة الوسيط البرمجي (مثال: /ar/about -> 'ar')
   const { locale } = useLocale();
   
   // محتوى قاموس 'lit-demo' لتلك اللغة
   const { greeting } = useIntlayer("lit-demo");
   ---
   
   <!doctype html>
   <html lang={locale} dir={locale === 'ar' ? 'rtl' : 'ltr'}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{greeting}</title>
   
       <!-- رابط Canonical -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- روابط Hreflang -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- عنصر Lit مخصص - يستلم اللغة المكتشفة من الخادم كخاصية (property) -->
       <lit-demo locale={locale}></lit-demo>
     </body>
   </html>
   
   <script>
     import "../../components/lit/LitDemo";
   </script>
   

   إذا كنت ترغب في استخدام محتواك في سمة سلسلة (string)، مثل alt و title و href و aria-label وما إلى ذلك، يمكنك استخدام قيمة الدالة، مثل:

   tsx

   نسخ المحتوى

   نسخ الكود

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

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

   يعرض Astro.locals.intlayer أيضاً locale و defaultLocale و availableLocales للوسطاء البرمجيين ونقاط النهاية الخاصة بك. مرر لغة أو محدداً كوسيط ثانٍ (useIntlayer("app", "fr"), useIntlayer("faq", { item: 2 })) لتجاوز لغة الطلب لاستدعاء واحد.

   ملاحظة حول إعداد التوجيه: تعتمد بنية الدليل التي تستخدمها على إعداد middleware.routing في intlayer.config.ts:

   • prefix-no-default (افتراضي): يحافظ على اللغة الافتراضية في الجذر (بدون بادئة) ويضيف بادئات للغات الأخرى. استخدم [...locale] لتغطية جميع الحالات.
   • prefix-all: تحصل جميع الروابط على بادئة لغة. يمكنك استخدام [locale] القياسي إذا كنت لا تحتاج إلى معالجة الجذر بشكل منفصل.
   • search-param أو no-prefix: لا يلزم وجود أدلة لغة. يتم التعامل مع اللغة عبر معلمات الاستعلام أو ملفات تعريف الارتباط.

6. 6

   إنشاء عنصر Lit مخصص

   أنشئ عنصر Lit مخصصًا. استدعِ installIntlayer في connectedCallback باستخدام خاصية locale المحملة من الخادم لتهيئة singleton الترجمة في جانب العميل.

   src/components/lit/LitDemo.ts

   نسخ المحتوى

   نسخ الكود

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

   import { LitElement, html } from "lit";
   import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   class LitDemo extends LitElement {
     static properties = {
       locale: { type: String },
     };
   
     locale: LocalesValues = "en" as LocalesValues;
   
     private _content = useIntlayer(this, "lit-demo");
     private _localeCtrl = useLocale(this, {
       onLocaleChange: (newLocale: LocalesValues) => {
         window.location.href = getLocalizedUrl(
           window.location.pathname,
           newLocale
         );
       },
     });
   
     override connectedCallback() {
       super.connectedCallback();
       // التهيئة باللغة المكتشفة من الخادم
       installIntlayer({ locale: this.locale as any });
     }
   
     override render() {
       const { greeting, description } = this._content;
       const {
         locale: currentLocale,
         availableLocales,
         setLocale,
       } = this._localeCtrl;
   
       return html`
         <div dir=${currentLocale === "ar" ? "rtl" : "ltr"}>
           <h1>${greeting}</h1>
           <p>${description}</p>
           <!-- يتم رندر مبدل اللغة داخل LitElement -->
           <div class="locale-switcher">
             <span class="switcher-label">تغيير اللغة:</span>
             <div class="locale-buttons">
               ${availableLocales.map(
                 (localeItem) => html`
                   <button
                     class="locale-btn ${
                       localeItem === currentLocale ? "active" : ""
                     }"
                     ?disabled=${localeItem === currentLocale}
                     @click=${() => setLocale(localeItem)}
                   >
                     <span class="ls-own-name">${getLocaleName(localeItem)}</span>
                     <span class="ls-current-name"
                       >${getLocaleName(localeItem, currentLocale)}</span
                     >
                     <span class="ls-code">${localeItem.toUpperCase()}</span>
                   </button>
                 `
               )}
             </div>
           </div>
         </div>
       `;
     }
   }
   
   customElements.define("lit-demo", LitDemo);
   

   يتم تمرير خاصية locale من صفحة Astro (اكتشاف الخادم) وتستخدم لتهيئة installIntlayer في connectedCallback ، مما يحدد اللغة الأولية لجميع خطافات ReactiveController داخل العنصر.

   يتم تسجيل useIntlayer كـ ReactiveController. ويطلب تلقائيًا إعادة رندر العنصر عند تغيير اللغة، لذلك لا توجد حاجة لمنطق اشتراك (subscription logic) إضافي.

7. 7

   إضافة مبدل اللغة

   تتوفر وظيفة تغيير اللغة مباشرة داخل طريقة render() للعنصر المخصص لـ Lit (انظر الخطوة 6 أعلاه). وهي تستخدم useLocale من lit-intlayer وتنتقل إلى الرابط المترجم عندما يختار المستخدم لغة جديدة:

   src/components/lit/LitDemo.ts

   نسخ المحتوى

   نسخ الكود

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

   // داخل فئة LitElement ، بعد تهيئة useLocale في الخطوة 6:
   
   private _localeCtrl = useLocale(this, {
     onLocaleChange: (newLocale: LocalesValues) => {
       // الانتقال إلى الرابط المترجم عند تغيير اللغة
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   
   override render() {
     const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;
   
     return html`
       <div class="locale-switcher">
         <span class="switcher-label">تغيير اللغة:</span>
         <div class="locale-buttons">
           ${availableLocales.map(
             (localeItem) => html`
               <button
                 class="locale-btn ${localeItem === currentLocale ? "active" : ""}"
                 ?disabled=${localeItem === currentLocale}
                 @click=${() => setLocale(localeItem)}
               >
                 <span class="ls-own-name">${getLocaleName(localeItem)}</span>
                 <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>
                 <span class="ls-code">${localeItem.toUpperCase()}</span>
               </button>
             `
           )}
         </div>
       </div>
     `;
   }
   

   ملاحظة حول تفاعلية Lit: تقوم useLocale بإرجاع ReactiveController. عند استدعاء setLocale ، يطلب المتحكم تلقائيًا إعادة رندر، مما يؤدي إلى تحديث حالة الزر النشط دون معالجة DOM يدويًا.

   ملاحظة حول الاستمرارية: يضمن استخدام onLocaleChange لإعادة التوجيه عبر window.location.href زيارة الرابط الجديد للغة، مما يسمح لوسيط Intlayer بتعيين كوكيز اللغة وتذكر تفضيلات المستخدم في الزيارات المستقبلية.

8. 8

   خريطة الموقع وRobots.txt

   توفر Intlayer أدوات لإنشاء خريطة موقع مترجمة وملفات robots.txt ديناميكيًا.

   خريطة الموقع (Sitemap)

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

   تدعم خريطة الموقع المُنشأة من قِبل Intlayer مساحة الأسماء xhtml:link (Hreflang XML Extensions). على عكس مولدات خرائط الموقع الافتراضية التي تُدرج عناوين URL الخام فقط، ينشئ Intlayer تلقائياً الروابط ثنائية الاتجاه المطلوبة بين جميع إصدارات الصفحة باللغات المختلفة (على سبيل المثال، /about و /about?lang=fr و /about?lang=es). هذا يضمن أن محركات البحث تفهرس بشكل صحيح وتقدم النسخة الصحيحة من اللغة للجمهور المناسب.

   أنشئ src/pages/sitemap.xml.ts لإنشاء خريطة موقع تتضمن جميع مساراتك المترجمة.

   src/pages/sitemap.xml.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   أنشئ src/pages/robots.txt.ts للتحكم في زحف محركات البحث.

   src/pages/robots.txt.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 15

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

   اختياري

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

   لتسهيل هذه العملية، يقترح Intlayer مترجمًا / مستخرجًا لتحويل مكوناتك واستخراج المحتوى.

   مترجمًا

   مستخرجًا

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

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     // ... Rest of your config
     compiler: {
       /**
        * Indicates if the compiler should be enabled.
        */
       enabled: true,
   
       /**
        * Defines the output files path
        */
       output: ({ fileName, extension }) => `./${fileName}${extension}`,
   
       /**
        * Indicates if the components should be saved after being transformed.
        *
        * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
        *
        * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
        */
       saveComponents: false,
   
       /**
        * Dictionary key prefix
        */
       dictionaryKeyPrefix: "",
     },
   };
   
   export default config;
   

   Extract commandBabel compiler

   قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer extract
   

   قم ببناء تطبيقك لتحويل مكوناتك واستخراج المحتوى

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm run build # Or npm run dev
   

تكوين TypeScript

تستخدم Intlayer تقنية توسيع الوحدات (module augmentation) للاستفادة من TypeScript، مما يجعل برمجتك أكثر قوة. إذا كنت تستخدم صيغة الـ decorators ، فتأكد من تفعيل experimentalDecorators في خيارات المترجم (compiler options).

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

{
  compilerOptions: {
    // ...
    experimentalDecorators: true,
    useDefineForClassFields: false, // مطلوب لدعم decorators في Lit
  },
  include: [
    // ... تكوين TypeScript الحالي الخاص بك
    ".intlayer/**/*.ts", // تضمين الأنواع المولدة تلقائيًا
  ],
}

تكوين Git

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

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

# تجاهل الملفات المولدة بواسطة Intlayer
.intlayer

إضافة VS Code

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

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

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

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

تعمق أكثر

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

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