البنية التقنية

better-auth-tarjim تحوّل أخطاء Better Auth إلى رسائل عربية لواجهات الإشعارات. وتُبقي Better Auth مصدر الحقيقة، وتضمن أن لكل رمز في أي إصدار رسالة عربية، وتبقى صغيرة وبلا اعتماديات وقت التشغيل.

كيف تعمل

للحزمة جانبان:

• التوليد: أثناء التطوير، تكتشف رموز الأخطاء من حزم Better Auth المثبّتة.
• وقت التشغيل: المكتبة المنشورة تربط تلك الرموز برسائل عربية.

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

الترجمة

يقبل المحوِّل أشكال الأخطاء الشائعة: أخطاء عميل Better Auth، وأخطاء الخادم التي تحمل جسم استجابة، وفشل الطلب أو الشبكة، والنصوص المجرّدة التي تحمل رمز خطأ.

ويحلّ الرسالة بهذا الترتيب:

1. تخصيصات المستهلك، بما فيها رموز الإضافات المخصّصة
2. القاموس العربي المضمّن
3. تجاوز حدّ الطلبات (429)
4. فشل الشبكة
5. أخطاء الخادم (5xx)
6. رسالة الخادم الأصلية، عند تفعيل ذلك فقط
7. رسالة بديلة من المستهلك أو رسالة عربية بديلة عامة

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

التكامل مع الإشعارات

تكامل Sonner اختياري. تقدّم الحزمة مساعدات لعرض الرسالة المترجمة كإشعار خطأ، وللتعامل مع الأخطاء العائدة ووعدٍ مرفوض معاً، ولضبط الإعدادات الافتراضية مرة واحدة.

البقاء على اطّلاع

تفرض الفحوص الآلية ما يأتي:

• تطابق قائمة الرموز مع إصدار Better Auth المثبّت.
• وجود ترجمة عربية لكل رمز خطأ.
• نجاح بناء الحزمة، والبقاء ضمن ميزانية الحجم، والعمل بصيغتَي ESM وCommonJS.
• منع نشر بيانات مُولَّدة قديمة أو اختبارات فاشلة.

ويفتح مسار عمل مجدول يرقّي Better Auth، ويعيد توليد قائمة الرموز، ويفتح طلب دمج يذكر ما إذا كانت الترجمات ناقصة.

الخيارات التصميمية

• الرموز لا النص الإنجليزي: الرموز ثابتة، أما الرسائل فيمكن أن تتغيّر.
• قائمة رموز مُولَّدة: تمنع الانحراف اليدوي مع تطوّر Better Auth.
• قاموس عربي محدَّد النوع: يحوّل الترجمات الناقصة إلى خطأ في وقت التجميع.
• صفر اعتماديات وقت التشغيل: يُبقي حجم التثبيت وسطح سلسلة التوريد صغيرين.
• Sonner اختياري: يمكن للمستهلكين استخدام مكتبة إشعارات أخرى أو الاكتفاء بالترجمة.
• مدخل ترجمة منفصل: يتجنّب مستخدمو غير Sonner اعتمادية غير لازمة.

إضافة لغة أخرى

الحزمة محايدة لغوياً بالتصميم، وعربية أولاً عند الإصدار. وإضافة لغة جديدة لا تغيّر الواجهة العامة:

1. أضف قاموساً بجانب src/ar.ts، مفتاحاته هي نفسه نوع ErrorCode.
2. مرّر خيار locale عبر TranslateOptions، واجعل src/ar.ts هو الافتراضي.
3. أبقِ better-auth-tarjim/translate خالياً من أي اعتمادية على المتصفّح، فيبقى مدخل الترجمة قابلاً للاستخدام في الخادم.

على المستهلك الذي يحتاج لغة واحدة فقط أن لا يدفع ثمن اللغات الأخرى. يُفضَّل مدخل منفصل أو استيراد مقيَّد بالّغة على حزمة واحدة تضم كل القواميس.

القيود

تدعم الحزمة العربية حالياً فقط. وتحتفظ الرموز المكرّرة داخل Better Auth بأول تعريف وتُنتج تحذيراً. وكشف الشبكة استدلالي، بينما الحالة الرقمية أو رمز الخطأ المعروف لهما الأسبقية دائماً.