8000 arabic-docx-skill/SKILL.md at main · alahmadics/arabic-docx-skill · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
113 lines (88 loc) · 4.23 KB

SKILL.md

File metadata and controls

113 lines (88 loc) · 4.23 KB

arabic-docx — مكتبة إنشاء وتحويل مستندات Word عربية RTL

مكتبة Python معتمدة لإنشاء مستندات Word عربية بتنسيق RTL كامل وصحيح، وتحويل أي مستند LTR موجود إلى RTL.


المشكلة التي تحلها

  • <w:bidi/> على الفقرة وحدها لا يكفي — الأحرف المحايدة (◄ ، ☐ ، أقواس) كانت تأخذ اتجاه LTR
  • الحل الكامل: <w:rtl/> على كل run + <w:bidiVisual/> على كل جدول + <w:bidi/> على القسم
  • إضافة جديدة: w:lang w:val="ar-SA" على كل run + خط Tajawal بدل Arial + native bullets

الملفات المتاحة

الملف الوظيفة
/app/rtl_helper.py مكتبة بناء المستندات العربية من الصفر
.agents/skills/arabic-docx/convert_to_rtl.py تحويل مستند LTR موجود إلى RTL
.agents/skills/arabic-docx/references/arabic_qa.md مرجع الجودة العربية (12 حالة اختبار + 7 ثوابت)

١. إنشاء مستند عربي جديد (rtl_helper)

import sys; sys.path.insert(0, '/app')
from rtl_helper import (
    set_rtl_para,       # تفعيل RTL على فقرة
    make_run,           # إضافة نص مع w:rtl + w:lang + w:cs مضمونة
    add_para,           # فقرة كاملة RTL
    add_native_bullet,  # نقطة أصلية (w:numPr) — مفضّلة
    add_bullet,         # نقطة بصرية ◄ — للتوافق القديم
    add_section_title,  # عنوان قسم (أخضر، عريض)
    add_quote,          # استشهاد قانوني
    add_field,          # حقل إدخال
    add_table,          # جدول RTL كامل
    add_check_row_rtl,  # صف تحقق
    set_table_rtl,      # تفعيل bidiVisual على جدول
    audit_arabic_docx,  # فحص هيكلي صارم (pass/fail)
)

القواعد الإلزامية (7 ثوابت)

  1. كل فقرة → set_rtl_para(para) — يضيف w:bidi
  2. كل run → make_run(para, text) — يضيف w:rtl + w:lang ar-SA + w:cs=Tajawal
  3. كل جدول → set_table_rtl(table) — يضيف w:bidiVisual
  4. الخط: Tajawal (افتراضي) مع Arial كـ fallback
  5. لا Unicode bidi controls (RLM, LRM, RLE...)
  6. النقاط: add_native_bullet() مفضّلة على add_bullet()
  7. لا خط مائل (italic) على نص عربي

فحص الجودة بعد الإنشاء

result = audit_arabic_docx(doc)
# → يطبع تقرير: PASS ✅ أو FAIL ❌ مع تفاصيل
# → يعيد True/False

٢. تحويل مستند LTR موجود إلى RTL

import sys
sys.path.insert(0, '/app/.agents/skills/arabic-docx')
from convert_to_rtl import convert_docx_to_rtl

output = convert_docx_to_rtl('/path/to/input.docx')
print(output)

٣. مرجع الجودة العربية

اقرأ references/arabic_qa.md قبل تسليم أي مستند عربي مهم. يحتوي على:

  • 7 ثوابت هيكلية (OOXML invariants) — إلزامية
  • 7 ممنوعات (Unicode bidi controls، عكس الأحرف، نقاط كنص...)
  • 12 حالة اختبار (acceptance corpus) — افحصها بصرياً في Word
  • 3 طبقات جودة (Structural + Layout + Application QA)
  • تشخيص الأخطاء الشائعة
  • ترقيات مطلوبة على rtl_helper.py

المصدر: مقتبس من SultanAlsafran/agent-skills (arabic-presentations, MIT) — مكيّف لبيئة Word/docx.


نموذج مستند كامل من الصفر

from docx import Document
from docx.shared import Cm
import sys; sys.path.insert(0, '/app')
from rtl_helper import *

doc = Document()
for sec in doc.sections:
    sec.right_margin = Cm(3)
    sec.left_margin = Cm(2.5)

add_para(doc, "عنوان المستند", bold=True, size=14, center=True)
add_section_title(doc, "أولاً: البيانات")
add_field(doc, "الاسم")
add_native_bullet(doc, "بند أول")
add_native_bullet(doc, "بند ثان")
add_table(doc, ["م", "البند", "الملاحظة"], [["1", "نص", "—"]])

# فحص الجودة قبل الحفظ
audit_arabic_docx(doc)
doc.save('output.docx')
0