style-guide: add Arabic translation

contributing-guides/style-guide.ar.md

@@ -0,0 +1,252 @@
+# إرشادات التنسيق
+
+تستعرض هذه الصفحة إرشادات التنسيق لصفحات `tldr` الخاصة باللغة العربية.
+
+## التنسيق العام
+
+يجب أن يتبع الشكل الأساسي لكل صفحة القالب التالي وألا يتجاوز 8 أمثلة للأمر الواحد:
+
+```md
+# اسم الأمر
+
+> وصف مختصر وواضح للأمر.
+> يفضل أن يكون في سطر واحد؛ سطرين مقبولين إذا لزم الأمر.
+> لمزيد من التفاصيل: <https://example.com/command_name/help/page>.
+
+- وصف الكود:
+
+`command_name options`
+
+- وصف الكود:
+
+`command_name options`
+
+...
+```
+مثال:
+
+```md
+# krita
+
+> برنامج للرسم والتلوين مصمم للفنانين الرقميين.
+> انظر أيضًا: `gimp`.
+> مزيد من التفاصيل: <https://docs.krita.org/en/reference_manual/linux_command_line.html>.
+
+- بدء Krita:
+
+`krita`
+
+- فتح ملفات محددة:
+
+`krita {{path/to/image1 path/to/image2 ...}}`
+
+- بدء بدون شاشة بداية:
+
+`krita --nosplash`
+
+- بدء مع مساحة عمل معينة:
+
+`krita --workspace {{Animation}}`
+
+- بدء في وضع ملء الشاشة:
+
+`krita --fullscreen`
+```
+
+> [!NOTE]
+> يجب أن يتطابق اسم ملف الصفحة والعنوان مع اسم الأمر تمامًا. يمكن أن يكون عنوان الصفحة بأي حالة حروف، بينما يجب أن تكون أسماء ملفات Markdown الخاصة بالصفحات بحروف صغيرة.
+
+هناك أداة "linter" تفرض هذا التنسيق.
+يتم تشغيلها تلقائيًا مع كل "Pull Request"،
+ولكن يمكنك تثبيتها لاختبار مساهماتك محليًا قبل تقديمها:
+
+```sh
+npm install --global tldr-lint
+tldr-lint path/to/tldr_page.md
+```
+
+لطرق أخرى لاستخدام `tldr-lint`، مثل فحص مجلد كامل، يمكنك الاطلاع على
+[صفحة `tldr-lint` على `tldr`](https://github.com/tldr-pages/tldr/blob/main/pages/common/tldr-lint.md). بدلاً من ذلك، يمكنك أيضًا استخدام اختصارها `tldrl`.
+
+اعتمادًا على عميلك، قد تتمكن من معاينة الصفحة محليًا باستخدام خيار `--render`:
+
+```sh
+tldr --render path/to/tldr_page.md
+```
+
+### القواعد الخاصة بـ PowerShell
+
+عند توثيق أوامر PowerShell، يرجى ملاحظة قواعد التسمية التالية.
+
+- يجب أن يكون اسم الملف مكتوبًا بحروف صغيرة، مثل `invoke-webrequest.md` بدلاً من `Invoke-WebRequest.md`.
+- يجب أن يكون عنوان/رأس الصفحة مكتوبًا كما هو (بما يتطابق مع التهجئة التي يقصدها مايكروسوفت أو مؤلف الأمر PowerShell)، مثل `Invoke-WebRequest` بدلاً من `invoke-webrequest`.
+- يجب أيضًا كتابة اسم الأمر والخيارات في الأمثلة كما هي، مثل `Command-Name {{input}} -CommandParameter {{value}}` بدلاً من `command-name {{input}} -commandparameter {{value}}`.
+
+نظرًا للاختلافات في التوافق بين الإصدارات [وإزالة الأوامر الخاصة بـ Windows](https://learn.microsoft.com/powershell/scripting/whats-new/differences-from-windows-powershell) في PowerShell 6.x، تأكد من أن
+الأمر يعمل بين **PowerShell 5.1** (المعروف أيضًا باسم "PowerShell Windows القديم" كما هو مثبت في Windows 10 و11) و **أحدث إصدار من PowerShell متعدد المنصات** (المعروف سابقًا باسم PowerShell Core).
+
+لذا، إذا كان الأمر أو خياراته غير متوفرة أو تحتوي على سلوكيات مختلفة بين كل إصدار، يرجى ملاحظة ذلك بلطف في الوصف. على سبيل المثال:
+
+```md
+# Clear-RecycleBin
+
+> حذف العناصر من سلة المهملات.
+> ملاحظة: يمكن استخدام هذا الأمر فقط من خلال إصدارات PowerShell 5.1 وما دون، أو 7.1 وما فوق.
+> المزيد من التفاصيل: <https://learn.microsoft.com/powershell/module/microsoft.powershell.management/clear-recyclebin>.
+```
+
+## الصفحات
+
+### اختلافات المنصات
+
+إذا كنت قلقًا من أن الأوامر قد تختلف بين المنصات أو أنظمة التشغيل (مثل Windows مقابل macOS)، 
+فإن معظم [عملاء صفحات tldr](https://github.com/tldr-pages/tldr/wiki/Clients) سيختارون النسخة الأنسب من الأمر لعرضها للمستخدم النهائي.
+
+في هذه الحالة، سيتم عرض معلومات النسخة الخاصة بـ Windows من أمر `cd` (المخزنة في `pages.ar/windows/cd.md`) بشكل افتراضي لمستخدمي Windows، 
+وسيتم عرض النسخة العامة/المشتركة (المخزنة في `pages.ar/common/cd.md`) للمستخدمين على أنظمة Linux وmacOS ومنصات أخرى.
+
+### الألقاب
+
+إذا كان يمكن استدعاء أمر ما باستخدام أسماء بديلة (مثلًا، يمكن استدعاء `vim` باستخدام `vi`)، يمكن إنشاء صفحات ألقاب للإشارة إلى اسم الأمر الأصلي للمستخدم.
+
+```md
+# command_name
+
+> هذا الأمر هو لقب لـ `اسم-الأمر-الأصلي`.
+
+- عرض الإرشادات للأمر الأصلي:
+
+`tldr original_command_name`
+```
+
+مثال:
+
+```md
+# vi
+
+> هذا الأمر هو لقب لـ `vim`.
+
+- عرض الإرشادات للأمر الأصلي:
+
+`tldr vim`
+
+```
+
+- يمكن العثور على قوالب صفحات الألقاب المترجمة مسبقًا [هنا](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md).
+
+#### الألقاب الخاصة بـ PowerShell
+
+قد تقدم بعض أوامر PowerShell ألقابًا تقع في واحدة من هذه الفئات الثلاث:
+
+1. **استبدال أمر موجود في موجه أوامر Windows (`cmd`)**، مثل استبدال `cd` بـ `Set-Location` مع خيارات أوامر مختلفة. في هذه الحالة، أضف ملاحظة اللقب التالية في السطر الثاني من وصف أمر tldr للأمر الأصلي في موجه الأوامر، على سبيل المثال:
+
+```md
+# cd
+
+> عرض الدليل الحالي أو الانتقال إلى دليل آخر.
+> في PowerShell، هذا الأمر هو لقب لـ `Set-Location`. هذه الوثائق تستند إلى النسخة الخاصة بـ Command Prompt (`cmd`) من `cd`.
+> مزيد من التفاصيل: <https://learn.microsoft.com/windows-server/administration/windows-commands/cd>.
+
+- عرض الإرشادات الخاصة بالأمر المقابل في PowerShell:
+
+`tldr set-location`
+```
+
+> [!NOTE]
+> مثال "عرض الإرشادات للأمر المعادل في PowerShell" اختياري ويجب استبعاده إذا كانت الصفحة تحتوي بالفعل على الحد الأقصى من الأمثلة (8).
+
+2. **يوفر لقبًا جديدًا يمكن تنفيذه فقط في PowerShell**، مثل `ni` لـ `New-Item`. في هذه الحالة، استخدم [قالب اللقب القياسي](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md)، ولكن أضف كلمة "في PowerShell" (أو ما يعادلها) للإشارة إلى أن الأمر حصري لـ PowerShell. على سبيل المثال:
+
+```md
+# ni
+
+> في PowerShell، هذا الأمر هو لقب لـ `New-Item`.
+> مزيد من التفاصيل: <https://learn.microsoft.com/powershell/module/microsoft.powershell.management/new-item>.
+
+- عرض الإرشادات للأمر الأصلي:
+
+`tldr new-item`
+```
+
+3. **يوفر لقبًا جديدًا يتعارض مع برامج أخرى، وأشهر مثال هو تضمين** curl و wget كألقاب لـ Invoke-WebRequest (مع مجموعة غير متوافقة من خيارات الأوامر).
+لاحظ أن الألقاب الخاصة بـ PowerShell التي تقع في هذه الفئة غالبًا ما تكون حصرية لـ Windows.
+
+في هذه الحالة، قدم ملاحظة وطريقة لتحديد ما إذا كان الأمر يشير حاليًا إلى أمر PowerShell (من خلال اللقب) أو إلى أمر آخر. على سبيل المثال:
+```md
+# curl
+
+> في PowerShell، قد يكون هذا الأمر هو لقب لـ `Invoke-WebRequest` عندما لا يكون البرنامج الأصلي `curl` (<https://curl.se>) مثبتًا بشكل صحيح.
+> لمزيد من التفاصيل: <https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest>.
+
+- تحقق مما إذا كان `curl` مثبتًا بشكل صحيح عن طريق طباعة رقم الإصدار الخاص به. إذا أظهرت هذه الأوامر خطأ، قد تكون PowerShell قد استبدلت هذا الأمر بـ `Invoke-WebRequest`:
+
+`curl --version`
+
+- عرض الإرشادات الخاصة بأمر `curl` الأصلي:
+
+`tldr curl -p common`
+
+- عرض الإرشادات الخاصة بأمر `Invoke-WebRequest` في PowerShell:
+
+`tldr invoke-webrequest`
+```
+
+## الكتابة العامة
+
+### التأكيد
+
+لا تستخدم *الخط المائل* (Italic) أو **الخط العريض** (Bold) أو أي تنسيق نصي آخر في الصفحات. هذه محجوزة لتأكيد العميل على العناصر القابلة للتغيير.
+
+### صيغة الأمر
+
+- **يجب أن تكون جميع الأوصاف مكتوبة بصيغة الأمر.**
+
+عند كتابة الأوصاف لأمثلة الأوامر، تحقق من أي أخطاء نحوية. يُفضل استخدام "اذهب إلى المجلد المحدد" بدلاً من:
+
+- `سيذهب هذا الأمر إلى المجلد المحدد`
+- `لنذهب إلى المجلد المحدد!`
+
+### الحالات الخاصة
+
+- إذا كان الأمر يقوم بإجراء تغييرات لا رجعة فيها على نظام الملفات أو الأجهزة،  
+  فاكتب كل مثال بطريقة لا يمكن نسخها ولصقها بشكل متهور.  
+  على سبيل المثال، بدلاً من `ddrescue --force --no-scrape /dev/sda /dev/sdb`  
+  اكتب `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}`  
+  واستخدم القالب `{{/dev/sdXY}}` لأجهزة الكتل بدلاً من `/dev/sda1`.
+
+بشكل عام، يجب أن تجعل القوالب من السهل فهم كيفية استخدام الأمر وملء القيم.
+
+> [!NOTE]
+> لا تترجم الplaceholders مثل `{{path/to/file}}` إلى `{{المسار/إلى/الملف}}` لتجنب الإلتباس
+
+يجب استخدام صياغة تقنية على خطوط الوصف باستخدام تنسيق `backtick`.  
+استخدم الخطوط المائلة الخلفية `backticks` مع التالي:
+
+- المسارات، مثل `package.json`، `/etc/package.json`.  
+- الامتدادات، مثل `.dll`.  
+- الأوامر، مثل `ls`.  
+- التدفقات القياسية: `stdout`، `stdin`، `stderr`.  
+  **لا تستخدم** الأسماء الكاملة (مثل: standard output).  
+- خوارزميات الضغط، مثل `zip`، `7z`، `xz`.
+
+### الفاصلة التسلسلية
+
+- عند الإعلان عن قائمة تحتوي على 3 عناصر أو أكثر،  
+  استخدم [الفاصلة التسلسلية](https://en.wikipedia.org/wiki/Serial_comma)،  
+  والمعروفة أيضًا باسم فاصلة أكسفورد،  
+  حيث أن حذفها يمكن أن يؤدي إلى التباس.
+
+> حذف فروع Git، tags، و remotes.
+
+المثال أعلاه لا يستخدم فاصلة تسلسلية، لذا قد يعني أحد الأمرين التاليين:
+
+- حذف فروع Git المسماة `tags` و`remotes`.  
+- حذف جميع الفروع، tags، وremotes الخاصة بـGit.
+
+يمكن حل هذا الالتباس بإضافة فاصلة قبل كلمة "و" أو "أو" في العنصر الأخير من القائمة.
+
+> حذف فروع Git وtags وremotes.
+
+> [!NOTE]  
+> يمكن كتابة أسماء العلامات التجارية والمشاريع بحروف كبيرة في الوصف عند الاقتضاء  
+> (على سبيل المثال، استخدم `أداة للتعامل مع مستودع Git` بدلاً من `أداة للتفاعل مع مستودع git`).