انتقل إلى المحتوى

ترجمة آلية

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

المصدر الإنجليزي · الإبلاغ عن مشكلة في الترجمة

التدويل

تتعامل الوثائق مع اللغتين الإنجليزية والصينية المبسطة كمصادر قانونية مراجعة. كل لغة أخرى مفعلة هي مشتق مولّد. سجل اللغات، توجيه المصدر، تكوين النموذج، وحدود API موجودة في i18n/config.toml.

1. تغطية اللغة وتوجيه المصدر

يقوم السجل بتفعيل مجموعة مركزة من 12 لغة موقع. يغطي جميع اللغات الرسمية الست للأمم المتحدة: العربية، الصينية، الإنجليزية، الفرنسية، الروسية، والإسبانية. بالإضافة إلى ذلك، يغطي اليابانية، الكورية، والصينية التقليدية لشرق آسيا، بالإضافة إلى الألمانية، الإيطالية، والبرتغالية لأوروبا. الإنجليزية والصينية المبسطة قانونيتان، لذا فإن 10 لغات هي ترجمات آلية.

تستخدم اليابانية، الكورية، والصينية التقليدية الصينية المبسطة كمصدر لها. جميع اللغات المولّدة الأخرى تستخدم الإنجليزية. اختيار المصدر صريح لكل لغة؛ لا يخمن المترجم أبدًا من اسم لغة أو من أحرف المستند.

تتطلب إضافة لغة إدخالات متطابقة في i18n/config.toml وقائمة لغات MkDocs i18n. يرفض تدقيق الوثائق السجلات غير المتسقة.

2. عقد المستند القانوني

كل صفحة MkDocs لها ملف إنجليزي وملف .zh-CN.md. طلب سحب، دفع إلى main، أو تشغيل جودة مرسل يدويًا يغير إصدارًا قانونيًا واحدًا يجب أن يتضمن نظيره في نطاق الالتزام المفحوص. يتحقق سير عمل الجودة من:

  • الأزواج القانونية واقتران الزوج المتغير؛
  • تكافؤ مستوى العنوان وحدود الكود؛
  • الروابط المحلية ومراجع المصدر؛
  • جرد الاختبارات والتجارب؛
  • بناء صارم لكل لغة مكونة.

يمكن كتابة النثر القانوني يدويًا أو بمساعدة الذكاء الاصطناعي، ولكن يجب الالتزام به ومراجعته كمصدر عادي. لا يتم استدعاء API الترجمة أبدًا من سير عمل طلب السحب.

3. ترقيم العناوين واستقرار المعرفات

يخزن مصدر Markdown نص العنوان الوصفي بدون أرقام مخطط تفصيلي. أثناء كل بناء MkDocs، يضيف scripts/mkdocs_heading_numbers.py أرقامًا محلية للصفحة لعناوين H2–H6. تستخدم صفحات دليل المستخدم أحرفًا صغيرة في H2 (a.، b.) وأحرفًا بالإضافة إلى أرقام عشرية للفروع (a.1، a.1.1)؛ تحتفظ الصفحات الأخرى بمخططات تفصيلية عشرية للصفحة. بشكل منفصل، يستخدم التنقل الأيسر لدليل المستخدم أرقامًا عشرية هرمية مثل 1.1. تظل عناوين الصفحات H1 وأقسام التنقل ذات المستوى الأعلى غير مرقمة. الأرقام المولّدة هي بيانات وصفية للعرض: نقل قسم يغير رقمه المرئي دون تغيير معرف المقطع الخاص به.

يجعل خطاف البناء كل معرف عنوان صريحًا قبل إضافة الرقم المرئي. يحتفظ i18n/legacy-heading-anchors.json بأسماء مستعارة للمقاطع التي تم نشرها قبل إزالة أرقام المخطط التفصيلي المخزنة. لا تقم بتحرير خريطة التوافق المولّدة هذه بشكل عرضي، ولا تقم بإضافة أرقام مخطط تفصيلي يدويًا مرة أخرى إلى Markdown القانوني أو المولّد؛ يرفض تدقيق الوثائق ذلك.

4. عقد المستند المولّد

تستخدم الصفحات المولّدة وضع لاحقة MkDocs، مثل index.fr.md أو guide/configuration.ja.md. تحتوي كل صفحة على بيانات أمامية حتمية تسجل:

  • اللغة المصدر القانونية والمسار؛
  • ملخص SHA-256 للمصدر؛
  • النموذج المحلول وإصدار المطالبة؛
  • أن الصفحة هي ترجمة آلية.

يسجل i18n/manifest.json بالإضافة إلى ذلك ملخصات الإخراج وبصمات إدخال الترجمة. تصبح الصفحة قديمة عندما يتغير مصدرها، أو قاموسها، أو مطالبتها، أو نموذجها، أو إخراجها المولّد. يطلب المترجم فقط الوحدات القديمة ما لم يتم طلب إعادة بناء كاملة صراحة.

تحتفظ العناوين المترجمة بمعرفاتها المحلية الطبيعية وتتلقى أسماء مستعارة مخفية للمعرفات القانونية المصدر. نظرًا لأن وجهات روابط Markdown محمية بخلاف ذلك من تغييرات النموذج، تحافظ هذه الأسماء المستعارة على روابط المقاطع داخل الصفحة وعبر الصفحات صالحة في كل لغة. يمكن تحديث الأسماء المستعارة دون اتصال دون استدعاء API ترجمة آخر.

يجب عدم تحرير الملفات المولّدة يدويًا. يقوم سير عمل الترجمة للفرع الرئيسي بإعادة إنشائها ويضع نقطة تفتيش لكل لغة مكتملة كالتزام واحد على فرع مولّد فقط مشتق من SHA الذي تم التحقق من جودته بالضبط. يمكن لتشغيل لاحق التحقق من ذلك الفرع وإعادة استخدامه، لذا فإن الانقطاع يتجاهل فقط اللغة التي لا تزال قيد التقدم. يظل main دون تغيير حتى يقوم سير العمل بتشغيل تدقيق اللغة المولّدة المطلوب، ومجموعة الاختبارات الكاملة، والبناء الصارم لجميع اللغات. ثم يتحقق من أن main لم يتقدم، ويُرقّي نقطة التفتيش التي تم التحقق منها بدفع واحد سريع للأمام، وينشر نفس قطعة الموقع التي تم التحقق منها.

5. Markdown المحمي وعقد المطالبة

قبل طلب API، يستبدل المترجم البيانات الأمامية، والكود المسوّر، والكود المضمن، ووجهات الروابط، وعلامات HTML، وعناوين URL العارية ببدائل غير قابلة للتغيير. يتم رفض الرد إذا كان أي بديل مفقودًا أو مكررًا أو مخترعًا أو منقولًا خارج عقد الإخراج القابل للاسترداد.

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

يتم إصدار مطالبات Markdown وكتالوج التنقل تحت i18n/prompts/. يحمل i18n/glossary.json مصطلحات المنتج والأوامر المستقرة.

6. تكوين النموذج وبيانات الاعتماد

يتم تكوين النموذج الافتراضي كـ deepseek-v4-flash. لا يتفرع التنفيذ على هذا الاسم. يتطلب تغيير النموذج في المستقبل فقط تحديث i18n/config.toml، أو تمرير --model، أو تعيين متغير سير العمل DEEPSEEK_TRANSLATION_MODEL. يتم تسجيل النموذج المحلول في كل صفحة مولّدة وإدخال بيان.

يقرأ GitHub Actions بيانات اعتماد API فقط من السر الخاص بالمستودع المسمى DEEKSEEK_API_KEY. يتم حقنه فقط في خطوة التوليد عندما يبلغ الخطة غير المتصلة عن وحدات معلقة مدعومة بـ API. لا يكون متاحًا أبدًا لكود طلب السحب غير الموثوق أو خطوات التخطيط والتنظيف والتحقق بدون API. لا تتم كتابة قيم المصادقة أبدًا إلى السجلات أو الملفات المولّدة أو القطع الأثرية أو البيان.

7. إشعار الصفحة وتفضيل اللغة

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

في أول زيارة للزائر للصفحة الجذرية، يقارن الموقع navigator.languages مع بدائل اللغة المكونة. يتم تحديد لغة متوافقة عند توفرها. يتم حفظ اختيار اللغة اليدوي محليًا ويأخذ الأولوية في الزيارات اللاحقة.

8. أوامر المشرف

عرض عدد وحدات الترجمة المعلقة دون إجراء مكالمات شبكة:

uv run python scripts/translate_docs.py --plan

التحقق من أن كل صفحة وكتالوج مولّد حديث:

uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required

تحديث الأسماء المستعارة لعناوين المصدر المستقرة دون استدعاءات API:

uv run python scripts/translate_docs.py --refresh-heading-anchors

فرض إعادة إنشاء كاملة بنموذج صريح:

DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
  --force --model deepseek-v4-flash
يستخدم سير العمل الآلي السر الخاص بالمستودع بدلاً من وضع مفتاح على سطر الأوامر.