كيف تنشر وثائق منتج بالعربية من دون أن تكسر RTL والبحث

إضافة dir="rtl" تستغرق دقيقة. المشكلات تبدأ بعدها.

قد يظهر العنوان في مكانه الصحيح، ثم تجد سهم «التالي» يشير إلى الجهة الخطأ. أو تكتب أمرًا داخل فقرة عربية فتقفز العلامة -d بعيدًا عنه. والأسوأ أن يبحث القارئ عن كلمة موجودة أمامه، ولا يحصل على نتيجة لأن طريقة كتابتها اختلفت بحرف واحد.

هذه قائمة فحص عملية لوثائق المنتج، لا شرحًا نظريًا لاتجاه النص. جرّبها على صفحة حقيقية قبل أن تنشر القسم العربي كله.

ابدأ بسطر سيئ عمدًا

لا تبدأ الاختبار بفقرة عربية صافية. اكتب سطرًا يجمع الأشياء التي تربك العرض:

شغّل الأمر docker compose up -d، ثم افتح المسار /docs/getting-started?lang=ar وتأكد أن الإصدار v2.4.1 ظاهر في الصفحة.

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

احتفظ بهذا السطر في صفحة اختبار داخل مشروعك. سيكشف أي تراجع في الاتجاه أسرع من مراجعة صفحة ترحيبية بسيطة.

استخدم خصائص CSS المنطقية

الخاصية margin-left تربط المسافة بجهة ثابتة. أما margin-inline-start فتربطها ببداية السطر، فتتغير تلقائيًا مع اتجاه الصفحة.

/* يرتبط بالجهة اليسرى دائمًا */
.nav-item {
  margin-left: 12px;
  border-left: 2px solid var(--accent);
}

/* يتبع اتجاه الصفحة */
.nav-item {
  margin-inline-start: 12px;
  border-inline-start: 2px solid var(--accent);
}

راجع الهوامش والحشو والحدود والتموضع. في Tailwind، تساعدك الأدوات ms-* وme-* وps-* وpe-* وstart-* وend-* على كتابة قاعدة واحدة للاتجاهين.

الأيقونات تحتاج قرارًا منفصلًا. اقلب السهم الذي يعني «السابق» أو «التالي»، لأنه يصف حركة داخل الواجهة. لا تقلب أيقونة تمثل شيئًا حقيقيًا مثل شعار أو هاتف أو لقطة شاشة.

اعزل الشيفرة عن الفقرة العربية

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

استخدم اتجاهًا صريحًا وعزلًا للشيفرة داخل السطر:

.docs-content :not(pre) > code {
  direction: ltr;
  unicode-bidi: isolate;
}

.docs-content pre {
  direction: ltr;
  text-align: left;
}

طبّق القاعدة في سطحَي الكتابة والقراءة. إذا بدا الأمر صحيحًا في المحرر ثم اختل بعد النشر، فلديك تنفيذان مختلفان لنفس المحتوى.

اختبر البحث بصيغ الكلمة التي يكتبها الناس

قد تظهر الكلمة نفسها بأكثر من صورة من دون أن يقصد الكاتب تغيير معناها. هذه أمثلة مناسبة لاختبار الفهرس:

النص في الصفحة	عبارة البحث التي يجب اختبارها	الفرق
الإعدادات	الاعدادات	همزة الألف
إِعْدادات	إعدادات	التشكيل
التحكــم	التحكم	التطويل
إلى	الي	الألف المقصورة والياء

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

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

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

لا تنسخ شجرة الإنجليزية حرفيًا

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

اجعل لكل لغة شجرتها الخاصة. اربط الصفحات المتقابلة بمعرّف ثابت، حتى لو اختلف الرابط أو ترتيب القسم. بهذه الطريقة يمكن أن يكون المسار الإنجليزي /getting-started والعربي /البدء من دون إجبار الفريق على شجرتين متطابقتين.

هذه هي الطريقة التي يتعامل بها Nibleaf مع اللغات: لكل لغة شجرة صفحات مستقلة، وتُربط الترجمات التي تقابل بعضها. إذا كنت تقارن هذا النهج بمولد يعتمد مجلدات الترجمة، راجع مقارنة Nibleaf وDocusaurus.

أعط محركات البحث إشارات متسقة

الصفحة العربية تحتاج أكثر من نص عربي ظاهر. افحص المصدر الناتج وتأكد من وجود الآتي:

<html lang="ar" dir="rtl">
<link rel="canonical" href="https://docs.example.com/ar/deploy" />
<link rel="alternate" hreflang="ar" href="https://docs.example.com/ar/deploy" />
<link rel="alternate" hreflang="en" href="https://docs.example.com/en/deploy" />
<link rel="alternate" hreflang="x-default" href="https://docs.example.com/en/deploy" />

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

راجع أيضًا العنوان والوصف وog:locale والبيانات المنظمة. لا يكفي أن يكون جسم المقال عربيًا بينما تقول بيانات Article إن لغته en.

اختبر الخط بدل الاعتماد على اسم العائلة

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

اكتب صفحة اختبار فيها:

• عنوان طويل مع التشكيل.
• فقرة تجمع العربية والإنجليزية والأرقام.
• أوزان الخط التي تستخدمها فعلًا.
• جدول وقائمة ورابط وشيفرة داخل السطر.

افتحها على Windows وAndroid وiOS إن كانت هذه أجهزة جمهورك. اضبط ارتفاع السطر بحسب الخط الفعلي، لا بحسب رقم ثابت من مقال. وألغ letter-spacing وtext-transform في العناوين العربية، لأن المسافات بين الحروف قد تكسر اتصالها.

راجع الهاتف ولوحة المفاتيح

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

قبل النشر، مر على هذه القائمة:

• اتجاه html صحيح منذ أول استجابة، لا بعد تشغيل JavaScript.
• الشيفرة داخل السطر وكتل الشيفرة تبقى LTR ويمكن نسخها.
• الأسهم والفواصل ومسار التنقل تتحرك في الاتجاه الصحيح.
• نتائج البحث تغطي صيغ الكلمات التي يستخدمها القراء فعلًا.
• الخط يحتوي على العربية في كل وزن مستخدم.
• الصفحات المتقابلة تعلن hreflang متبادلًا وcanonical متسقًا.
• العنوان والوصف والبيانات المنظمة تقول إن اللغة عربية.
• شجرة الصفحات العربية تستطيع أن تنمو من دون صفحات وهمية.

ما الذي ينجزه Nibleaf اليوم؟

Nibleaf يدعم شجرة مستقلة لكل لغة، واتجاه RTL في القارئ والمحرر، وعزل الشيفرة داخل النص، وواجهة عربية للموقع المنشور ولوحة العمل. يستخدم البحث tokenizer عربيًا مع التطبيع المحدود ومسار صرفي خفيف ومحافظ، وينشئ canonical وhreflang للصفحات المرتبطة بترجمات فعلية.

هناك حدود واضحة أيضًا. هذا المسار ليس محللًا صرفيًا قاموسيًا كاملًا، ولن يوحّد كل صيغة أو يصلح ترجمة رديئة أو مصطلحات غير متسقة. هذه مسؤولية المحتوى والاختبار.

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

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