diff --git a/src/content/docs/ar/astro-courses.mdx b/src/content/docs/ar/astro-courses.mdx new file mode 100644 index 0000000000000..2d0e7f84b4879 --- /dev/null +++ b/src/content/docs/ar/astro-courses.mdx @@ -0,0 +1,50 @@ +--- +title: دورات Astro +sidebar: + label: الدورات +description: تعلم Astro من خلال دورات ودروس تعليمية مميزة خارج هذا العالم! +i18nReady: true +--- +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; + +هل ترغب في البدء بتعلّم Astro من خلال دورة أو دليل تعليمي؟ + +يمكنك تعلم أساسيات Astro عبر [الدليل الرسمي "أنشئ مدونة"](/ar/tutorial/0-introduction/)، أو استكشاف مجموعتنا المختارة من المحتوى التعليمي الموصى به حول Astro. + +## شركاء التعليم + +:::tip[ادعم Astro أثناء التعلّم] +استخدم روابط الشراكة الخاصة بـ Astro للحصول على خصومات من شركائنا التعليميين، وجزء من مشترياتك يُعاد مباشرةً لدعم تطوير مشروع Astro مفتوح المصدر! +::: + +تعلّم Astro من خبراء موثوقين في المنصة، من خلال دروس مرئية، وتمارين تفاعلية، ومشاريع تطبيقية! + + + + + +## موارد التعلم من المجتمع + +تعلم من زملائك المبدعين في مجتمع Astro عبر مجموعات من الأدلة والمقالات والمنشورات المميزة. + + + + + + diff --git a/src/content/docs/ar/concepts/islands.mdx b/src/content/docs/ar/concepts/islands.mdx new file mode 100644 index 0000000000000..b5b429b0c234b --- /dev/null +++ b/src/content/docs/ar/concepts/islands.mdx @@ -0,0 +1,162 @@ +--- +title: بنية الجزر (Islands Architecture) +description: تعرّف على كيفية مساعدة بنية الجزر في Astro في جعل المواقع سريعة الأداء. +i18nReady: true +--- + +import IslandsDiagram from '~/components/IslandsDiagram.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +ساعد إطار **Astro** في ابتكار ونشر نمط جديد من هندسة الواجهات الأمامية يُعرف باسم **بنية الجزر**. +تعمل هذه البنية عن طريق توليد الجزء الأكبر من صفحتك إلى **HTML ثابت وسريع**، مع إضافة جزر صغيرة من **JavaScript** فقط عند الحاجة إلى التفاعل أو التخصيص (مثل شريط صور متحرك مثلًا). +بهذه الطريقة يتم تجنّب تحميل حزم JavaScript ضخمة تبطّئ استجابة المواقع الحديثة المبنية على أطر JavaScript التقليدية. + +## لمحة تاريخية + +تم استخدام مصطلح **«مكوّن الجزيرة»** لأول مرة من قبل مهندسة الواجهات الأمامية في موقع Etsy، [كاتي سايلور ميلر](https://sylormiller.com/) عام 2019. +ثم قام منشئ إطار **Preact**، [جيسون ميلر](https://jasonformat.com/islands-architecture/)، بتوسيع الفكرة وشرحها في مقال بتاريخ 11 أغسطس 2020. + +> الفكرة العامة لبنية "الجزر" بسيطة في ظاهرها: يتم توليد صفحات HTML على الخادم، مع حقن أماكن مخصصة أو مناطق ديناميكية يمكن «ترطيبها» لاحقًا على المتصفح لتتحول إلى وحدات تفاعلية مستقلة تستخدم نفس HTML المولّد من الخادم. +> — جيسون ميلر، منشئ إطار Preact + +يعتمد هذا النمط المعماري على تقنية تُعرف باسم **الترطيب الجزئي** أو **الانتقائي**. + +في المقابل، تقوم معظم أطر الويب المبنية على JavaScript بترطيب وتوليد الموقع بالكامل كتطبيق JavaScript واحد كبير (ويُعرف هذا بـ SPA أو "التطبيق أحادي الصفحة"). +توفر SPAs سهولة وقوة في التطوير، لكنها تعاني من بطء تحميل الصفحات نتيجة اعتمادها الكامل على JavaScript من جهة العميل. + +ورغم أن SPAs لها استخداماتها، بل ويمكن [دمجها داخل صفحة Astro](/ar/guides/migrate-to-astro/from-create-react-app/)، إلا أنها تفتقر إلى القدرة الأصلية على الترطيب الانتقائي، مما يجعلها خيارًا ثقيلًا في معظم مشاريع الويب الحديثة. + +أصبح Astro شائعًا لكونه أول إطار JavaScript رئيسي يقدم الترطيب الانتقائي بشكل مدمج، معتمدًا على نمط الجزر الذي صاغته سايلور ميلر. +وقد قمنا في Astro بتوسيع هذه الفكرة وتطويرها لدعم محتوى يتم توليده ديناميكيًا من الخادم بشكل متوازي وعالي الأداء. + +## ما هي الجزيرة؟ + +في Astro، تُعتبر **الجزيرة** مكوّن واجهة مستخدم محسّن داخل صفحة HTML ثابتة. + +الـ [**جزيرة العميل**](#client-islands) هي مكوّن JavaScript تفاعلي يتم ترطيبه بشكل منفصل عن بقية الصفحة، +أما [**جزيرة الخادم**](#server-islands) فهي مكوّن واجهة مستخدم يتم توليد محتواه الديناميكي من الخادم بشكل منفصل أيضًا. + +كلا النوعين يعملان بشكل مستقل، مما يتيح أداءً أفضل وتقليلًا في زمن التحميل. + +## مكوّنات الجزر + +مكوّنات Astro هي اللبنات الأساسية لقالب صفحتك. فهي تُحوّل إلى HTML ثابت بدون أي وقت تشغيل على المتصفح. + +تخيل جزيرة العميل كمكوّن تفاعلي صغير «يطفو» في بحر من HTML خفيف وسريع يتم توليده من الخادم. +أما جزر الخادم، فتُستخدم لعناصر مخصصة أو ديناميكية مثل صورة ملف المستخدم بعد تسجيل الدخول. + + + رأس الصفحة (جزيرة تفاعلية) + شريط جانبي (HTML ثابت) + + محتوى ثابت مثل النصوص والصور وغيرها. + + شريط صور متحرك (جزيرة تفاعلية) + تذييل الصفحة (HTML ثابت) + المصدر: [Islands Architecture: Jason Miller](https://jasonformat.com/islands-architecture/) + + +تعمل كل جزيرة بمعزل عن الأخرى على الصفحة، ويمكن أن تحتوي الصفحة على عدة جزر. +ومع ذلك، يمكن لجزر العميل تبادل الحالة والتواصل فيما بينها رغم أنها تعمل في سياقات مكونات مختلفة. + +تمنح هذه المرونة Astro القدرة على دعم أطر واجهات متعددة مثل [React](https://react.dev/)، [Preact](https://preactjs.com/)، [Svelte](https://svelte.dev/)، [Vue](https://vuejs.org/)، و [SolidJS](https://www.solidjs.com/). +ولأنها مستقلة، يمكنك حتى دمج عدة أطر في نفس الصفحة. + +:::tip +رغم أن معظم المطورين يفضلون استخدام إطار واحد، إلا أن Astro يدعم استخدام عدة أطر في نفس المشروع، مما يتيح لك: + +- اختيار الإطار الأنسب لكل مكوّن. +- تعلم إطار جديد دون الحاجة لإنشاء مشروع منفصل. +- التعاون مع آخرين حتى لو كانوا يستخدمون أطرًا مختلفة. +- نقل موقعك تدريجيًا إلى إطار جديد دون توقف. +::: + +## جزر العميل + +بشكل افتراضي، يقوم Astro بتحويل كل مكوّن واجهة مستخدم إلى HTML و CSS فقط، +**ويزيل تلقائيًا أي JavaScript من جهة العميل.** + +```astro title="src/pages/index.astro" + +``` + +قد يبدو هذا مقيدًا، لكنه ما يجعل مواقع Astro سريعة بطبيعتها ويمنع المطورين من إرسال JavaScript غير ضروري قد يبطئ الموقع. + +لتحويل أي مكوّن ثابت إلى جزيرة تفاعلية، أضف توجيه `client:*`. +عندها يقوم Astro تلقائيًا ببناء وتجميع كود JavaScript الخاص بالعميل بكفاءة عالية. + +```astro title="src/pages/index.astro" ins="client:load" + + +``` + +يتم تحميل JavaScript من جهة العميل فقط للمكونات التفاعلية التي تحددها باستخدام توجيهات `client:*`. + +ويمكنك أيضًا تحديد أولوية التحميل لكل مكون مثل `client:idle` (يُحمّل عند خمول المتصفح) أو `client:visible` (يُحمّل عند ظهوره على الشاشة). + +

فوائد الجزر العميلية

+ +أبرز فائدة لبناء المواقع باستخدام **جزر Astro** هي **الأداء**: +حيث يتم تحويل الجزء الأكبر من موقعك إلى **HTML ثابت وسريع**، بينما يتم تحميل **JavaScript** فقط للمكونات التي تحتاجه فعلًا. +يُعد JavaScript أحد أبطأ أنواع الملفات من حيث التحميل بالبايت، لذلك فكل بايت يتم توفيره يُحدث فرقًا في السرعة. + +فائدة أخرى هي **التحميل المتوازي**. +في المثال الموضح أعلاه، فإن جزيرة "شريط الصور" منخفضة الأولوية لا تُعيق تحميل جزيرة "رأس الصفحة" عالية الأولوية. +كلاهما يتم تحميله بشكل متوازٍ ومستقل، مما يجعل الرأس تفاعليًا فورًا دون الحاجة لانتظار تحميل شريط الصور الأثقل في أسفل الصفحة. + +والأفضل من ذلك، يمكنك إخبار **Astro** تمامًا **متى وكيف يتم عرض كل مكون**. +إذا كان مكون مثل شريط الصور مكلفًا في التحميل، يمكنك إضافة [توجيه خاص للعميل](/ar/reference/directives-reference/#client-directives) ليخبر **Astro** بعدم تحميله إلا عند ظهوره للمستخدم على الصفحة. +وإذا لم يظهر أبدًا، فلن يتم تحميله مطلقًا. + +في **Astro**، يعود القرار إليك كمطور لتحديد المكونات التي يجب أن تعمل على المتصفح. +سيقوم **Astro** بترطيب ما تحتاجه الصفحة فقط، ويترك بقية الموقع كـ **HTML ثابت**. + +**الجزر العميلية هي السر وراء الأداء العالي الافتراضي الذي يميز Astro!** + +اقرأ المزيد حول [استخدام مكونات أطر JavaScript](/ar/guides/framework-components/) في مشروعك. + +## الجزر الخادمية (Server Islands) + +تُعد الجزر الخادمية طريقة فعّالة لنقل الأكواد البطيئة أو المكلفة على الخادم بعيدًا عن عملية العرض الأساسية، +مما يجعل من السهل الجمع بين **HTML ثابت عالي الأداء** ومكونات ديناميكية تُولّد على الخادم. + +أضف التوجيه [`server:defer`](/ar/reference/directives-reference/#server-directives) إلى أي مكون في صفحتك لتحويله إلى **جزيرة خادمية مستقلة**: + + +```astro title="src/pages/index.astro" "server:defer" +--- +import Avatar from "../components/Avatar.astro"; +--- + +``` + +يعمل هذا الأسلوب على تقسيم صفحتك إلى مناطق أصغر من المحتوى الذي يتم إنشاؤه على الخادم، بحيث يتم تحميل كل منها بشكل متوازٍ دون انتظار الأخرى. + +يمكن عرض المحتوى الرئيسي لصفحتك على الفور باستخدام محتوى مؤقت مثل صورة رمزية افتراضية، +وذلك حتى يصبح محتوى الجزيرة الخاصة متاحًا. +وبفضل **الجزر الخادمية**، فإن وجود مكونات صغيرة مخصصة لا يؤدي إلى تأخير عرض الصفحة الثابتة بالكامل. + +تم تصميم هذا النمط من العرض ليكون **قابلًا للنقل** — فهو لا يعتمد على بنية تحتية محددة للخادم، +مما يجعله يعمل مع أي نوع من الاستضافة، سواء خادم **Node.js** داخل **Docker** أو أي مزود **Serverless** تختاره. + +

فوائد الجزر الخادمية

+ +من أبرز فوائد الجزر الخادمية هي **القدرة على عرض الأجزاء الديناميكية** من الصفحة بشكل مباشر عند الطلب. +يتيح ذلك تخزين الإطار الخارجي والمحتوى الرئيسي مؤقتًا بشكل أكثر فاعلية، مما يوفر أداءً أسرع بشكل ملحوظ. + +ميزة أخرى هي **تحسين تجربة الزائر**: +فالجزر الخادمية محسّنة بحيث تُحمّل بسرعة كبيرة — غالبًا قبل أن يبدأ المتصفح في رسم الصفحة أصلًا. +وفي الوقت القصير الذي تستغرقه الجزر في التحميل، يمكنك عرض محتوى بديل مخصص لتجنب أي تغير مفاجئ في تصميم الصفحة. + +كمثال على موقع يستفيد من **جزر Astro الخادمية**، يمكننا ذكر **متجر إلكتروني**: +رغم أن المحتوى الرئيسي لصفحات المنتجات لا يتغير كثيرًا، إلا أنها تحتوي عادة على عناصر ديناميكية مثل: + +- الصورة الرمزية للمستخدم في الرأس. +- العروض والخصومات الخاصة بالمنتج. +- مراجعات المستخدمين. + +باستخدام الجزر الخادمية لهذه العناصر، سيتمكن الزائر من رؤية الجزء الأهم — **المنتج** — فورًا. +بينما يمكن عرض صور رمزية عامة، أو مؤشرات تحميل، أو إعلانات مؤقتة حتى يظهر المحتوى المخصص بالكامل. + +اقرأ المزيد حول [استخدام الجزر الخادمية](/ar/guides/server-islands/) في مشروعك. diff --git a/src/content/docs/ar/develop-and-build.mdx b/src/content/docs/ar/develop-and-build.mdx new file mode 100644 index 0000000000000..8c5d3aaf43b87 --- /dev/null +++ b/src/content/docs/ar/develop-and-build.mdx @@ -0,0 +1,146 @@ +--- +title: التطوير والبناء +description: 'كيفية بدء العمل على مشروع جديد.' +i18nReady: true +--- +import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; + +بعد إنشاء مشروع Astro، أصبحت جاهزًا للبدء في البناء باستخدام Astro! 🚀 + +## تعديل مشروعك + +لتعديل مشروعك، افتح مجلد المشروع في محرر الشيفرة. العمل في وضع التطوير مع خادم التطوير قيد التشغيل يتيح لك مشاهدة التحديثات أثناء تحرير الشيفرة بشكل فوري. + +يمكنك أيضًا [تخصيص بعض جوانب بيئة التطوير الخاصة بك](#configure-your-dev-environment) مثل إعداد TypeScript أو تثبيت امتدادات المحرر الرسمية الخاصة بـ Astro. + +### تشغيل خادم التطوير الخاص بـ Astro + +يأتي Astro مزودًا بخادم تطوير مدمج يحتوي على كل ما تحتاجه لتطوير المشروع. سيُشغّل أمر CLI \`astro dev\` خادم التطوير المحلي حتى تتمكن من رؤية موقعك يعمل للمرة الأولى. + +كل قالب بداية (starter) يأتي مُعدًا مسبقًا مع سكрипت يقوم بتشغيل \`astro dev\` نيابةً عنك. بعد الانتقال إلى مجلد المشروع، استخدم مدير الحزم المفضل لديك لتشغيل الأمر التالي وبدء خادم تطوير Astro: + + + + ```shell + npm run dev + ``` + + + ```shell + pnpm run dev + ``` + + + ```shell + yarn run dev + ``` + + + + +إذا سار كل شيء على ما يرام، سيقوم Astro الآن بتقديم مشروعك على العنوان التالي: [http://localhost:4321/](http://localhost:4321/). افتح هذا الرابط في متصفحك لمعاينة موقعك الجديد! + +### العمل في وضع التطوير + +سيقٌبل Astro تغييرات الملفات الحيّة داخل مجلد \`src/\` وسيحدّث معاينة الموقع أثناء بنائك، لذلك لن تحتاج لإعادة تشغيل الخادم عند إجراء تغييرات أثناء التطوير. ستتمكن دائمًا من رؤية نسخة محدثة من موقعك في المتصفح طالما أن خادم التطوير قيد التشغيل. + +عند معاينة موقعك في المتصفح، سيكون بإمكانك الوصول إلى [شريط أدوات التطوير في Astro](/ar/guides/dev-toolbar/). أثناء البناء سيساعدك هذا الشريط على فحص [الجزر](/ar/concepts/islands/)، اكتشاف مشكلات إمكانية الوصول، والمزيد. + +إذا لم تتمكن من فتح مشروعك في المتصفح بعد تشغيل خادم التطوير، عُد إلى الطرفية التي شغّلت فيها أمر \`dev\` وتحقق من الرسالة المعروضة — ستخبرك إذا حدث خطأ أو إذا كان مشروعك يُقدّم على عنوان URL مختلف عن [http://localhost:4321/](http://localhost:4321/). + +## بناء الموقع ومعاينته + +لمعرفة كيف ستبدو نسخة موقعك الناتجة عن عملية البناء، قم بإنهاء خادم التطوير (Ctrl + C) ثم نفّذ أمر البناء المناسب لمدير الحزم الذي تستخدمه في الطرفية: + + + + ```shell + npm run build + ``` + + + ```shell + pnpm build + ``` + + + ```shell + yarn run build + ``` + + + +Astro سيُنشئ نسخة جاهزة للنشر من موقعك في مجلد منفصل (افتراضيًا \`dist/\`) وستتمكن من متابعة تقدم عملية البناء في الطرفية. سيُنبّهك هذا إلى أي أخطاء في عملية البناء قبل نشر الموقع إلى الإنتاج. إذا كان TypeScript مُكوّنًا على \`strict\` أو \`strictest\`، فستتحقق سكريبت \`build\` أيضًا من أخطاء الأنواع في مشروعك. + +عند اكتمال البناء، شغّل أمر المعاينة المناسب (مثل \`npm run preview\`) في الطرفية لتعرض النسخة المبنية من موقعك محليًا في نافذة المتصفح نفسها. + +انتبه أن المعاينة تعرض الشيفرة كما كانت عند آخر مرة شغّلت فيها أمر \`build\`. هدفها إعطاؤك صورة حقيقية عن كيف سيبدو موقعك بعد النشر. أي تغييرات تُجريها لاحقًا **لن** تظهر في المعاينة حتى تعيد تشغيل أمر \`build\` مرة أخرى. + +استخدم (Ctrl + C) لإنهاء وضع المعاينة وتشغيل أوامر طرفية أخرى، مثل إعادة تشغيل خادم التطوير للعودة إلى [وضع التطوير الحي](#work-in-development-mode) الذي يحدّث المعاينة تلقائيًا أثناء التحرير ليُظهر تغييرات الشيفرة فورًا. + +اطّلع على مزيد من التفاصيل حول [واجهة سطر أوامر Astro](/ar/reference/cli-reference/) والأوامر الطرفية التي ستستخدمها أثناء بناء مشاريعك مع Astro. + +:::tip +قد تفضّل [نشر موقعك الجديد فورًا](/ar/guides/deploy/) قبل أن تبدأ بتعديل الكثير من الشيفرة. ذلك يُسهّل الحصول على نسخة بسيطة وعاملة منشورة من موقعك، وقد يُوفر عليك وقتًا وجهدًا عند حل مشاكل النشر لاحقًا. +::: + +## الخطوات التالية + +تهانينا! أنت الآن جاهز للبدء في البناء باستخدام Astro! 🥳 + +فيما يلي بعض المواضيع الموصى باستكشافها بعد ذلك — يمكنك قراءتها بأي ترتيب، أو التوقف عن الوثائق مؤقتًا والعودة لتجربة الكود في مشروعك، ثم الرجوع وقتما تحتاج مساعدة أو لديك سؤال. + +### تخصيص بيئة التطوير + +استعرض الأدلة التالية لتخصيص تجربة التطوير لديك. + + + + + + + +### استكشاف ميزات Astro + + + + + + + + +### ابدأ بالدليل التمهيدي + +ابنِ مدونة Astro كاملة بدايةً من صفحة فارغة في [الدليل التمهيدي](/ar/tutorial/0-introduction/). + +هذا المسار طريقة ممتازة لرؤية كيفية عمل Astro: يمر بك عبر الأساسيات مثل الصفحات، القوالب، المكونات، التوجيه، الجزر، والمزيد. كما يتضمن وحدة اختيارية للمبتدئين تشرح تثبيت التطبيقات اللازمة على جهازك، إنشاء حساب GitHub، ونشر موقعك. diff --git a/src/content/docs/ar/guides/build-with-ai.mdx b/src/content/docs/ar/guides/build-with-ai.mdx new file mode 100644 index 0000000000000..b3c3095c32643 --- /dev/null +++ b/src/content/docs/ar/guides/build-with-ai.mdx @@ -0,0 +1,356 @@ +--- +title: بناء مواقع Astro باستخدام أدوات الذكاء الاصطناعي +sidebar: + label: البناء بالذكاء الاصطناعي +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +i18nReady: true +description: موارد ونصائح لبناء مواقع Astro بمساعدة أدوات الذكاء الاصطناعي +--- + +import { Steps, LinkButton, Card, Tabs, TabItem } from '@astrojs/starlight/components'; + +تتمتع المحررات وأدوات البرمجة المعتمدة على الذكاء الاصطناعي عادةً بمعرفة جيدة بواجهات برمجة التطبيقات (APIs) والمفاهيم الأساسية لإطار **Astro**. +لكن قد تستخدم بعض هذه الأدوات واجهات قديمة أو تفتقر إلى معرفة بالميزات الجديدة أو التغييرات الحديثة في الإطار. + +يشرح هذا الدليل كيفية تحسين أداء أدوات الذكاء الاصطناعي عبر تزويدها بأحدث معلومات **Astro**، مع تقديم أفضل الممارسات لبناء المواقع باستخدام الذكاء الاصطناعي كمساعد برمجي. + +## ملفات السياق (Context Files) + +يوفّر **Astro** ملفات [`llms.txt`](https://docs.astro.build/llms.txt) و[`llms-full.txt`](https://docs.astro.build/llms-full.txt)، وهي تحتوي على محتوى التوثيق الكامل بصيغة مبسّطة ومهيّأة لأدوات الذكاء الاصطناعي. +تُعتبر هذه الملفات نسخًا ثابتة من توثيق **Astro** بصيغة Markdown منظمة وسهلة التحليل، ويمكن لبعض الأدوات اكتشافها تلقائيًا عند تحديد مصدر الوثائق كالتالي: `https://docs.astro.build`. + +ورغم أن هذه الملفات توفر وصولًا مباشرًا وسهلًا للمحتوى، إلا أنها كبيرة الحجم وتستهلك عددًا كبيرًا من الرموز (tokens) عند استخدامها بشكل مباشر، كما تحتاج إلى تحديث دوري لمواكبة آخر التغييرات. +لذلك يُفضّل استخدامها كخيار احتياطي فقط عندما لا تتوفر طريقة أحدث للوصول إلى التوثيق. +أما الخيار الأكثر كفاءة فهو **خادم MCP الخاص بوثائق Astro** الذي يوفّر بحثًا لحظيًا في الوثائق ويُحدث تلقائيًا. + +## خادم وثائق Astro MCP + +لضمان امتلاك أدوات الذكاء الاصطناعي أحدث معرفة حول **Astro**، يمكن ربطها بخادم **Astro Docs MCP (Model Context Protocol)**. +يتيح هذا الخادم الوصول الفوري إلى آخر التحديثات في التوثيق، مما يساعد الأدوات على تجنّب التوصيات القديمة والالتزام بأفضل الممارسات الحديثة. + +:::tip[ما هو MCP؟] +[Model Context Protocol](https://modelcontextprotocol.io/) هو معيار موحّد يسمح لأدوات الذكاء الاصطناعي بالوصول إلى مصادر البيانات الخارجية والخدمات المساندة. +::: + +على عكس النماذج التي تعتمد على بيانات ثابتة، يتيح خادم **MCP** الوصول إلى أحدث إصدار من وثائق **Astro** مباشرةً عبر الإنترنت. +الخادم مجاني ومفتوح المصدر ويعمل عن بُعد دون الحاجة إلى أي تثبيت محلي. + +يستخدم خادم وثائق **Astro MCP** واجهة [kapa.ai](https://www.kapa.ai/) للحفاظ على فهرس محدّث دائمًا لمحتوى التوثيق. + +### تفاصيل الخادم + +- **الاسم**: Astro Docs +- **الرابط (URL)**: `https://mcp.docs.astro.build/mcp` +- **نظام النقل (Transport)**: Streamable HTTP + +### التثبيت + +تختلف طريقة إعداد الخادم باختلاف أداة تطوير الذكاء الاصطناعي المستخدمة. +قد يُشار إلى خوادم MCP في بعض الأدوات بمصطلحات أخرى مثل *Connectors* أو *Adapters* أو *Extensions* أو *Plugins*. + +#### الإعداد اليدوي + +تدعم العديد من الأدوات تنسيق JSON موحّد لإعداد خوادم MCP. +في حال لم تكن هناك تعليمات خاصة بالأداة التي تستخدمها، يمكنك إضافة خادم **Astro Docs MCP** يدويًا عبر تضمين التهيئة التالية في إعدادات MCP الخاصة بأداتك: + + + + ```json title="mcp.json" {3-6} + { + "mcpServers": { + "Astro docs": { + "type": "http", + "url": "https://mcp.docs.astro.build/mcp" + } + } + } + ``` + + + ```json title="mcp.json" {3-7} + { + "mcpServers": { + "Astro docs": { + "type": "stdio", + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"] + } + } + } + ``` + + + +#### Claude Code CLI + +[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) هي أداة برمجة ذكية تعمل عبر سطر الأوامر (CLI). +يؤدي تفعيل خادم **Astro Docs MCP** إلى تمكينها من الوصول إلى أحدث وثائق **Astro** أثناء إنشاء الأكواد البرمجية. + +لتثبيت الخادم، استخدم الأمر التالي في الطرفية (Terminal): + +```shell +claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp +``` + +[مزيد من المعلومات حول استخدام خوادم MCP مع Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp) + +--- + +#### Claude Code GitHub Action + +يوفّر **Claude Code** أيضًا **إجراءً (Action)** خاصًا بـ **GitHub** يمكن استخدامه لتنفيذ الأوامر تلقائيًا استجابةً لأحداث معينة داخل المستودع. +ومن خلال تفعيل خادم **Astro Docs MCP**، يمكن لهذا الإجراء الوصول إلى أحدث توثيق أثناء الرد على التعليقات أو إنشاء أكواد لمشاريع **Astro**. + +يمكنك ضبط الإجراء ليستخدم خادم **Astro Docs MCP** للوصول إلى الوثائق بإضافة التكوين التالي داخل ملف مهام GitHub Workflow: + +```yaml title=".github/workflows/claude.yml" {5-14} +# ...بقية إعدادات سير العمل (Workflow) +- uses: anthropics/claude-code-action@beta + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + mcp_config: | + { + "mcpServers": { + "astro-docs": { + "type": "http", + "url": "https://mcp.docs.astro.build/mcp" + } + } + } + allowed_tools: "mcp__astro-docs__search_astro_docs" +``` + +[مزيد من المعلومات حول استخدام خوادم MCP مع Claude Code GitHub Action](https://github.com/anthropics/claude-code-action?tab=readme-ov-file#using-custom-mcp-configuration) + +#### Cursor + +[Cursor](https://cursor.com) هو محرر أكواد يعتمد على الذكاء الاصطناعي. +إضافة خادم **Astro Docs MCP** إلى **Cursor** تتيح له الوصول إلى أحدث وثائق **Astro** أثناء تنفيذ المهام البرمجية أو المساعدة في التطوير. + +لتثبيت الخادم، اضغط على الزر أدناه: + +إضافة إلى Cursor + +[مزيد من المعلومات حول استخدام خوادم MCP مع Cursor](https://docs.cursor.com/context/mcp) + +--- + +#### Visual Studio Code + +يدعم [Visual Studio Code](https://code.visualstudio.com) خوادم **MCP** عند استخدام **Copilot Chat**. +إضافة خادم **Astro Docs MCP** تتيح للمحرر الوصول إلى أحدث توثيق لـ **Astro** عند الإجابة عن الأسئلة أو أثناء تنفيذ المهام البرمجية. + +لتثبيته، اضغط على الزر أدناه: + +إضافة إلى VS Code + +[مزيد من المعلومات حول استخدام خوادم MCP مع VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) + +--- + +#### Warp + +[Warp](https://warp.dev) (المعروف سابقًا باسم Warp Terminal) هو بيئة تطوير تعتمد على الذكاء الاصطناعي وتدعم العمل بعدة وكلاء (Agents) في وقت واحد. +إضافة خادم **Astro Docs MCP** تتيح لـ **Warp** الوصول إلى أحدث وثائق **Astro** أثناء الإجابة على الأسئلة أو تنفيذ المهام البرمجية. + + + +1. افتح إعدادات Warp وانتقل إلى **AI > MCP Servers > Manage MCP Servers**. +2. اضغط على **Add** لإضافة خادم جديد. +3. أدخل الإعدادات التالية، ويمكنك اختيار تفعيل الخادم تلقائيًا عند التشغيل باستخدام الخاصية `start_on_launch`: + ```json title="MCP Configuration" {3-9} + { + "mcpServers": { + "Astro docs": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"], + "env": {}, + "working_directory": null, + "start_on_launch": true + } + } + } + ``` +4. اضغط **Save** لحفظ الإعدادات. + + + +[مزيد من المعلومات حول استخدام خوادم MCP مع Warp](https://docs.warp.dev/knowledge-and-collaboration/mcp) + +#### Claude.ai / Claude Desktop + +يُعد [Claude.ai](https://claude.ai) مساعدًا ذكيًا عامًا متعدد الاستخدامات. +إضافة خادم **Astro Docs MCP** تمكّنه من الوصول إلى أحدث وثائق **Astro** عند الإجابة على الأسئلة أو توليد الأكواد الخاصة بالمشاريع. + + + +1. انتقل إلى [إعدادات الموصلات في Claude.ai](https://claude.ai/settings/connectors). +2. اضغط على **"Add custom connector"** (إضافة موصل مخصص)، وقد تحتاج إلى التمرير للأسفل للوصول إلى هذا الخيار. +3. أدخل رابط الخادم التالي: `https://mcp.docs.astro.build/mcp`. +4. حدّد الاسم ليكون **"Astro docs"**. + + + +[مزيد من المعلومات حول استخدام خوادم MCP مع Claude.ai](https://support.anthropic.com/en/articles/10168395-setting-up-integrations-on-claude-ai#h_cda40ecb32) + +--- + +#### Windsurf + +يُعد [Windsurf](https://windsurf.com/) أداة برمجة ذكية مدعومة بالذكاء الاصطناعي، متوفرة كمحرر مستقل أو كمكون إضافي (Plugin) لمحررات الأكواد المختلفة. +يمكنه استخدام خادم **Astro Docs MCP** للوصول إلى أحدث وثائق **Astro** أثناء تنفيذ المهام البرمجية. + +لا يدعم **Windsurf** بروتوكول **Streaming HTTP** بشكل مباشر، لذا يتطلب إعداد وكيل (Proxy) محلي عبر التكوين التالي: + + + +1. افتح الملف `~/.codeium/windsurf/mcp_config.json` في محرر الأكواد لديك. +2. أضف الإعدادات التالية ضمن تكوين MCP الخاص بـ **Windsurf**: + + ```json title="MCP Configuration" {3-6} + { + "mcpServers": { + "Astro docs": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"] + } + } + } + ``` +3. احفظ التغييرات ثم أعد تشغيل **Windsurf** لتفعيل الإعداد. + + + +[مزيد من المعلومات حول استخدام خوادم MCP مع Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) + +#### Gemini CLI + +تُعد **Gemini CLI** أداة برمجة تعتمد على الذكاء الاصطناعي وتعمل من خلال سطر الأوامر. +يمكنها استخدام خادم **Astro Docs MCP** للوصول إلى أحدث وثائق **Astro** أثناء إنشاء الأكواد البرمجية. + +يمكنك ضبط خوادم MCP على مستوى النظام عبر الملف `~/.gemini/settings.json` +أو داخل ملف إعدادات خاص بالمشروع في المسار `.gemini/settings.json`. + +```json title=".gemini/settings.json" {3-5} +{ + "mcpServers": { + "Astro docs": { + "httpUrl": "https://mcp.docs.astro.build/mcp" + } + } +} +``` + +[مزيد من المعلومات حول استخدام خوادم MCP مع Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) + +--- + +#### Zed + +يدعم [Zed](https://zed.dev) خوادم **MCP** عند استخدام ميزاته المدعومة بالذكاء الاصطناعي. +يمكنه الاستفادة من خادم **Astro Docs MCP** للوصول إلى أحدث التوثيقات أثناء تنفيذ المهام البرمجية. + +لا يدعم **Zed** بروتوكول **Streaming HTTP** بشكل مباشر، لذلك يتطلب إعداد وكيل (Proxy) محلي عبر التكوين التالي: + + + +1. افتح الملف `~/.config/zed/settings.json` في محرر الأكواد. +2. أضف الإعداد التالي ضمن إعدادات MCP الخاصة بـ **Zed**: + + ```json title="MCP Configuration" {3-6} + { + "context_servers": { + "Astro docs": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"] + } + } + } + ``` +3. احفظ التغييرات بعد الانتهاء. + + + +[مزيد من المعلومات حول استخدام خوادم MCP مع Zed](https://zed.dev/docs/ai/mcp) + +#### ChatGPT + +:::caution[توفر محدود] +تكامل خوادم **MCP** متاح فقط لمستخدمي **ChatGPT Pro** و**Team** و**Enterprise**، كما أن إعدادها أكثر تعقيدًا مقارنةً بالأدوات الأخرى. +::: + +راجع [توثيق OpenAI الخاص بخوادم MCP](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server) للحصول على إرشادات الإعداد التفصيلية. + +--- + +#### Raycast + +يمكن لـ [Raycast](https://www.raycast.com/) الاتصال بخوادم **MCP** لتعزيز قدراته الذكية. +تتطلب ميزات الذكاء الاصطناعي (بما في ذلك MCP) اشتراك **Raycast Pro**، لذا تأكد من الترقية قبل التثبيت. +إضافة خادم **Astro Docs MCP** تتيح لـ **Raycast** الوصول إلى أحدث توثيق لـ **Astro** أثناء الإجابة على الأسئلة أو تنفيذ المهام البرمجية. + +لتثبيت الخادم، اضغط على الزر أدناه: + +إضافة إلى Raycast + +[مزيد من المعلومات حول استخدام خوادم MCP مع Raycast](https://manual.raycast.com/model-context-protocol) + +--- + +### الاستخدام + +بعد إعداد الخادم، يمكنك سؤال أداة الذكاء الاصطناعي الخاصة بك عن أي شيء يتعلق بـ **Astro**، وستقوم بجلب المعلومات مباشرة من أحدث التوثيقات. +تتمكن أدوات البرمجة الذكية من الرجوع إلى أحدث الوثائق أثناء تنفيذ الأكواد، كما يمكن للدردشة الذكية الإجابة بدقة عن ميزات **Astro** وواجهاته وأفضل ممارساته. + +:::note[تذكير] +يوفّر خادم **Astro Docs MCP** وصولًا مباشرًا إلى التوثيق المحدث، +لكن أدوات الذكاء الاصطناعي تظل مسؤولة عن تفسير هذه المعلومات وتوليد الأكواد. +لذلك يُنصح دائمًا بمراجعة الأكواد الناتجة واختبارها بعناية قبل استخدامها في الإنتاج. +::: + +--- + +### استكشاف الأخطاء وإصلاحها + +إذا واجهت مشاكل أثناء الإعداد أو الاستخدام: + +- تأكد من أن أداتك تدعم نقل البيانات عبر **Streamable HTTP**. +- تحقق من صحة رابط الخادم: `https://mcp.docs.astro.build/mcp`. +- تأكد من أن أداتك تملك اتصالًا بالإنترنت. +- راجع وثائق الدمج الخاصة بخوادم MCP للأداة التي تستخدمها. + +وإذا استمرت المشكلة، يمكنك فتح بلاغ في [مستودع خادم Astro Docs MCP](https://github.com/withastro/docs-mcp/issues). + +--- + +## دعم الذكاء الاصطناعي عبر Discord + +تعتمد التقنية نفسها التي تشغّل خادم **Astro MCP** على روبوت دردشة في [خادم Discord الخاص بـ Astro](https://astro.build/chat) لتقديم دعم فوري. +انتقل إلى قناة **#support-ai** لطرح أسئلتك حول **Astro** أو كود مشروعك بلغة طبيعية. +تُنشأ المحادثات تلقائيًا في خيوط (Threads)، ويمكنك متابعة النقاش بعدد غير محدود من الأسئلة. + +> **ملاحظة:** المحادثات مع الروبوت عامة وتخضع لقواعد السلوك العامة في الخادم. +> لا يشارك أعضاء الدعم المتطوعون في هذه القناة بشكل مباشر. +> إذا كنت تحتاج مساعدة من المجتمع، يرجى إنشاء موضوع جديد في قناة **#support**. + +--- + +## نصائح لتطوير مشاريع Astro باستخدام الذكاء الاصطناعي + +- **ابدأ من القوالب:** + بدلاً من البدء من الصفر، اطلب من أداة الذكاء الاصطناعي إنشاء مشروع باستخدام [قالب Astro جاهز](https://astro.build/themes/) + أو استخدم الأمر `npm create astro@latest` مع تحديد خيار القالب. + +- **استخدم `astro add` للإضافات الرسمية:** + اطلب من الأداة استخدام أوامر مثل `astro add tailwind` أو `astro add react` لإضافة التكاملات الرسمية. + أما الحزم الأخرى، فقم بتثبيتها عبر مدير الحزم (npm أو pnpm أو yarn) بدل تعديل `package.json` يدويًا. + +- **تحقق من واجهات البرمجة الحالية:** + قد تعتمد بعض الأدوات على أنماط قديمة. + اطلب منها دائمًا مراجعة التوثيق الأحدث، خصوصًا لميزات مثل **Sessions** و**Actions** + أو الميزات التي تم تحديثها بشكل كبير مثل **Content Collections**. + +- **استخدم قواعد المشروع:** + إذا كانت أداتك تدعم ذلك، قم بإعداد قواعد مشروعك (Project Rules) لتطبيق أفضل الممارسات ومعايير الأكواد تلقائيًا. diff --git a/src/content/docs/ar/guides/configuring-astro.mdx b/src/content/docs/ar/guides/configuring-astro.mdx new file mode 100644 index 0000000000000..cf2ee8ace377c --- /dev/null +++ b/src/content/docs/ar/guides/configuring-astro.mdx @@ -0,0 +1,134 @@ +--- +title: نظرة عامة على الإعداد +description: تعرّف على الطرق التي يمكنك من خلالها ضبط مشروعك الجديد وتخصيص تجربة التطوير الخاصة بك. +i18nReady: true +--- +import ReadMore from '~/components/ReadMore.astro' + +يُعد **Astro** إطار عمل مرن وغير مقيّد (unopinionated)، مما يتيح لك ضبط مشروعك بعدة طرق مختلفة. +وهذا يعني أن البدء بمشروع جديد قد يبدو محيّرًا في البداية، لأنه لا توجد "طريقة واحدة مثالية" لإعداد مشروع Astro! + +ستساعدك الأدلة في قسم **الإعداد (Configuration)** هذا على التعرف على الملفات المختلفة التي يمكنك من خلالها تخصيص إعدادات مشروعك وبيئة التطوير. + +إذا كان هذا أول مشروع Astro لك، أو مر وقت منذ آخر مرة أنشأت فيها مشروعًا جديدًا، فاستخدم الأدلة والمراجع التالية الموجودة في التوثيق لمساعدتك على البدء. + +## ملف إعداد Astro + +يُعد [ملف إعداد Astro](/ar/reference/configuration-reference/) ملف JavaScript يتم تضمينه في جذر كل مشروع بداية (starter): + +```js +// astro.config.mjs +import { defineConfig } from "astro/config"; + +export default defineConfig({ + // خيارات الإعداد الخاصة بك هنا... +}); +``` + +يُستخدم هذا الملف فقط إذا كنت بحاجة لتخصيص إعدادات معينة، لكن معظم المشاريع تعتمد عليه. +تُساعدك الدالة `defineConfig()` في تفعيل ميزة **IntelliSense** تلقائيًا داخل محرر الشيفرة لديك (IDE)، وهي المكان الذي تضيف فيه جميع خيارات الإعداد لتخبر Astro بكيفية بناء مشروعك وتحويله إلى HTML. + +نوصي باستخدام الامتداد الافتراضي `.mjs` في معظم الحالات، أو `.ts` إذا كنت تفضل كتابة ملف الإعداد باستخدام TypeScript. +ومع ذلك، يدعم Astro أيضًا الملفات `astro.config.js` و `astro.config.cjs`. + +اطّلع على [مرجع إعدادات Astro](/ar/reference/configuration-reference/) للحصول على نظرة شاملة حول جميع خيارات الإعداد المدعومة. + +## ملف إعداد TypeScript + +يتضمن كل مشروع بداية لـ Astro ملفًا باسم `tsconfig.json` داخل مشروعك. +يُكتب [كود المكون (component script)](/ar/basics/astro-components/#the-component-script) في Astro بلغة TypeScript، مما يوفر أدوات قوية في المحرر ويسمح لك بإضافة بنية نحوية اختيارية إلى JavaScript للتحقق من الأنواع داخل كود مشروعك. + +استخدم ملف `tsconfig.json` لتخصيص قالب TypeScript الذي سيقوم بالتحقق من الأنواع في الكود الخاص بك، وضبط الإضافات (plugins)، وتحديد مسارات الاستيراد (import aliases)، والمزيد. + +اقرأ [دليل TypeScript في Astro](/ar/guides/typescript/) للحصول على نظرة كاملة حول خيارات TypeScript وأنواع المساعدة (utility types) المضمنة في Astro. + +## تجربة التطوير (Development Experience) + +أثناء عملك في وضع التطوير، يمكنك الاستفادة من محرر الشيفرة والأدوات الأخرى لتحسين تجربة المطور مع Astro. + +يُوفر Astro امتدادًا رسميًا لبرنامج **VS Code**، كما أنه متوافق مع العديد من أدوات التحرير الشائعة الأخرى. +كما يقدّم شريط أدوات (Toolbar) قابلًا للتخصيص يظهر في متصفحك أثناء تشغيل خادم التطوير. +يمكنك تثبيت تطبيقات إضافية لهذا الشريط أو حتى إنشاء تطبيقاتك الخاصة لإضافة وظائف جديدة. + +اقرأ أدلة Astro حول [خيارات إعداد المحرر](/ar/editor-setup/) و[استخدام شريط أدوات التطوير](/ar/guides/dev-toolbar/) لتتعلم كيفية تخصيص تجربة التطوير الخاصة بك. + +## مهام شائعة في المشاريع الجديدة + +فيما يلي بعض الخطوات الأولى التي يُمكنك القيام بها بعد إنشاء مشروع Astro جديد. + +### إضافة نطاق النشر (Deployment Domain) + +لإنشاء خريطة موقع (sitemap) وتوليد روابط قانونية (canonical URLs)، قم بتحديد رابط النشر في خيار [`site`](/ar/reference/configuration-reference/#site). +إذا كنت تنشر مشروعك ضمن مسار فرعي (مثل `www.example.com/docs`)، يمكنك أيضًا تحديد خيار [`base`](/ar/reference/configuration-reference/#base) لضبط جذر المشروع. + +بالإضافة إلى ذلك، قد تختلف خدمات النشر في كيفية التعامل مع الشرطة المائلة في نهاية الروابط (مثل `example.com/about` مقابل `example.com/about/`). +بعد نشر موقعك، قد تحتاج إلى ضبط خيار [`trailingSlash`](/ar/reference/configuration-reference/#trailingslash) لتحديد الطريقة التي تفضلها. + +```js title="astro.config.mjs" +import { defineConfig } from "astro/config"; + +export default defineConfig({ + site: "https://www.example.com", + base: "/docs", + trailingSlash: "always", +}); +``` + +### إضافة بيانات التعريف (Site Metadata) + +لا يستخدم Astro ملف الإعداد الخاص به لإدارة بيانات **SEO** أو بيانات **meta** الشائعة، +بل يقتصر استخدامه على المعلومات اللازمة لبناء شيفرة مشروعك وتحويلها إلى HTML. + +بدلاً من ذلك، تتم إضافة هذه المعلومات داخل وسم الصفحة `` باستخدام وسوم HTML القياسية +مثل `` و ``، تمامًا كما تفعل عند كتابة صفحات HTML عادية. + +إحدى الممارسات الشائعة في مواقع Astro هي إنشاء مكون باسم `` من نوع [ملف `.astro`](/ar/basics/astro-components/) +ثم إضافته إلى [مكون التخطيط العام (layout)](/ar/basics/layouts/) ليُطبَّق تلقائيًا على جميع الصفحات في الموقع. + +```astro title="src/components/MainLayout.astro" +--- +import Head from "./Head.astro"; + +const { ...props } = Astro.props; +--- + + + + + + + + + + +``` + +نظرًا لأن `Head.astro` هو مجرد مكون Astro عادي، يمكنك استيراد ملفات أخرى داخله +واستقبال **الخصائص (props)** المُمرَّرة من المكونات الأخرى، مثل عنوان صفحة محددة أو بياناتها التعريفية. + +```astro title="src/components/Head.astro" +--- +import Favicon from "../assets/Favicon.astro"; +import SomeOtherTags from "./SomeOtherTags.astro"; + +const { title = "موقعي على Astro", ...props } = Astro.props; +--- + +{title} + + + + + + + + + + + + + + + + +``` diff --git a/src/content/docs/ar/guides/dev-toolbar.mdx b/src/content/docs/ar/guides/dev-toolbar.mdx new file mode 100644 index 0000000000000..514b721e197ec --- /dev/null +++ b/src/content/docs/ar/guides/dev-toolbar.mdx @@ -0,0 +1,123 @@ +--- +title: شريط أدوات التطوير (Dev Toolbar) +description: دليل لاستخدام شريط أدوات التطوير في Astro +i18nReady: true +--- +import RecipeLinks from "~/components/RecipeLinks.astro"; + +أثناء تشغيل خادم التطوير، يضيف **Astro** شريط أدوات في أسفل كل صفحة ضمن معاينة المتصفح المحلية. + +يحتوي هذا الشريط على مجموعة من الأدوات المفيدة لتصحيح الأخطاء واستعراض موقعك أثناء التطوير، +ويمكن أيضًا [توسيعه بإضافة تطبيقات إضافية](#extending-the-dev-toolbar) من مجلد **integrations**. +كما يمكنك [بناء تطبيقاتك الخاصة لشريط الأدوات](/ar/recipes/making-toolbar-apps/) باستخدام [واجهة برمجة تطبيقات شريط الأدوات (Dev Toolbar API)](/ar/reference/dev-toolbar-app-reference/)! + +يكون هذا الشريط مفعلاً بشكل افتراضي، ويظهر عند تمرير المؤشر فوق الجزء السفلي من الصفحة. +وهو أداة تطوير فقط، **ولن يظهر في موقعك المنشور**. + +--- + +## التطبيقات المدمجة + +### قائمة Astro + +توفّر تطبيق **Astro Menu** وصولًا سريعًا إلى معلومات مختلفة عن المشروع الحالي وروابط إلى موارد إضافية. +ومن أبرز مميزاته أنه يتيح بنقرة واحدة فتح توثيق **Astro**، أو مستودع **GitHub**، أو خادم **Discord** الرسمي. + +يحتوي هذا التطبيق أيضًا على زر **"Copy debug info"**، +الذي يشغّل أمر [`astro info`](/ar/reference/cli-reference/#astro-info) وينسخ مخرجاته إلى الحافظة. +يمكن أن يكون هذا مفيدًا عند طلب المساعدة أو الإبلاغ عن مشكلة. + +--- + +### الفحص (Inspect) + +يُظهر تطبيق **Inspect** معلومات عن أي **جزيرة (Island)** موجودة في الصفحة الحالية. +يمكنك من خلاله معرفة الخصائص (Props) الممرّرة لكل جزيرة، +والتوجيه الخاص بالعميل (Client Directive) المستخدم في عرضها. + +--- + +### التدقيق (Audit) + +يقوم تطبيق **Audit** تلقائيًا بتشغيل سلسلة من الفحوصات على الصفحة الحالية +للكشف عن أكثر المشكلات شيوعًا في الأداء وسهولة الوصول (Accessibility). +عند اكتشاف مشكلة، يظهر **نقطة حمراء** في الشريط، +وبالنقر على التطبيق تظهر نافذة تتضمّن قائمة بالنتائج مع تمييز العناصر ذات الصلة مباشرة في الصفحة. + +:::note +إن فحوصات الأداء وسهولة الوصول التي يجريها شريط أدوات التطوير +ليست بديلًا عن الأدوات المتخصصة مثل [Pa11y](https://pa11y.org/) +أو [Lighthouse](https://developers.google.com/web/tools/lighthouse)، +ولا تغني عن مراجعة بشرية حقيقية. + +يهدف شريط الأدوات إلى تقديم طريقة سريعة وسهلة لاكتشاف المشكلات الشائعة أثناء التطوير، +دون الحاجة إلى مغادرة بيئة العمل أو التبديل إلى أداة أخرى. +::: + +### الإعدادات (Settings) + +يتيح لك تطبيق **Settings** ضبط إعدادات شريط أدوات التطوير، +مثل تفعيل **السجلات التفصيلية (Verbose Logging)**، +أو تعطيل الإشعارات، أو تعديل موضع الشريط على الشاشة حسب تفضيلك. + +--- + +## توسيع شريط أدوات التطوير + +يمكن لتكاملات **Astro Integrations** إضافة تطبيقات جديدة إلى شريط الأدوات، +مما يتيح لك توسيعه بأدوات مخصصة تتناسب مع مشروعك. + +يمكنك العثور على [المزيد من تطبيقات شريط الأدوات في دليل التكاملات](https://astro.build/integrations/?search=&categories%5B%5D=toolbar) +أو الوصول إليها من خلال [قائمة Astro](#astro-menu). + +قم بتثبيت أي تطبيق إضافي لشريط الأدوات في مشروعك تمامًا كما تفعل مع أي [تكامل آخر في Astro](/ar/guides/integrations-guide/)، +باتباع تعليمات التثبيت الخاصة به. + + + +--- + +## تعطيل شريط أدوات التطوير + +يكون شريط الأدوات مفعلاً بشكل افتراضي في جميع مشاريع **Astro**، +لكن يمكنك تعطيله لمشاريع محددة أو لمستخدمين معينين عند الحاجة. + +### على مستوى المشروع + +لإيقاف تشغيل شريط الأدوات لجميع المطورين العاملين على نفس المشروع، +قم بتعيين الخيار `devToolbar: false` في [ملف إعدادات Astro](/ar/reference/configuration-reference/#devtoolbarenabled). + +```js title="astro.config.mjs" ins={4-6} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + devToolbar: { + enabled: false + } +}); +``` + +لإعادة تفعيل شريط الأدوات لاحقًا، قم بحذف هذه الأسطر من ملف الإعدادات +أو غيّر القيمة إلى `enabled: true`. + +### على مستوى المستخدم (Per-user) + +لتعطيل شريط أدوات التطوير لنفسك فقط في مشروع محدد، +يمكنك تشغيل الأمر التالي من سطر الأوامر باستخدام أداة [`astro preferences`](/ar/reference/cli-reference/#astro-preferences): + +```shell +astro preferences disable devToolbar +``` + +أما إذا كنت ترغب في تعطيل شريط الأدوات لجميع مشاريع **Astro** على الجهاز الحالي، +فأضف الخيار `--global` أثناء تنفيذ الأمر: + +```shell +astro preferences disable --global devToolbar +``` + +يمكنك إعادة تفعيل شريط الأدوات لاحقًا باستخدام الأمر: + +```shell +astro preferences enable devToolbar +``` diff --git a/src/content/docs/ar/guides/environment-variables.mdx b/src/content/docs/ar/guides/environment-variables.mdx new file mode 100644 index 0000000000000..00475fedcc84e --- /dev/null +++ b/src/content/docs/ar/guides/environment-variables.mdx @@ -0,0 +1,376 @@ +--- +title: استخدام المتغيرات البيئية +sidebar: + label: المتغيرات البيئية +description: تعلّم كيفية استخدام المتغيرات البيئية في مشروع Astro. +i18nReady: true +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import ReadMore from '~/components/ReadMore.astro'; + +يوفّر لك Astro إمكانية استخدام [دعم Vite المدمج للمتغيرات البيئية](#vites-built-in-support)، ويتضمّن بعض [المتغيرات البيئية الافتراضية لمشروعك](#default-environment-variables) التي تتيح لك الوصول إلى قيم الإعدادات الخاصة بمشروعك الحالي (مثل `site` و`base`) سواء كان المشروع يعمل في بيئة التطوير أو الإنتاج، والمزيد. + +كما يوفّر Astro طريقة [لاستخدام وتنظيم المتغيرات البيئية مع ضمان التحقق من الأنواع](#type-safe-environment-variables). يمكن استخدامها داخل سياق Astro (مثل مكوّنات Astro، أو المسارات والنهايات، أو مكوّنات أُطر العمل، أو الوسائط "middleware")، ويتم إدارتها من خلال [مخطط في إعدادات Astro الخاصة بك](/ar/reference/configuration-reference/#env). + +## دعم Vite المدمج + +يعتمد Astro على دعم Vite المدمج للمتغيرات البيئية، والتي يتم استبدالها بشكلٍ ثابت أثناء عملية البناء، ويسمح لك [باستخدام أي من طرقه](https://vite.dev/guide/env-and-mode.html) للتعامل معها. + +لاحظ أنه بينما تكون **جميع المتغيرات البيئية** متاحة في الشيفرة التي تعمل على الخادم، فإن المتغيرات البيئية التي تبدأ بالمقدمة `PUBLIC_` فقط هي التي تكون متاحة في الشيفرة التي تعمل على جهة العميل، وذلك لأسبابٍ أمنية. + +```ini title=".env" +SECRET_PASSWORD=password123 +PUBLIC_ANYBODY=there +``` + +في هذا المثال، سيكون المتغير `PUBLIC_ANYBODY` (القابل للوصول عبر `import.meta.env.PUBLIC_ANYBODY`) متاحًا في كلٍ من شيفرة الخادم والعميل، بينما سيكون المتغير `SECRET_PASSWORD` (القابل للوصول عبر `import.meta.env.SECRET_PASSWORD`) متاحًا في جهة الخادم فقط. + +:::caution +لن يتم تحميل ملفات `.env` داخل [ملفات الإعداد](#in-the-astro-config-file). +::: + +### الإكمال التلقائي IntelliSense في TypeScript + +بشكلٍ افتراضي، يوفّر Astro تعريفات الأنواع الخاصة بـ `import.meta.env` داخل الملف `astro/client.d.ts`. + +ورغم أنه يمكنك تعريف المزيد من المتغيرات البيئية المخصصة في ملفات `.env.[mode]`، فقد ترغب أحيانًا في الحصول على ميزة الإكمال التلقائي IntelliSense في TypeScript للمتغيرات البيئية التي تُعرّفها بنفسك والمسبوقة بـ `PUBLIC_`. + +لتحقيق ذلك، يمكنك إنشاء ملف باسم `env.d.ts` داخل مجلد `src/` من أجل [توسيع الأنواع العامة](/ar/guides/typescript/#extending-global-types) وضبط واجهة `ImportMetaEnv` كما يلي: + +```ts title="src/env.d.ts" +interface ImportMetaEnv { + readonly DB_PASSWORD: string; + readonly PUBLIC_POKEAPI: string; + // أضف المزيد من المتغيرات البيئية هنا... +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} +``` + +## المتغيرات البيئية الافتراضية + +يتضمّن Astro عددًا من المتغيرات البيئية المدمجة بشكلٍ افتراضي: + +- `import.meta.env.MODE`: يحدّد وضع التشغيل الحالي للموقع. تكون قيمته `development` عند تشغيل الأمر `astro dev`، و`production` عند تشغيل `astro build`. +- `import.meta.env.PROD`: تساوي `true` إذا كان الموقع يعمل في بيئة الإنتاج، و`false` في غير ذلك. +- `import.meta.env.DEV`: تساوي `true` إذا كان الموقع يعمل في بيئة التطوير، و`false` في غير ذلك. وهي دائمًا معاكسة لقيمة `import.meta.env.PROD`. +- `import.meta.env.BASE_URL`: عنوان الأساس الذي يتم تقديم الموقع منه. يتم تحديده من خلال خيار الإعداد [`base`](/ar/reference/configuration-reference/#base). +- `import.meta.env.SITE`: يتم ضبطه بناءً على خيار [`site`](/ar/reference/configuration-reference/#site) المعرّف في ملف إعداد مشروعك `astro.config`. +- `import.meta.env.ASSETS_PREFIX`: يُستخدم كمقدمة (prefix) للروابط الخاصة بالملفات التي ينشئها Astro إذا تم تحديد خيار [`build.assetsPrefix`](/ar/reference/configuration-reference/#buildassetsprefix). يمكن استخدامه لإنشاء روابط موارد (assets) لا يديرها Astro مباشرة. + +يمكنك استخدامها كما تستخدم أي متغير بيئي آخر. + +```ts utils.ts +const isProd = import.meta.env.PROD; +const isDev = import.meta.env.DEV; +``` + +## ضبط المتغيرات البيئية + +### ملفات `.env` + +يمكن تحميل المتغيرات البيئية من ملفات `.env` الموجودة داخل مجلد مشروعك. + +كل ما عليك هو إنشاء ملف باسم `.env` في مجلد المشروع، ثم إضافة المتغيرات التي تريدها بداخله. + +```ini title=".env" +# سيكون هذا المتغير متاحًا فقط عند التشغيل على الخادم! +DB_PASSWORD="foobar" + +# بينما سيكون هذا المتغير متاحًا في كل مكان! +PUBLIC_POKEAPI="https://pokeapi.co/api/v2" +``` + +يمكنك أيضًا إضافة امتدادات مثل `.production` أو `.development` أو أي اسم وضع مخصص إلى اسم ملف البيئة نفسه (مثل `.env.testing` أو `.env.staging`). +يتيح لك ذلك استخدام مجموعات مختلفة من المتغيرات البيئية في أوقات مختلفة. + +تعمل أوامر `astro dev` و`astro build` بشكلٍ افتراضي في أوضاع `"development"` و`"production"` على التوالي. +ويمكنك تشغيل هذه الأوامر باستخدام العلم [`--mode`](/ar/reference/cli-reference/#--mode-string) لتمرير قيمة مختلفة للـ `mode` وتحميل ملف البيئة المناسب. + +يتيح لك هذا تشغيل خادم التطوير أو بناء موقعك مع الاتصال بواجهات برمجة تطبيقات (APIs) مختلفة، مثل: + + + + ```shell + # تشغيل خادم التطوير متصل بواجهة API بيئة "staging" + npm run astro dev -- --mode staging + + # بناء الموقع متصل بواجهة API لبيئة "production" مع معلومات تصحيح إضافية + npm run astro build -- --devOutput + + # بناء الموقع متصل بواجهة API لبيئة "testing" + npm run astro build -- --mode testing + ``` + + + ```shell + # تشغيل خادم التطوير متصل بواجهة API بيئة "staging" + pnpm astro dev --mode staging + + # بناء الموقع متصل بواجهة API لبيئة "production" مع معلومات تصحيح إضافية + pnpm astro build --devOutput + + # بناء الموقع متصل بواجهة API لبيئة "testing" + pnpm astro build --mode testing + ``` + + + ```shell + # تشغيل خادم التطوير متصل بواجهة API بيئة "staging" + yarn astro dev --mode staging + + # بناء الموقع متصل بواجهة API لبيئة "production" مع معلومات تصحيح إضافية + yarn astro build --devOutput + + # بناء الموقع متصل بواجهة API لبيئة "testing" + yarn astro build --mode testing + ``` + + + +لمزيد من المعلومات حول ملفات `.env`، راجع [توثيق Vite](https://vite.dev/guide/env-and-mode.html#env-files). + +### داخل ملف إعداد Astro + +يقوم Astro بتقييم ملفات الإعداد قبل تحميل بقية الملفات. +وهذا يعني أنه لا يمكنك استخدام `import.meta.env` داخل ملف `astro.config.mjs` للوصول إلى المتغيرات البيئية المحددة في ملفات `.env`. + +يمكنك استخدام `process.env` داخل ملف الإعداد للوصول إلى المتغيرات البيئية الأخرى، مثل تلك [التي يحددها سطر الأوامر (CLI)](#using-the-cli). + +كما يمكنك أيضًا استخدام [دالة Vite المساعدة `loadEnv`](https://main.vite.dev/config/#using-environment-variables-in-config) لتحميل ملفات `.env` يدويًا. + +```js title="astro.config.mjs" +import { loadEnv } from "vite"; + +const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), ""); +``` + +:::note +لا يسمح `pnpm` باستيراد الحزم (modules) التي لم يتم تثبيتها مباشرة في مشروعك. +إذا كنت تستخدم `pnpm`، فستحتاج إلى تثبيت حزمة `vite` لتتمكن من استخدام الدالة المساعدة `loadEnv`. + +```sh +pnpm add -D vite +``` +::: + +### استخدام سطر الأوامر (CLI) + +يمكنك أيضًا إضافة المتغيرات البيئية أثناء تشغيل مشروعك مباشرةً، مثل: + + + + ```shell + PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev + ``` + + + ```shell + PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev + ``` + + + ```shell + PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev + ``` + + + +## الوصول إلى المتغيرات البيئية + +يتم الوصول إلى المتغيرات البيئية في Astro من خلال `import.meta.env`، باستخدام ميزة [`import.meta` المضافة في ES2020](https://tc39.es/ecma262/2020/#prod-ImportMeta)، بدلاً من `process.env`. + +على سبيل المثال، يمكنك استخدام `import.meta.env.PUBLIC_POKEAPI` للحصول على قيمة المتغير البيئي `PUBLIC_POKEAPI`. + +```js /(?هل تطوّر مُهايئًا (Adapter)؟ اطّلع على كيفية [جعل المهايئ متوافقًا مع `astro:env`](/ar/reference/adapter-reference/#envgetsecret). + +### الاستخدام الأساسي + +#### تعريف المخطط (Schema) + +لتهيئة المخطط، أضف الخيار `env.schema` إلى إعدادات مشروعك في ملف إعداد Astro: + +```js title="astro.config.mjs" ins={4-8} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + env: { + schema: { + // ... + } + } +}) +``` + +بعد ذلك، يمكنك [تسجيل المتغيرات كقيمة نصية (string)، رقمية (number)، تعداد (enum)، أو منطقية (boolean)](#data-types) باستخدام الدالة المساعدة `envField`. + +قم بتحديد [نوع المتغير البيئي](#variable-types) من خلال تحديد **السياق** (`"client"` أو `"server"`) و**مستوى الوصول** (`"secret"` أو `"public"`) لكل متغير، +ويمكنك أيضًا تمرير خصائص إضافية مثل `optional` (اختياري) أو `default` (قيمة افتراضية) داخل كائن الإعدادات. + +```js title="astro.config.mjs" ins="envField" +import { defineConfig, envField } from "astro/config"; + +export default defineConfig({ + env: { + schema: { + API_URL: envField.string({ context: "client", access: "public", optional: true }), + PORT: envField.number({ context: "server", access: "public", default: 4321 }), + API_SECRET: envField.string({ context: "server", access: "secret" }), + } + } +}) +``` + +سيتم توليد الأنواع (Types) تلقائيًا عند تشغيل الأمرين `astro dev` أو `astro build`، +ولكن يمكنك أيضًا تشغيل الأمر `astro sync` لتوليد الأنواع فقط دون تشغيل المشروع. + +#### استخدام المتغيرات من المخطط + +قم باستيراد المتغيرات التي عرّفتها واستخدمها من الوحدة المناسبة سواء كانت `/client` أو `/server`: + +```astro +--- +import { API_URL } from "astro:env/client"; +import { API_SECRET_TOKEN } from "astro:env/server"; + +const data = await fetch(`${API_URL}/users`, { + method: "GET", + headers: { + "Content-Type": "application/json", + "Authorization": `Bearer ${API_SECRET_TOKEN}` + }, +}) +--- + + +``` + +### أنواع المتغيرات البيئية + +هناك ثلاثة أنواع من المتغيرات البيئية، يتم تحديدها بناءً على مزيج من إعدادات `context` (إما `"client"` أو `"server"`) و`access` (إما `"secret"` أو `"public"`) في المخطط الخاص بك: + +- **متغيرات العميل العامة (Public client variables):** + هذه المتغيرات يتم تضمينها في حزم العميل والخادم النهائية، + ويمكن الوصول إليها من كليهما من خلال وحدة `astro:env/client`: + + ```js + import { API_URL } from "astro:env/client"; + ``` + +- **متغيرات الخادم العامة (Public server variables):** + يتم تضمين هذه المتغيرات في الحزمة النهائية الخاصة بالخادم، + ويمكن الوصول إليها على الخادم من خلال وحدة `astro:env/server`: + + ```js + import { PORT } from "astro:env/server"; + ``` + +- **متغيرات الخادم السرّية (Secret server variables):** + هذه المتغيرات لا يتم تضمينها في الحزمة النهائية إطلاقًا، + ويمكن الوصول إليها فقط على الخادم من خلال وحدة `astro:env/server`: + + ```js + import { API_SECRET } from "astro:env/server"; + ``` + + بشكلٍ افتراضي، يتم التحقق من المتغيرات السرّية أثناء وقت التشغيل فقط. + يمكنك تفعيل التحقق منها عند بدء التشغيل عن طريق ضبط الخيار [`validateSecrets: true`](/ar/reference/configuration-reference/#envvalidatesecrets). + +:::note +**المتغيرات السرّية الخاصة بالعميل (Secret client variables)** غير مدعومة، +لأنه لا توجد طريقة آمنة لإرسال هذه البيانات إلى العميل. +لذلك، لا يمكن الجمع بين `context: "client"` و`access: "secret"` في المخطط الخاص بك. +::: + +### أنواع البيانات + +يدعم النظام حاليًا أربعة أنواع من البيانات: **string (نصي)**، **number (رقمي)**، **enum (تعدادي)**، و**boolean (منطقي)**: + +```js +import { envField } from "astro/config"; + +envField.string({ + // السياق ومستوى الوصول + optional: true, + default: "foo", +}) + +envField.number({ + // السياق ومستوى الوصول + optional: true, + default: 15, +}) + +envField.boolean({ + // السياق ومستوى الوصول + optional: true, + default: true, +}) + +envField.enum({ + // السياق ومستوى الوصول + values: ["foo", "bar", "baz"], + optional: true, + default: "baz", +}) +``` + +للاطلاع على قائمة كاملة بخصائص التحقق، راجع [مرجع واجهة برمجة التطبيقات `envField`](/ar/reference/configuration-reference/#envschema). + +### جلب القيم السرّية ديناميكيًا + +على الرغم من تعريفك لمخطط المتغيرات، فقد تحتاج أحيانًا إلى جلب القيمة الأصلية (الخام) لمتغير سرّي معيّن أو لجلب متغيرات سرّية لم تُعرّفها في المخطط. +في هذه الحالة، يمكنك استخدام الدالة `getSecret()` المصدّرة من الوحدة `astro:env/server`: + +```js +import { + FOO, // نوعه boolean + getSecret +} from "astro:env/server"; + +getSecret("FOO"); // ترجع string أو undefined +``` + +تعرّف على المزيد في [مرجع واجهة برمجة التطبيقات](/ar/reference/modules/astro-env/#getsecret). + +### القيود + +الوحدة `astro:env` هي وحدة افتراضية (virtual module)، مما يعني أنه يمكن استخدامها فقط داخل سياق Astro. +على سبيل المثال، يمكنك استخدامها في: + +- الوسائط (Middlewares) +- المسارات والنهايات في Astro +- مكوّنات Astro +- مكوّنات أطر العمل +- الوحدات (Modules) + +بينما **لا يمكن** استخدامها في الأماكن التالية، ويجب عليك في هذه الحالات استخدام `process.env` بدلًا منها: + +- ملف `astro.config.mjs` +- السكربتات (Scripts) diff --git a/src/content/docs/ar/guides/typescript.mdx b/src/content/docs/ar/guides/typescript.mdx new file mode 100644 index 0000000000000..568af8a0dd878 --- /dev/null +++ b/src/content/docs/ar/guides/typescript.mdx @@ -0,0 +1,421 @@ +--- +title: TypeScript +description: تعلّم كيفية استخدام دعم TypeScript المدمج في Astro. +i18nReady: true +--- +import Since from '~/components/Since.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' + +يأتي **Astro** مزوّدًا بدعم مدمج لـ [TypeScript](https://www.typescriptlang.org/). يمكنك استيراد ملفات `.ts` و `.tsx` في مشروعك، وكتابة كود TypeScript مباشرةً داخل [مكوّنات Astro](/ar/basics/astro-components/#the-component-script)، بل ويمكنك أيضًا استخدام ملف [`astro.config.ts`](/ar/guides/configuring-astro/#the-astro-config-file) لتكوين إعدادات المشروع إن رغبت. + +باستخدام TypeScript، يمكنك تجنّب الأخطاء أثناء التشغيل عبر تعريف شكل الكائنات والمكوّنات في الكود الخاص بك. على سبيل المثال، إذا استخدمت TypeScript لتعريف [أنواع الخصائص (props) الخاصة بالمكوّنات](#component-props)، فسيُظهر لك المحرّر خطأً إذا مرّرت خاصية غير معرّفة للمكوّن. + +لست مضطرًا لكتابة كود TypeScript حتى تستفيد منه. فـ **Astro** يتعامل مع كود المكوّنات وكأنه TypeScript افتراضيًا، وملحق [Astro الخاص بـ VS Code](/ar/editor-setup/) يقوم بتخمين الأنواع لتوفير الإكمال التلقائي والتنبيهات والأخطاء في المحرّر. + +خادم التطوير في Astro لا يقوم بفحص الأنواع أثناء التشغيل، ولكن يمكنك استخدام [سكربت منفصل](#type-checking) لفحص أخطاء الأنواع عبر سطر الأوامر. + +## الإعداد + +تتضمّن مشاريع البدء في Astro ملف `tsconfig.json` داخل المشروع. حتى لو لم تستخدم TypeScript، يظل هذا الملف ضروريًا حتى يتمكّن كل من Astro و VS Code من فهم بنية مشروعك. بعض الميزات (مثل استيراد حزم npm) لن تعمل بشكل كامل داخل المحرّر دون وجود هذا الملف. وإذا قمت بتثبيت Astro يدويًا، فتأكّد من إنشاء هذا الملف بنفسك. + +### قوالب TSConfig + +يتضمّن Astro ثلاثة قوالب قابلة للتوسيع من `tsconfig.json`: وهي `base` و `strict` و `strictest`. +قالب `base` يفعّل ميزات JavaScript الحديثة ويُستخدم كأساس للقالبين الآخرين. +نوصي باستخدام `strict` أو `strictest` إذا كنت تخطط لكتابة كود TypeScript في مشروعك. +يمكنك الاطلاع على هذه القوالب الثلاثة ومقارنتها على [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/). + +للاستفادة من أحد هذه القوالب، استخدم إعداد [`extends`](https://www.typescriptlang.org/tsconfig#extends): + +```json title="tsconfig.json" +{ + "extends": "astro/tsconfigs/base" +} +``` + +بالإضافة إلى ذلك، نوصي بتحديد الخصائص `include` و `exclude` كما يلي للاستفادة من أنواع Astro وتجنّب فحص الملفات الناتجة بعد البناء: + +```json title="tsconfig.json" ins={3-4} +{ + "extends": "astro/tsconfigs/base", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] +} +``` + +### إضافة TypeScript للمحرّر + +يمكنك تثبيت [إضافة TypeScript الخاصة بـ Astro](https://www.npmjs.com/package/@astrojs/ts-plugin) بشكل منفصل إذا لم تكن تستخدم [الملحق الرسمي لـ Astro في VS Code](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). +يتم تثبيت هذه الإضافة تلقائيًا وإعدادها بواسطة ملحق VS Code، لذلك لا حاجة لتثبيتهما معًا. + +تعمل هذه الإضافة داخل المحرّر فقط، أي أنها لا تُشغَّل عند تنفيذ الأمر `tsc` في الطرفية. +عند استخدام `tsc`، يتم تجاهل ملفات `.astro` تمامًا. +بدلاً من ذلك، يمكنك استخدام [أمر CLI `astro check`](/ar/reference/cli-reference/#astro-check) لفحص كلٍّ من ملفات `.astro` و `.ts`. + +كما تدعم هذه الإضافة أيضًا استيراد ملفات `.astro` من ملفات `.ts`، وهو أمر مفيد في بعض الحالات مثل إعادة التصدير. + + + + ```shell + npm install @astrojs/ts-plugin + ``` + + + ```shell + pnpm add @astrojs/ts-plugin + ``` + + + ```shell + yarn add @astrojs/ts-plugin + ``` + + + +بعد التثبيت، أضف الإضافة إلى ملف `tsconfig.json` الخاص بك: + +```json title="tsconfig.json" +{ + "compilerOptions": { + "plugins": [ + { + "name": "@astrojs/ts-plugin" + }, + ], + } +} +``` +للتأكّد من أن الإضافة تعمل بشكل صحيح، أنشئ ملفًا بامتداد `.ts` واستورد مكوّنًا من مكوّنات Astro داخله. +إذا لم تظهر أي رسائل تحذير في المحرّر، فهذا يعني أن الإضافة مفعّلة وتعمل كما يجب. + +### أُطر واجهات المستخدم (UI Frameworks) + +إذا كان مشروعك يستخدم أحد [أُطر واجهات المستخدم](/ar/guides/framework-components/)، فقد تحتاج إلى إعدادات إضافية تختلف حسب الإطار المستخدم. +راجع توثيق TypeScript الخاص بإطارك لمزيد من التفاصيل: + +- [Vue](https://vuejs.org/guide/typescript/overview.html#using-vue-with-typescript) +- [React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup) +- [Preact](https://preactjs.com/guide/v10/typescript) +- [Solid](https://www.solidjs.com/guides/typescript) +- [Svelte](https://svelte.dev/docs/svelte/typescript) + +## استيراد الأنواع (Type Imports) + +احرص على استخدام **استيراد وتصدير الأنواع بشكل صريح** متى كان ذلك ممكنًا. + +```js del={1} ins={2} ins="type" +import { SomeType } from "./script"; +import type { SomeType } from "./script"; +``` + +بهذه الطريقة، تتجنّب الحالات النادرة التي قد يحاول فيها مجمّع Astro ضمّ الأنواع المستوردة وكأنها ملفات JavaScript فعلية. + +يمكنك ضبط TypeScript ليفرض استخدام استيراد الأنواع في ملف `tsconfig.json`. +قم بتعيين الخيار [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) إلى القيمة `true`. +سيقوم TypeScript عندها بفحص الاستيرادات وإعلامك متى يجب استخدام `import type`. +يُفعَّل هذا الإعداد افتراضيًا في جميع القوالب الجاهزة (presets) الخاصة بـ Astro. + +```json title="tsconfig.json" ins={3} +{ + "compilerOptions": { + "verbatimModuleSyntax": true + } +} +``` + +## أسماء الاستيراد المختصرة (Import Aliases) + +يدعم **Astro** استخدام أسماء استيراد مختصرة يمكنك تعريفها داخل إعداد `paths` في ملف `tsconfig.json`. +[اطّلع على دليل الاستيراد الخاص بنا](/ar/guides/imports/#aliases) لمعرفة المزيد حول كيفية استخدامها. + +```astro title="src/pages/about/nate.astro" "@components" "@layouts" +--- +import HelloWorld from "@components/HelloWorld.astro"; +import Layout from "@layouts/Layout.astro"; +--- +``` + +```json title="tsconfig.json" {4-5} +{ + "compilerOptions": { + "paths": { + "@components/*": ["./src/components/*"], + "@layouts/*": ["./src/layouts/*"] + } + } +} +``` + +## توسيع الأنواع العامة (Extending Global Types) + +يمكنك إنشاء ملف باسم `src/env.d.ts` كإجراء متّبع لإضافة تعريفات أنواع مخصّصة، +أو للاستفادة من أنواع **Astro** في حال لم يكن لديك ملف `tsconfig.json`: + +```ts title="src/env.d.ts" +// تعريف أنواع مخصّصة +declare var myString: string; + +// أنواع Astro — ليست ضرورية إذا كان لديك بالفعل ملف `tsconfig.json` +/// +``` + +### `window` و `globalThis` + +قد تحتاج أحيانًا إلى إضافة خاصية إلى الكائن العام (global object). +يمكنك القيام بذلك عبر إضافة تعريفات على المستوى الأعلى باستخدام الكلمة المفتاحية `declare` داخل ملف `env.d.ts`: + +```ts title="src/env.d.ts" +declare var myString: string; +declare function myFunction(): boolean; +``` + +سيُوفّر هذا التعريف دعم الأنواع لكلٍّ من `globalThis.myString` و `globalThis.myFunction`، +وكذلك `window.myString` و `window.myFunction`. + +لاحظ أن الكائن `window` متاح فقط في كود الواجهة الأمامية (client-side). +أما `globalThis` فهو متاح في كلٍّ من الخادم (server-side) والواجهة الأمامية، +لكن القيم المعرّفة على الخادم لن تُشارك تلقائيًا مع الواجهة الأمامية. + +إذا كنت ترغب فقط في تعريف خاصية على كائن `window`، يمكنك بدلاً من ذلك تعريف واجهة (interface) باسم `Window` كما يلي: + +```ts title="src/env.d.ts" +interface Window { + myFunction(): boolean; +} +``` + +### إضافة خصائص غير قياسية (Non-standard Attributes) + +قد ترغب أحيانًا في تعريف نوع لخصائص مخصّصة أو لخصائص CSS خاصة بمشروعك. +يمكنك توسيع تعريفات JSX الافتراضية في **Astro** لإضافة هذه الخصائص غير القياسية عن طريق إعادة تعريف مساحة الأسماء `astroHTML.JSX` داخل ملف `.d.ts`. + +```ts title="src/env.d.ts" +declare namespace astroHTML.JSX { + interface HTMLAttributes { + "data-count"?: number; + "data-label"?: string; + } + + // إضافة خاصية CSS مخصّصة إلى كائن style + interface CSSProperties { + "--theme-color"?: "black" | "white"; + } +} +``` + +:::note +يتم حقن الكائن `astroHTML` بشكلٍ عام داخل مكونات `.astro`. +أما إذا كنت تريد استخدامه داخل ملفات TypeScript، فيمكنك ذلك باستخدام [توجيه التعليمة الثلاثية](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html): + +```ts +/// + +type MyAttributes = astroHTML.JSX.ImgHTMLAttributes; +``` +::: + +### استخدام الاستيراد (Using Imports) + +قد ترغب في توسيع الأنواع العامة (global types) عبر إعادة استخدام أنواع تم تعريفها مسبقًا داخل مشروعك أو من مكتبة خارجية. +للقيام بذلك، استخدم [الاستيراد الديناميكي](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import): + +```ts title="src/env.d.ts" +type Product = { + id: string; + name: string; + price: number; +}; + +declare namespace App { + interface Locals { + orders: Map + session: import("./lib/server/session").Session | null; + user: import("my-external-library").User; + } +} +``` + +ملف `.d.ts` هو إعلان لـ **وحدة محيطة** (ambient module). على الرغم من تشابه صيغته مع صيغة وحدات ES، إلا أن هذه الملفات لا تسمح بوجود استيرادات أو تصديرات على مستوى الأعلى (top-level imports/exports). إذا صادف TypeScript وجود استيراد أو تصدير في ملف `.d.ts`، فسيُعامل الملف على أنه **توسيع للوحدة** (module augmentation) — وهذا سيؤدّي إلى كسر تعريفات الأنواع العامة لديك. + +## خواص المكوّن (Component Props) + +يدعم **Astro** كتابة أنواع (typing) لخاصيات المكوّنات (component props) باستخدام TypeScript. لتمكين ذلك، أضِف واجهة TypeScript باسم `Props` داخل الـ frontmatter للمكوّن. يمكن استخدام عبارة `export` لكنّها ليست ضرورية. يقوم [ملحق Astro الخاص بـ VS Code](/ar/editor-setup/) بالبحث تلقائيًا عن واجهة `Props` وتوفير دعم TypeScript المناسب عند استخدام ذلك المكوّن داخل قالب آخر. + +```astro title="src/components/HelloProps.astro" ins={2-5} +--- +interface Props { + name: string; + greeting?: string; +} + +const { greeting = "Hello", name } = Astro.props; +--- +

{greeting}, {name}!

+``` + +### أنماط شائعة لتعريف أنواع الخصائص (Common Prop Type Patterns) + +- إذا كان المكوّن لا يستقبل أي خصائص أو محتوى ضمن الفتحات (slots)، يمكنك استخدام: + `type Props = Record`. +- إذا كان المكوّن يجب أن يحتوي على عناصر فرعية (children) في الفتحة الافتراضية، يمكنك فرض ذلك باستخدام: + `type Props = { children: any; };`. + +## أدوات أنواع (Type Utilities) + +

+ +يأتي **Astro** مزوّدًا ببعض أنواع الأدوات (utility types) المضمّنة لأنماط الخصائص الشائعة. +تتوفر هذه الأنواع من خلال نقطة الدخول `astro/types`. + +### الخصائص المضمّنة لعناصر HTML (Built-in HTML Attributes) + +يوفّر Astro النوع `HTMLAttributes` للتحقّق من أن علامات HTML في مشروعك تستخدم الخصائص الصحيحة والمعتمدة. +يمكنك استخدام هذه الأنواع لبناء تعريفات دقيقة لخصائص المكوّنات (component props). + +على سبيل المثال، إذا كنت بصدد إنشاء مكوّن باسم ``، يمكنك استخدام هذا النوع لتعكس الخصائص الافتراضية لعناصر `` في نوع الخصائص الخاص بالمكوّن: + +```astro title="src/components/Link.astro" ins="HTMLAttributes" ins="HTMLAttributes<'a'>" +--- +import type { HTMLAttributes } from "astro/types"; + +// استخدام `type` +type Props = HTMLAttributes<"a">; + +// آو باستخدام `interface` +interface Props extends HTMLAttributes<"a"> { + myProp?: boolean; +} + +const { href, ...attrs } = Astro.props; +--- + + + +``` + +### نوع `ComponentProps` + +

+ +يتيح لك هذا النوع الوصول إلى تعريف `Props` الخاص بمكوّن آخر، حتى لو لم يقم ذلك المكوّن بتصدير نوع `Props` بشكل مباشر. + +يوضّح المثال التالي كيفية استخدام أداة `ComponentProps` من مكتبة `astro/types` للإشارة إلى نوع الخصائص `Props` الخاص بمكوّن `