diff --git a/contributing-guides/style-guide.ar.md b/contributing-guides/style-guide.ar.md new file mode 100644 index 00000000000000..25e3fa224b5bd6 --- /dev/null +++ b/contributing-guides/style-guide.ar.md @@ -0,0 +1,252 @@ +# إرشادات التنسيق + +تستعرض هذه الصفحة إرشادات التنسيق لصفحات `tldr` الخاصة باللغة العربية. + +## التنسيق العام + +يجب أن يتبع الشكل الأساسي لكل صفحة القالب التالي وألا يتجاوز 8 أمثلة للأمر الواحد: + +```md +# اسم الأمر + +> وصف مختصر وواضح للأمر. +> يفضل أن يكون في سطر واحد؛ سطرين مقبولين إذا لزم الأمر. +> لمزيد من التفاصيل: . + +- وصف الكود: + +`command_name options` + +- وصف الكود: + +`command_name options` + +... +``` +مثال: + +```md +# krita + +> برنامج للرسم والتلوين مصمم للفنانين الرقميين. +> انظر أيضًا: `gimp`. +> مزيد من التفاصيل: . + +- بدء 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 وما فوق. +> المزيد من التفاصيل: . +``` + +## الصفحات + +### اختلافات المنصات + +إذا كنت قلقًا من أن الأوامر قد تختلف بين المنصات أو أنظمة التشغيل (مثل 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`. +> مزيد من التفاصيل: . + +- عرض التوثيقات الخاصة بالأمر المقابل في 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`. +> مزيد من التفاصيل: . + +- عرض التوثيقات للأمر الأصلي: + +`tldr new-item` +``` + +3. **يوفر لقبًا جديدًا يتعارض مع برامج أخرى، وأشهر مثال هو تضمين** curl و wget كألقاب لـ Invoke-WebRequest (مع مجموعة غير متوافقة من خيارات الأوامر). +لاحظ أن الألقاب الخاصة بـ PowerShell التي تقع في هذه الفئة غالبًا ما تكون حصرية لـ Windows. + +في هذه الحالة، قدم ملاحظة وطريقة لتحديد ما إذا كان الأمر يشير حاليًا إلى أمر PowerShell (من خلال اللقب) أو إلى أمر آخر. على سبيل المثال: +```md +# curl + +> في PowerShell، قد يكون هذا الأمر هو لقب لـ `Invoke-WebRequest` عندما لا يكون البرنامج الأصلي `curl` () مثبتًا بشكل صحيح. +> لمزيد من التفاصيل: . + +- تحقق مما إذا كان `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`).