تلقي إشعارات حول الإصدارات القادمة من Intlayer
    إنشاء:2024-03-07آخر تحديث:2025-10-03

    البدء في التدويل (i18n) مع Intlayer و Astro

    راجع قالب التطبيق على GitHub.

    ما هو Intlayer؟

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

    مع Intlayer، يمكنك:

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

    دليل خطوة بخطوة لإعداد Intlayer في Astro

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

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

    npm install intlayer astro-intlayer# Optional: add React island supportnpm install react react-dom react-intlayer @astrojs/react

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

    • astro-intlayer يتضمن مكون التكامل الخاص بـ Astro لدمج Intlayer مع مجمّع Vite، بالإضافة إلى وسيط برمجي لاكتشاف اللغة المفضلة للمستخدم، وإدارة ملفات تعريف الارتباط، والتعامل مع إعادة توجيه عناوين URL.

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

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

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

    أضف مكون intlayer الإضافي إلى تكوينك.

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

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

    الخطوة 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",    }),  },} satisfies Dictionary;export default appContent;

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

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

    الخطوة 5: استخدام المحتوى الخاص بك في Astro

    يمكنك استهلاك القواميس مباشرة في ملفات .astro باستخدام الأدوات الأساسية التي تصدرها intlayer.

    src/pages/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";import appContent from "../app.content";const { title } = getIntlayer('app');---<html lang="en">  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <title>{title}</title>  </head>  <body>    <h1>{title}</h1>  </body></html>

    الخطوة 6: التوجيه المحلي

    قم بإنشاء جزء مسار ديناميكي لخدمة الصفحات المحلية، على سبيل المثال src/pages/[locale]/index.astro:

    src/pages/[locale]/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>

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

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

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

    تكوين TypeScript

    يستخدم Intlayer تعزيز الوحدات (module augmentation) للاستفادة من TypeScript وجعل قاعدة الشيفرة الخاصة بك أقوى.

    Autocompletion

    Translation error

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

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

    تكوين Git

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

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

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

    امتداد VS Code

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

    التثبيت من سوق VS Code

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

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

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

    التقدم أكثر

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

    تاريخ الوثيقة

    الإصدار التاريخ التغييرات
    6.2.0 2025-10-03 تحديث لتكامل Astro، الإعدادات، الاستخدام
    Tanstack Start
    React CRA
    تلقي إشعارات حول الإصدارات القادمة من Intlayer