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

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

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

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

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

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

1. 1

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer astro-intlayer
   

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

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

2. 2

   تهيئة مشروعك

   البنية

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── LocaleSwitcher.astro      # Locale switcher component
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page (rest param also serves the default locale)
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() integration
   ├── 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,
         // لغاتك الأخرى
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

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

3. 3

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

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

   astro.config.ts

   نسخ المحتوى

   نسخ الكود

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

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

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

4. 4

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

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

   src/app.content.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         ar: "مرحبا بالعالم",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

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

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

5. 5

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

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

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

   يجب عليك أيضاً إضافة بيانات تعريف SEO مثل hreflang والروابط الأساسية (canonical) إلى كل صفحة وتضمين محوّل لغات للسماح للمستخدمين بتغيير اللغة.

   src/pages/index.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // اللغة المحددة بواسطة الوسيط البرمجي (مثال: /ar/about -> 'ar')
   const { locale } = useLocale();
   
   // محتوى قاموس 'app' لتلك اللغة
   const { title } = useIntlayer("app");
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- Canonical link: Tells search engines which is the primary version of this page -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Tell Google about all localized versions -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Fallback for users in unmatched languages -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <header>
         <LocaleSwitcher />
       </header>
       <main>
         <h1>{title}</h1>
       </main>
     </body>
   </html>
   

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

6. 6

   التوجيه المترجم

   أنشئ أجزاء مسار ديناميكية لخدمة الصفحات المترجمة (مثل src/pages/[locale]/index.astro):

   src/pages/[locale]/index.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import { getIntlayer } from "intlayer";
   
   const { title } = getIntlayer('app');
   ---
   
   <h1>{title}</h1>
   

   يضيف تكامل Astro وسيط Vite الذي يساعد في التوجيه الحساس للغة وتعريفات البيئة أثناء التطوير. يمكنك أيضًا إنشاء روابط عبر اللغات باستخدام منطقك الخاص أو أدوات intlayer مثل getLocalizedUrl.

7. 7

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

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

   src/components/LocaleSwitcher.astro

   نسخ المحتوى

   نسخ الكود

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

   ---
   import { useLocale } from "astro-intlayer";
   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   
   const { locale, availableLocales } = useLocale();
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav aria-label="Languages">
     <ul>
       {
         availableLocales.map((localeItem) => (
           <li key={localeItem} class="p-1">
             <a
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               data-locale={localeItem}
               aria-current={localeItem === locale ? "page" : undefined}
             >
               {getLocaleName(localeItem)}
             </a>
           </li>
         ))
       }
     </ul>
   </nav>
   
   <script>
     // في المتصفح، يحل نفس الاستيراد إلى تنفيذ العميل
     import { useLocale } from "astro-intlayer";
     import { getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // يحفظ الاختيار في ملف تعريف ارتباط اللغة، ثم ينتقل إلى عنوان URL المترجم
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (event) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         event.preventDefault();
         setLocale(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     ul {
       display: flex;
       list-style: none;
       padding: 0;
       margin: 0;
       gap: 0.5rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   ملاحظة حول الاستمرارية: يحفظ setLocale من useLocale من جانب العميل تفضيل لغة المستخدم في ملف تعريف ارتباط. يتيح ذلك لـ Intlayer تذكر الاختيار وإعادة توجيه المستخدم تلقائياً إلى لغته المفضلة في الزيارات المستقبلية: تتم إعادة توجيه الصفحات المعروضة عند الطلب (باستخدام محول مع output: 'server' أو prerender = false) بواسطة وسيط Intlayer البرمجي قبل إرسال أي HTML، بينما تتم إعادة توجيه الصفحات المعروضة مسبقاً، والتي تُقدم كملفات ثابتة، بواسطة سكريبت صغير يحقنه التكامل في كل صفحة. عيّن routing.enableProxy إلى false لإيقاف تشغيل كليهما. في astro dev، يتم تجاهل ملف تعريف الارتباط كمصدر لإعادة التوجيه ما لم يتم تعيين routing.enableProxy إلى true، حتى لا يختطف ملف تعريف ارتباط قديم الصفحات التي تعمل عليها.

   التوافق المتبادل بين الخادم والعميل: يحل astro-intlayer إلى خطافات الخادم في الواجهة الأمامية (بقراءة Astro.locals) وإلى خطافات العميل لـ vanilla-intlayer في كتل <script> والجزر (islands)، بنفس الأسماء وهيكل المحتوى. يعمل setLocale و onChange على العميل فقط، استدعِ installIntlayer() هناك مرة واحدة لتهيئة مخزن العميل. يكشف astro-intlayer/client نقطة إدخال العميل بشكل صريح.

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. 9

   استمر في استخدام إطارات العمل المفضلة لديك

   استمر في بناء تطبيقك باستخدام إطار العمل الذي تختاره.

   • Intlayer + React: Intlayer مع React
   • Intlayer + Vue: Intlayer مع Vue
   • Intlayer + Svelte: Intlayer مع Svelte
   • Intlayer + Solid: Intlayer مع Solid
   • Intlayer + Preact: Intlayer مع Preact
   • Intlayer + Lit: Intlayer مع Lit
10. 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، مما يجعل برمجتك أكثر قوة.

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

{
  // ... تكوين TypeScript الحالي الخاص بك
  "include": [
    // ... تكوين TypeScript الحالي الخاص بك
    ".intlayer/**/*.ts", // تضمين الأنواع المولدة تلقائيًا
  ],
}

تكوين Git

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

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

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

إضافة VS Code

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

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

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

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

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

تعمق أكثر

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

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