Vale CLI

عندما يكتب كل مطور أو وكيل ذكي التوثيق بطريقته، تظهر أسماء مختلفة للميزة نفسها، وصياغات طويلة، ومصطلحات غير معتمدة لا تُكتشف إلا أثناء المراجعة. Vale CLI مدقق أسلوب للنصوص يعمل مثل أدوات فحص الكود: يقرأ Markdown وMDX وHTML وصيغًا أخرى، ويقارن الكتابة بقواعد فريقك، ثم يعرض الملف والسطر وشدة الملاحظة واسم القاعدة. قيمته ليست «كتابة النص بدلًا عنك»، بل جعل قواعد الكتابة قابلة للتكرار محليًا وفي Git وCI.

🧭 ما أداة Vale CLI؟

Vale أداة سطر أوامر مفتوحة المصدر لفحص النثر: الشروحات، صفحات التوثيق، التعليقات داخل الكود، أوصاف OpenAPI، ورسائل Git عند إعدادها لذلك. بخلاف البحث النصي البسيط، تفهم بنية صيغ التوثيق؛ تستطيع فحص فقرة أو عنوان مع تجاوز كتلة الكود والرابط. لا تفرض أسلوبًا جاهزًا واحدًا: تختار حزمة منشورة مثل Microsoft أو Google أو Red Hat، أو تبني قواعد YAML لمصطلحاتك وصوتك التحريري.

تعمل الأداة على macOS وWindows وLinux، ويمكن تشغيلها من الطرفية أو محرر يدعم LSP أو pre-commit أو GitHub Actions. الفحص المحلي لا يحتاج حسابًا ولا يرفع النصوص، لكن vale sync يحتاج شبكة لتنزيل الحزم التي تسميها في الإعداد.

رسم توضيحي أصلي لمسار العمل؛ لا يمثل واجهة المنتج.

🎯 كيف ستفيدك؟

تناسب Vale مطورًا منفردًا أو فريقًا صغيرًا ينشر توثيقًا، README، تعليمات تشغيل، أو محتوى يولده وكلاء AI. بدل أن تذكّر الوكيل في كل محادثة بأن اسم المنتج «NASQ» وليس «Nasq»، أو تراجع يدويًا عبارات غير مرغوبة، تحفظ القاعدة داخل المشروع. بعدها يرى المطور والوكيل وCI النتيجة نفسها.

مثال عملي: لديك توثيق عربي وإنجليزي. تستخدم حزمة جاهزة للنص الإنجليزي، وتضيف قواعد داخلية للمصطلحات المعتمدة في اللغتين. قبل دمج أي Pull Request، يفحص Vale الملفات المتغيرة؛ الأخطاء تعيد صاحب التغيير إلى السطر المحدد، بينما تبقى الاقتراحات للتحسين دون إيقاف الدمج إذا ضبطتها بهذه الطريقة.

القيمة المضافة هي تحويل «ذوق المحرر» إلى قواعد ظاهرة وقابلة للمراجعة في Git. لكنها ليست بديلًا عن محرر بشري: لا تفهم صحة القرار التجاري، ولا تضمن دقة الترجمة، ولا تقيّم النحو العربي تلقائيًا بحزم الإنجليزية.

🌟 الميزات والقدرات الرئيسية

1. فحص واعٍ ببنية Markdown وMDX وHTML

يحلل Vale المستند قبل تشغيل القواعد. لهذا تستطيع القاعدة استهداف عنوان أو فقرة أو تعليق، بينما تُستبعد الروابط وكتل الكود بحسب الصيغة والإعداد. توثق الأداة صيغًا تشمل Markdown وMDX وAsciiDoc وreStructuredText وHTML وXML وDITA وOrg وQuarto وTypst وJupyter وغيرها.

كما تستطيع Views استخراج الكتابة من ملفات ليست مستندات تقليدية: وصف داخل OpenAPI بصيغة YAML، خلية Markdown داخل Notebook، أو نص داخل رسالة commit. في المصدر البرمجي تستطيع محركات tree-sitter استخراج التعليقات وdocstrings للغات موثقة مثل Go وRust وPython وJavaScript وTypeScript وJava.

• أين تستخدمها: على ملف أو مجلد، مثل vale docs/.
• الفائدة: يقل الضجيج الناتج عن فحص الكود والروابط كأنهما جمل عادية.
• القيد: الصيغ المتقدمة قد تحتاج View أو مكوّنًا إضافيًا؛ وجود اسم الصيغة في الوثائق لا يعني أن كل بناء خاص فيها مغطى بلا إعداد.

رسم توضيحي لبنية الفحص، وليس لقطة من الواجهة.

2. حزم أسلوب جاهزة وقواعدك الخاصة

لا يأتي Vale بأحكام تحريرية إجبارية. ملف .vale.ini يحدد مجلد الأنماط، أقل شدة تريد عرضها، والحزم والقواعد المفعلة لكل نوع ملف. تستطيع البدء بحزمة منشورة، ثم إنشاء قواعد YAML خاصة بك.

أبسط قاعدة مصطلحات تستخدم substitution: إذا ظهر اسم قديم، تعرض الاسم المعتمد وربما إجراء تصحيح. توجد نقاط توسعة للوجود، التكرار، الإملاء، التسلسل، القابلية للقراءة، والعلاقات بين أجزاء المستند. الإصدار v3.24.0 أضاف vale test لاختبار قواعدك بحالات نجاح وفشل، مع خيار تغطية يكشف القاعدة التي لم تُشغّلها أي حالة.

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

رسم توضيحي؛ النص العربي يشرح إعدادًا مقترحًا ولا يدّعي وجود حزمة عربية رسمية.

3. نفس الفحص في المحرر وpre-commit وCI

يمكن تشغيل Vale من الطرفية، وربطه بمحررات عبر تكاملات موثقة، وتشغيله قبل commit، أو استخدام Vale GitHub Action في CI. الفكرة العملية أن ملف .vale.ini والقواعد يبقيان داخل المستودع، فيقل اختلاف النتائج بين جهاز المطور وبوابة الدمج.

المستودع يوثق تكاملات مع VS Code وCursor وWindsurf وNeovim وJetBrains وObsidian وغيرها. هذه التكاملات ليست كلها جزءًا من ملف Vale التنفيذي؛ بعضها امتدادات منفصلة، لذلك راجع ناشر كل امتداد وصلاحياته قبل التثبيت.

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

رسم توضيحي لمسار تكامل ممكن؛ لا يعني أن CI مضبوط تلقائيًا بعد التثبيت.

4. تشغيل محلي وخصوصية واضحة

README يصف Vale بأنه يعمل دون رفع النص إلى خدمة: لا حساب ولا تحميل للمستندات ولا تدريب على كتابتك. هذا مناسب للتوثيق الداخلي ما دمت تشغّل الملف التنفيذي محليًا وتستخدم قواعد محلية.

لكن توجد حركة شبكة في مراحل محددة: تنزيل Vale، وvale sync لتنزيل الحزم، وتحديثات مدير الحزم، وCI أو المحرر نفسه. كما أن Vale Studio وVale CMS خدمات منفصلة اختيارية؛ لا تحتاجها لتشغيل CLI محليًا. تعامل مع Packages كاعتماد برمجي: ملف الأمن الرسمي يوضح أن الحزمة غير الموثوقة قد تغيّر ما يبلغه Vale، وأن vale sync يجلب ما تسميه الإعدادات.

🪜 مثال عملي خطوة بخطوة

مثال توضيحي لم أنفذه على مشروعك: تريد توحيد مصطلحات توثيق مشروع ثنائي اللغة.

1. ثبّت Vale وتحقق من النسخة عبر vale --version.
2. أنشئ .vale.ini في جذر المشروع، وحدد StylesPath وMinAlertLevel.
3. فعّل حزمة منشورة للملفات الإنجليزية فقط، وأنشئ نمطًا داخليًا لقواعد المصطلحات المشتركة.
4. أضف قاعدة substitution تمنع الاسم القديم للمنتج وتقترح الاسم المعتمد. ابدأ بثلاث قواعد مهمة بدل عشرات القواعد غير المختبرة.
5. شغّل vale sync لتنزيل الحزم، ثم vale docs/ لفحص المجلد.
6. راجع النتائج: اجعل المخالفة التي يجب أن توقف الدمج error، وما يحتاج حكمًا بشريًا warning أو suggestion.
7. أضف حالات vale test للقواعد الداخلية حتى لا تصبح قاعدة صامتة بعد تعديلها.
8. بعد استقرار النتائج محليًا، أضف pre-commit أو Vale GitHub Action. لا تجعل CI بوابة قبل معالجة الإيجابيات الكاذبة.

مثال إعداد مبسط:

StylesPath = styles
MinAlertLevel = suggestion

Packages = Microsoft

[docs/en/*.md]
BasedOnStyles = Vale, Microsoft, House

[docs/ar/*.md]
BasedOnStyles = Vale, HouseArabic

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

⚖️ ماذا تضيف مقارنة بالمراجعة اليدوية؟

هذه مقارنة لسير العمل، وليست ضمانًا لجودة النص أو قياسًا لتوفير الوقت.

⚙️ الإعدادات المهمة

• StylesPath: مكان الحزم والقواعد المحلية. توصي Quickstart بإضافة مجلد الحزم المنزلة إلى .gitignore إذا كنت تعيد مزامنته.
• MinAlertLevel: أقل شدة تظهر في التقرير.
• Packages: الحزم التي ينزلها vale sync. ثبّت مصدرًا موثوقًا وراجع التغييرات قبل التحديث.
• BasedOnStyles: الأنماط المفعلة لقسم ملفات محدد.
• تعطيل قاعدة: تستطيع ضبط اسمها إلى NO داخل القسم عندما لا تناسب سياقك.
• Views وScopes: استخدمها فقط عندما تحتاج استخراج نص من بنية معقدة؛ الإعداد الزائد يصعّب صيانة القواعد.

🚀 التثبيت والبدء

على macOS، الأمر الموصى به في التوثيق هو:

brew install vale

ثم:

vale --version
vale sync
vale README.md

توجد حزم لـWindows وLinux وDocker وملفات تنفيذية جاهزة لمعمارية amd64 وarm64. والبناء عبر Go يحتاج Go 1.25.7 أو أحدث ومترجم C وفق وثائق الإصدار الحالية. لم أنفذ التثبيت أو الأوامر في هذه البطاقة.

🔗 التكاملات والتوافق

• الأنظمة: macOS وWindows وLinux، مع ملفات تنفيذية جاهزة للمعماريات الموثقة.
• المحررات: VS Code/Cursor/Windsurf وNeovim وJetBrains وZed وSublime Text وEmacs وObsidian وغيرها عبر تكاملات مذكورة رسميًا.
• Git: hook موثق لـpre-commit ورسائل commit.
• CI: Vale GitHub Action رسمي، ويمكن تشغيل الأمر في أي CI يسمح بتنزيل الملف التنفيذي والقواعد.
• الصيغ: Markdown وMDX وHTML وAsciiDoc وreStructuredText وXML وDITA وOrg وQuarto وTypst وJupyter وصيغ أخرى موثقة.

💰 التكلفة والتشغيل المحلي

Vale CLI مفتوح المصدر بترخيص MIT ولا يحتاج اشتراكًا أو API مدفوعًا. تعمل الأداة محليًا بعد تثبيتها ومزامنة الحزم. تكاليف GitHub Actions أو جهاز CI أو أي منصة توثيق منفصلة ليست جزءًا من Vale.

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

⚠️ الحدود ومتى لا تستخدمها

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

🔐 الأمان والصلاحيات والخصوصية

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

الفحص المحلي نفسه لا يرفع النص وفق README. مع ذلك، راجع مصدر كل Packages لأن المزامنة تنزلها، وثبّت أحدث إصدار لأن سياسة الأمن لا تدعم الإصدارات الأقدم. تكاملات المحرر وGitHub Actions أدوات إضافية لها وصولها الخاص إلى المستودع؛ أقل صلاحية لازمة هي قراءة الملفات، وقد تحتاج CI إلى كتابة تعليق أو حالة فحص حسب إعداد التكامل.

📚 المصادر وتاريخ التحقق

تحققت في 4 أكتوبر 2026 من المستودع الأصلي، التوثيق الرسمي، Quickstart، التثبيت، الصيغ، Views، سياسة الأمن، وإصدارات GitHub. أحدث إصدار مستقر هو v3.24.0 المنشور في 1 أكتوبر 2026، وكان آخر commit ظاهر وقت الفحص في 3 أكتوبر 2026. لم أثبت Vale أو أشغّل المثال أو أختبر قواعد عربية فعلية.