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

مرحبًا بك في دليل المساهمة في توثيق 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: Intellisense وتمييز التركيب لـ MDX.
• Prettier: تنسيق ملفات MDX عند الحفظ.

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

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

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

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

هيكل الملف

تستخدم الوثائق توجيه نظام الملفات. يمثل كل مجلد وملف داخل /docs جزءًا من المسار. تُستخدم هذه الأجزاء لإنشاء مسارات URL، والتنقل، وفتات الخبز.

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

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

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

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

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.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
version: experimental
---

وثائق App و Pages

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

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

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

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

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

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

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

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

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

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

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

هذا المحتوى مشترك بين App و Pages.

<PagesOnly>

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

</PagesOnly>

هذا المحتوى مشترك بين App و Pages.

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

كتل الكود

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

على سبيل المثال، إذا كنت تريد عرض كيفية استخدام مكون <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، نستخدم مجموعات اللغة والامتداد التالية.

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

• تأكد من استخدام امتداد js مع كود JSX في ملفات JavaScript.
• على سبيل المثال، ```jsx filename="app/layout.js"

مبدل 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!