دليل المساهمة في التوثيق

مرحبًا بك في دليل المساهمة في توثيق Next.js! نحن متحمسون لوجودك هنا.

توفر هذه الصفحة تعليمات حول كيفية تحرير توثيق Next.js. هدفنا هو تمكين كل فرد في المجتمع من المساهمة وتحسين التوثيق.

لماذا تشارك؟

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

من خلال المساهمة في توثيق Next.js، أنت تساعدنا في بناء مصدر تعليمي أكثر قوة لجميع المطورين. سواء وجدت خطأً مطبعيًا، أو قسمًا غير واضح، أو لاحظت أن موضوعًا معينًا مفقود، فإن مساهماتك مرحب بها ومقدرة.

كيفية المساهمة

يمكن العثور على محتوى التوثيق في مستودع Next.js. للمساهمة، يمكنك تحرير الملفات مباشرة على GitHub أو استنساخ المستودع وتحرير الملفات محليًا.

سير العمل على GitHub

إذا كنت جديدًا على GitHub، نوصي بقراءة دليل المصادر المفتوحة على GitHub لتعلم كيفية تفرع مستودع، وإنشاء فرع، وإرسال طلب سحب.

معلومة مفيدة: يعيش كود التوثيق الأساسي في قاعدة كود خاصة تتم مزامنتها مع المستودع العام لـ Next.js. هذا يعني أنه لا يمكنك معاينة التوثيق محليًا. ومع ذلك، ستشاهد تغييراتك على nextjs.org بعد دمج طلب السحب.

كتابة MDX

يتم كتابة التوثيق باستخدام MDX، وهو تنسيق ماركداون يدعم تركيب JSX. هذا يسمح لنا بتضمين مكونات React في التوثيق. راجع دليل ماركداون على GitHub للحصول على نظرة سريعة على تركيب ماركداون.

VSCode

معاينة التغييرات محليًا

يحتوي VSCode على معاين مدمج لملفات ماركداون يمكنك استخدامه لرؤية تحريراتك محليًا. لتمكين المعاين لملفات MDX، ستحتاج إلى إضافة خيار تكوين إلى إعدادات المستخدم.

افتح لوحة الأوامر (⌘ + ⇧ + P على Mac أو Ctrl + Shift + P على Windows) وابحث عن Preferences: Open User Settings (JSON).

ثم أضف السطر التالي إلى ملف settings.json:

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

بعد ذلك، افتح لوحة الأوامر مرة أخرى، وابحث عن Markdown: Preview File أو Markdown: Open Preview to the Side. سيؤدي هذا إلى فتح نافذة معاينة حيث يمكنك رؤية التغييرات المنسقة.

الامتدادات

نوصي أيضًا بالامتدادات التالية لمستخدمي VSCode:

• MDX: ذكاء اصطناعي وتمييز تركيب لـ MDX.
• Grammarly: مدقق قواعد وإملاء.
• Prettier: تنسيق ملفات MDX عند الحفظ.

عملية المراجعة

بمجرد إرسال مساهمتك، سيقوم فريق Next.js أو فريق تجربة المطورين بمراجعة تغييراتك، وتقديم ملاحظات، ودمج طلب السحب عندما يكون جاهزًا.

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

نصيحة: قم بتشغيل pnpm prettier-fix لتشغيل Prettier قبل إرسال طلب السحب الخاص بك.

هيكل الملفات

يستخدم التوثيق توجيه نظام الملفات. يمثل كل مجلد وملف داخل /docs مقطع مسار. تستخدم هذه المقاطع لتوليد مسارات URL، والتنقل، وفتات الخبز.

يعكس هيكل الملفات التنقل الذي تراه على الموقع، وبشكل افتراضي، يتم فرز عناصر التنقل أبجديًا. ومع ذلك، يمكننا تغيير ترتيب العناصر عن طريق إضافة رقم مكون من خانتين (00-) إلى اسم المجلد أو الملف.

على سبيل المثال، في مرجع واجهة برمجة التطبيقات للوظائف، يتم فرز الصفحات أبجديًا لأنه يسهل على المطورين العثور على وظيفة محددة:

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

ولكن في قسم التوجيه، يتم إضافة رقم مكون من خانتين كبادئة للملفات، مرتبة بالترتيب الذي يجب أن يتعلم فيه المطورون هذه المفاهيم:

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.mdx
└── ...

للعثور بسرعة على صفحة، يمكنك استخدام ⌘ + P (Mac) أو Ctrl + P (Windows) لفتح شريط البحث في VSCode. ثم اكتب slug الخاص بالصفحة التي تبحث عنها. على سبيل المثال defining-routes

لماذا لا نستخدم ملف تعريف؟

لقد نظرنا في استخدام ملف تعريف (طريقة أخرى شائعة لتوليد تنقل التوثيق)، لكننا وجدنا أن ملف التعريف سيفقد التزامن بسرعة مع الملفات. يجبرنا توجيه نظام الملفات على التفكير في هيكل التوثيق ويبدو أكثر أصالة لـ Next.js.

البيانات الوصفية

تحتوي كل صفحة على كتلة بيانات وصفية في أعلى الملف مفصولة بثلاثة شرطات.

الحقول المطلوبة

الحقول التالية مطلوبة:

---
title: عنوان الصفحة
description: وصف الصفحة
---

من الجيد تحديد عنوان الصفحة إلى 2-3 كلمات (مثل تحسين الصور) والوصف إلى 1-2 جملة (مثل تعلم كيفية تحسين الصور في Next.js).

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

الحقول التالية اختيارية:

---
nav_title: عنوان عنصر التنقل
source: app/building-your-application/optimizing/images
related:
  description: راجع مرجع واجهة برمجة التطبيقات لمكون الصورة.
  links:
    - app/api-reference/components/image
---

توثيق App و Pages

نظرًا لأن معظم الميزات في موجه التطبيق (App Router) و موجه الصفحات (Pages Router) مختلفة تمامًا، يتم الاحتفاظ بتوثيق كل منها في أقسام منفصلة (02-app و 03-pages). ومع ذلك، هناك بعض الميزات المشتركة بينهما.

الصفحات المشتركة

لتجنب تكرار المحتوى وخطر عدم التزامن، نستخدم حقل source لسحب المحتوى من صفحة إلى أخرى. على سبيل المثال، يتصرف مكون <Link> بشكل متشابه إلى حد كبير في التطبيق و الصفحات. بدلاً من تكرار المحتوى، يمكننا سحب المحتوى من app/.../link.mdx إلى pages/.../link.mdx:

---
title: <Link>
description: مرجع واجهة برمجة التطبيقات لمكون <Link>.
---

سيساعدك مرجع واجهة برمجة التطبيقات هذا في فهم كيفية استخدام الخصائص
وخيارات التكوين المتاحة لمكون Link.

---
title: <Link>
description: مرجع واجهة برمجة التطبيقات لمكون <Link>.
source: app/api-reference/components/link
---

{/* لا تقم بتحرير هذه الصفحة. */}
{/* يتم سحب محتوى هذه الصفحة من المصدر أعلاه. */}

يمكننا therefore تحرير المحتوى في مكان واحد وينعكس في كلا القسمين.

المحتوى المشترك

في الصفحات المشتركة، قد يكون هناك أحيانًا محتوى خاص بـ موجه التطبيق أو موجه الصفحات. على سبيل المثال، يحتوي مكون <Link> على خاصية shallow متاحة فقط في الصفحات وليس في التطبيق.

للتأكد من ظهور المحتوى فقط في الموجه الصحيح، يمكننا لف كتل المحتوى في مكونات <AppOnly> أو <PagesOnly>:

هذا المحتوى مشترك بين التطبيق والصفحات.

<PagesOnly>

هذا المحتوى سيظهر فقط في توثيق الصفحات.

</PagesOnly>

هذا المحتوى مشترك بين التطبيق والصفحات.

من المحتمل أن تستخدم هذه المكونات للأمثلة وكتل الكود.

كتل الكود

يجب أن تحتوي كتل الكود على مثال عمل أدنى يمكن نسخه ولصقه. هذا يعني أن الكود يجب أن يعمل دون أي تكوين إضافي.

على سبيل المثال، إذا كنت تظهر كيفية استخدام مكون <Link>، يجب أن تتضمن عبارة import والمكون <Link> نفسه.

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

قم دائمًا بتشغيل الأمثلة محليًا قبل إرسالها. هذا سيضمن أن الكود محدث ويعمل.

اللغة واسم الملف

يجب أن تحتوي كتل الكود على رأس يتضمن اللغة و filename. أضف خاصية filename لعرض أيقونة Terminal خاصة تساعد المستخدمين في معرفة مكان إدخال الأمر. على سبيل المثال:

```bash filename="Terminal"
npx create-next-app
```

معظم الأمثلة في التوثيق مكتوبة بـ tsx و jsx، وبعضها بـ bash. ومع ذلك، يمكنك استخدام أي لغة مدعومة، إليك القائمة الكاملة.

عند كتابة كتل كود JavaScript، نستخدم مجموعات اللغة والامتداد التالية.

مبدل TS و JS

أضف مبدل لغة للتبديل بين TypeScript و JavaScript. يجب أن تكون كتل الكود TypeScript أولاً مع نسخة JavaScript لاستيعاب المستخدمين.

حاليًا، نكتب أمثلة TS و JS واحدًا تلو الآخر، ونربطها بخاصية switcher:

```tsx filename="app/page.tsx" switcher

```

```jsx filename="app/page.js" switcher

```

معلومة مفيدة: نخطط لتجميع مقاطع TypeScript تلقائيًا إلى JavaScript في المستقبل. في الوقت الحالي، يمكنك استخدام transform.tools.

تمييز الأسطر

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

سطر واحد: highlight={1}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

أسطر متعددة: highlight={1,3}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

نطاق الأسطر: highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

الأيقونات

الأيقونات التالية متاحة للاستخدام في التوثيق:

<Check size={18} />
<Cross size={18} />

المخرجات:

نحن لا نستخدم الرموز التعبيرية في التوثيق.

الملاحظات

للمعلومات المهمة ولكن غير الحرجة، استخدم الملاحظات. الملاحظات طريقة جيدة لإضافة معلومات دون تشتيت المستخدم عن المحتوى الرئيسي.

> **معلومة مفيدة**: هذه ملاحظة بسطر واحد.

> **معلومة مفيدة**:
>
> - نستخدم أيضًا هذا التنسيق للملاحظات متعددة الأسطر.
> - هناك أحيانًا عناصر متعددة تستحق المعرفة أو تذكرها.

المخرجات:

معلومة مفيدة: هذه ملاحظة بسطر واحد.

معلومة مفيدة:

• نستخدم أيضًا هذا التنسيق للملاحظات متعددة الأسطر.
• هناك أحيانًا عناصر متعددة تستحق المعرفة أو تذكرها.

الروابط ذات الصلة

توجه الروابط ذات الصلة رحلة تعلم المستخدم عن طريق إضافة روابط للخطوات التالية المنطقية.

• ستظهر الروابط في بطاقات أسفل المحتوى الرئيسي للصفحة.
• سيتم إنشاء الروابط تلقائيًا للصفحات التي تحتوي على صفحات فرعية. على سبيل المثال، يحتوي قسم التحسين على روابط لجميع صفحاته الفرعية.

قم بإنشاء روابط ذات صلة باستخدام حقل related في البيانات الوصفية للصفحة.

---
related:
  description: تعلم كيفية البدء بسرعة بتطبيقك الأول.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

الحقول المتداخلة

المخططات

المخططات طريقة رائعة لشرح المفاهيم المعقدة. نستخدم Figma لإنشاء مخططات، باتباع دليل تصميم Vercel.

توجد المخططات حاليًا في مجلد /public في موقع Next.js الخاص بنا. إذا كنت ترغب في تحديث أو إضافة مخطط، يرجى فتح مشكلة على GitHub مع أفكارك.

المكونات المخصصة و HTML

هذه هي مكونات React المتاحة للتوثيق: <Image /> (next/image)، <PagesOnly />، <AppOnly />، <Cross />، و <Check />. لا نسمح بـ HTML خام في التوثيق بخلاف وسم <details>.

إذا كانت لديك أفكار لمكونات جديدة، يرجى فتح مشكلة على GitHub.

دليل الأسلوب

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

قوالب الصفحات

بينما ليس لدينا قالب صارم للصفحات، هناك أقسام صفحات ستشاهدها متكررة عبر التوثيق:

• نظرة عامة: يجب أن تخبر الفقرة الأولى من الصفحة المستخدم بماهية الميزة وما تستخدم له. متبوعة بمثال عمل أدنى أو مرجع واجهة برمجة التطبيقات الخاصة بها.
• الاتفاقية: إذا كانت الميزة لها اتفاقية، يجب شرحها هنا.
• أمثلة: عرض كيفية استخدام الميزة مع حالات استخدام مختلفة.
• جداول واجهة برمجة التطبيقات: يجب أن تحتوي صفحات واجهة برمجة التطبيقات على جدول نظرة عامة في أسفل الصفحة مع روابط القفز إلى الأقسام (عند الإمكان).
• الخطوات التالية (الروابط ذات الصلة): أضف روابط للصفحات ذات الصلة لتوجيه رحلة تعلم المستخدم.

لا تتردد في إضافة هذه الأقسام حسب الحاجة.

أنواع الصفحات

تنقسم صفحات التوثيق إلى فئتين: المفاهيمية والمرجعية.

• الصفحات المفاهيمية: تُستخدم لشرح مفهوم أو ميزة. عادةً ما تكون أطول وتحتوي على معلومات أكثر من الصفحات المرجعية. في توثيق Next.js، توجد الصفحات المفاهيمية في قسم بناء تطبيقك.
• الصفحات المرجعية: تُستخدم لشرح واجهة برمجة تطبيقات (API) محددة. عادةً ما تكون أقصر وأكثر تركيزًا. في توثيق Next.js، توجد الصفحات المرجعية في قسم مرجع API.

من الجيد معرفة: اعتمادًا على الصفحة التي تساهم فيها، قد تحتاج إلى اتباع أسلوب وصوت مختلف. على سبيل المثال، الصفحات المفاهيمية أكثر إرشادية وتستخدم كلمة أنت لخطاب المستخدم. بينما الصفحات المرجعية أكثر تقنية، تستخدم كلمات أمرية مثل "أنشئ، حدّث، اقبل" وتميل إلى حذف كلمة أنت.

الصوت والأسلوب

إليك بعض الإرشادات للحفاظ على أسلوب وصوت متسق عبر التوثيق:

• اكتب جملًا واضحة وموجزة. تجنب الاستطراد.
  • إذا وجدت نفسك تستخدم الكثير من الفواصل، فكر في تقسيم الجملة إلى جمل متعددة أو استخدام قائمة.
  • استبدل الكلمات المعقدة بأخرى أبسط. على سبيل المثال، استخدم بدلاً من استغل.
• كن حذرًا مع كلمة هذا. يمكن أن تكون غامضة ومربكة، لا تتردد في تكرار موضوع الجملة إذا كان غير واضح.
  • على سبيل المثال، "Next.js يستخدم React" بدلاً من "Next.js يستخدم هذا".
• استخدم الصوت الفاعل بدلاً من المبني للمجهول. الجملة الفاعلة أسهل في القراءة.
  • على سبيل المثال، "Next.js يستخدم React" بدلاً من "React يُستخدم بواسطة Next.js". إذا وجدت نفسك تستخدم كلمات مثل تم و_بواسطة_ فقد تكون تستخدم صوتًا مبنيًا للمجهول.
• تجنب استخدام كلمات مثل سهل، سريع، بسيط، فقط، إلخ. هذه مصطلحات ذاتية ويمكن أن تكون محبطة للمستخدمين.
• تجنب الكلمات السلبية مثل لا، لا يمكن، لن، إلخ. يمكن أن تكون محبطة للقراء.
  • على سبيل المثال، "يمكنك استخدام مكون Link لإنشاء روابط بين الصفحات" بدلاً من "لا تستخدم وسم <a> لإنشاء روابط بين الصفحات".
• اكتب بصيغة المخاطب (أنت/لك). هذا أكثر شخصية وجذبًا.
• استخدم لغة محايدة جندريًا. استخدم المطورون، المستخدمون، أو القراء عند الإشارة إلى الجمهور.
• إذا كنت تضيف أمثلة برمجية، تأكد من تنسيقها بشكل صحيح وأنها تعمل.

بينما هذه الإرشادات ليست شاملة، إلا أنها يجب أن تساعدك على البدء. إذا كنت ترغب في التعمق أكثر في الكتابة التقنية، تحقق من دورة الكتابة التقنية من جوجل.

شكرًا لك على المساهمة في التوثيق وكونك جزءًا من مجتمع Next.js!