المساهمة في ترجمة لغة Go بالأمثلة

شكرًا لاهتمامك بتحسين الترجمة العربية. يهدف هذا المستودع إلى تقديم ترجمة عربية دقيقة وسهلة القراءة مع البقاء متوافقًا مع مشروع Go by Example الأصلي.

قبل البدء

1. راجع جدول الأمثلة واختر تحسينًا لغويًا أو تقنيًا، أو افتح مسألة لتنسيق العمل عليه.
2. اقرأ مسرد المصطلحات والتزم بالمصطلحات المعتمدة.
3. ثبّت إصدار Go المحدد في go.mod واستخدم بيئة Bash لتشغيل أدوات المشروع.

على Windows، أبقِ نهايات الأسطر بصيغة LF:

$ git config --local core.autocrlf false

خطوات المساهمة

1. أنشئ Fork من المستودع 0xKa/gobyexample-ar من لوحة GitHub.

2. استنسخ نسختك وأضف المستودع الأصلي باسم upstream:

   $ git clone https://github.com/YOUR-USER/gobyexample-ar.git
   $ cd gobyexample-ar
   $ git remote add upstream https://github.com/0xKa/gobyexample-ar.git
   

3. ابدأ فرعًا جديدًا من أحدث master:

   $ git fetch upstream
   $ git switch -c fix/short-description upstream/master
   

4. عدّل ملفات المصدر المناسبة، ولا تعدّل public يدويًا.

5. شغّل البناء والفحوص والمعاينة المحلية الموضحة أدناه. إذا غيّرت شرح ملف Go، فقد يرسل البناء غير الاختباري المصدر العام إلى Go Playground لتحديث بصمته.

6. راجع التغيير قبل إرساله:

   $ git status --short
   $ git diff --check
   $ git diff
   

7. أنشئ commit واضحًا وادفع الفرع إلى Fork الخاص بك:

   $ git add path/to/changed-file
   $ git commit -m "fix(ar): describe the change"
   $ git push -u origin fix/short-description
   

8. من صفحة Fork على GitHub اضغط Compare & pull request. اجعل المستودع الأساسي 0xKa/gobyexample-ar والفرع الأساسي master، واشرح سبب التغيير والملفات المتأثرة ونتائج الفحوص، ثم أنشئ Pull Request.

9. تابع فحوص CI وملاحظات المراجعة، وادفع الإصلاحات إلى الفرع نفسه حتى تُدمج المساهمة.

مصدر المحتوى

المصدر الأساسي للموقع هو examples وtemplates وexamples.ar.txt، أما public فهو ناتج مولّد.

• تُترجم الشروح الكاملة التي تبدأ بـ // في ملفات Go.
• تُترجم الشروح التي تبدأ بـ # في ملفات .sh عندما تكون نصًا توضيحيًا.
• تُعدل عناوين الأمثلة في examples.ar.txt مع إبقاء المعرّفات الإنجليزية دون تغيير، ويُذكر المصطلح الإنجليزي في أول عنوان يقدّمه فقط دون تكراره في العناوين اللاحقة.
• تُعدل النصوص المشتركة في templates، ثم يعاد توليد public.
• لا تعدل ملفات public يدويًا، ولا ترسل تغييرًا في HTML المولّد دون تغيير مصدره.

قواعد الترجمة

• استخدم العربية الفصحى المعاصرة، وفضل العبارة الواضحة على الترجمة الحرفية.
• حافظ على المعنى التقني وتسلسل الشرح، ولا تضف سلوكًا غير موجود في المثال الأصلي.
• أبقِ الكلمات المحجوزة، وأسماء الأنواع والدوال والحزم والمعرّفات باللغة الإنجليزية وضمن تنسيق الكود، مثل for وrange وfmt.Println.
• لا تترجم الكود، أو السلاسل النصية التي ينتج عنها خرج متوقع، أو الأوامر، أو الخيارات، أو المسارات، أو عناوين URL، أو قيم JSON وXML، أو البصمات.
• استخدم علامات الترقيم العربية في النثر، واستخدم الأرقام 0-9 في السياقات التقنية لتطابق الكود والخرج.
• عند الحاجة إلى مصطلح إنجليزي غير مألوف، اذكر المقابل العربي أولًا ثم المصطلح الإنجليزي بين قوسين أو ضمن تنسيق الكود في أول ظهور له.
• حافظ على اتجاه النص التقني من اليسار إلى اليمين، ولا تضف محارف اتجاه مخفية إلى ملفات المصدر.
• إذا احتجت إلى مصطلح غير موجود في المسرد، أضفه إلى GLOSSARY.md ضمن التغيير نفسه.

البناء والاختبار

بعد تعديل المصادر، شغّل:

$ VERBOSE=1 tools/build
$ VERBOSE=1 TESTING=1 tools/build
$ tools/serve

يتحقق tools/test من اكتمال فهرس العناوين العربية، ووجود شرح عربي لكل مثال، وتطابق حالات التقدم، وعدم وجود محارف اتجاه مخفية. ويعمل البناء في وضع TESTING=1 دون إرسال المصادر إلى Go Playground، ويفشل إذا كانت البصمات أو الملفات المولّدة قديمة.

راجع الموقع محليًا على http://127.0.0.1:8000/، وتحقق خصوصًا من اختلاط العربية بالكود الإنجليزي ومن العرض على شاشة ضيقة.

يحسب المولد بصمة ملف Go كاملًا، بما في ذلك الشروح. لذلك قد يؤدي تغيير الشروح إلى تحديث ملف .hash المرتبط بالمثال وإرسال نسخة جديدة إلى Go Playground. أدرج ملف .hash الجديد ضمن التغيير إذا حدّثته أداة البناء.

ما يجب أن يتضمنه التغيير

• ملفات المصدر المترجمة في examples أو templates.
• الملفات المولّدة المقابلة داخل public.
• ملفات .hash التي حدثتها أداة البناء، إن وجدت.
• تحديث حالة المثال في PROGRESS.md إذا تغيرت حالة ترجمته أو مراجعته.
• تحديث GLOSSARY.md عند اعتماد مصطلح جديد.
• تغيير واحد مترابط دون تعديلات جانبية غير ضرورية.

قائمة المراجعة قبل طلب الدمج

• الترجمة عربية فصحى سليمة وتنقل المعنى الأصلي بدقة.
• المصطلحات متوافقة مع GLOSSARY.md.
• الكود والخرج والأوامر والمعرّفات لم تتغير دون سبب تقني.
• tools/build ونسخة TESTING=1 ينجحان.
• public مولّد من المصادر الحالية.
• عاينت اتجاه RTL وعزل الكود LTR والتنقل والروابط.
• حدّثت PROGRESS.md والملفات المولّدة والبصمات اللازمة، إن انطبق ذلك.

الأمثلة الجديدة والتغييرات الهيكلية

لا تضف مثالًا جديدًا أو تغير ترتيب التنقل في الترجمة وحدها. افتح أولًا نقاشًا في المشروع الأصلي، ثم تُزامن الإضافة بعد قبولها upstream.

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