المساهمة

تحديث البيانات

تُبنى المحاكم والسجون والـjustitiehuizen / maisons de justice وحدود الكانتونات من المصادر الرسمية كل أسبوع (كيف): لا تعدّلها يدويًا. أصلح المحلّل في scripts/parse، أو، إن كان المصدر نفسه خاطئًا، أبلغ المحكمة. يُراجَع الـpull request الأسبوعي كأي pull request آخر: قارن الفروق بالمصادر قبل الدمج.

لمجموعات البيانات المحفوظة يدويًا (المناطق القضائية، والدوائر القضائية، وأسعار الفائدة):

1. عدّل ملف JSON في data/. احتفظ بالمعرّفات الموجودة: المشاريع تخزّنها.
2. حدّث lastReviewed لمجموعة البيانات في datapackage.json إذا راجعتها مقابل مصادرها.
3. pnpm check: يعيد توليد أنواع المعرّفات والمخططات، ويفحص الأنواع، ويجري lint وفحص التنسيق، والبناء، والاختبارات مع التغطية، وlint الحزمة. ويفشل حين لا تكون الملفات المولَّدة مضافة في commit.
4. أضف سطرًا إلى CHANGELOG.md تحت Unreleased، وأنشئ commit (بما في ذلك schema/ وsrc/ids.generated.ts وids.lock.json). مخرجات البناء (dist/) لا تُضاف إلى المستودع: تُبنى لكل إصدار وتُنشر على npm.

المعرّف الذي نُشر يبقى: يسردها ids.lock.json كلها وتفشل الاختبارات حين يغيب أحدها عن البيانات. إذا أعاد مصدرٌ تسمية سجل، فاربط الاسم الجديد بالمعرّف الموجود في المحلّل؛ وإذا انتهى السجل، فاحتفظ به مع validTo. انظر المعرّفات.

الكانتونات والبلديات

data/cantons.json وdata/municipalities.json ملفان مولَّدان؛ لا تعدّلهما يدويًا. شغّل pnpm build:cantons (يحتاج إلى اتصال بالشبكة وإلى unzip). وهو يقرأ:

• ملحق Gerechtelijk Wetboek / Code judiciaire (القانون القضائي)، «Gebiedsomschrijving en zetel van hoven en rechtbanken» (ELI، numac 1967101058)، بالهولندية والفرنسية؛
• ملف Statbel للسكان حسب البلدية، للبلديات الحالية ورموز REFNIS.

يحلّل النصين الهولندي والفرنسي كلًا على حدة ويرفض كتابة أي شيء ما لم يتطابقا وتُغطَّ كل بلدية مرة واحدة بالضبط (أو تُقسَّم على عدة كانتونات). الأسماء الأجنبية التي يستخدمها الملحق ولا تستخدمها Statbel ‏(Gembloers، Saint-Nicolas، …)، والأخطاء المطبعية في الملحق، وعبارات الحدود التي لا يستطيع التمييز بينها، مسرودة في أعلى السكربت.

أعد تشغيله بعد أن يغيّر قانونٌ الملحق أو تندمج بلديات. تتبع معرّفات الكانتونات اللغة المحلية (الهولندية في Vlaanderen وBrussel، والفرنسية في Wallonie، والألمانية حول Eupen)؛ والـvredegerecht / justice de paix للكانتون x معرّفه justice-of-the-peace-x ويرتبط به عبر حقله canton.

مجموعات البيانات المستخرَجة

pnpm fetch:sources            # كل مصدر إلى .sources/ (نحو 20 دقيقة، بتهذيب)
pnpm fetch:sources courts     # أو مصدر واحد
pnpm build:data               # إعادة بناء المحاكم والسجون والـjustitiehuizen والرموز البريدية والأقاليم والمقاطعات من .sources/

تأتي حدود الكانتونات من ملف GeoPackage الخاص بـNGI (المصدر ngi)، ويُقرأ بـSQLite المدمج في Node؛ وحين يعيد NGI تسمية كانتون، اربط رمزه بالمعرّف في CANTON_ALIASES في scripts/parse/boundaries.ts.

أو استخرج آخر اللقطات بدلًا من الجلب: git worktree add .sources origin/sources.

المصدر walk في scripts/sources/catalog.ts؛ والمحلّل يقرأ لقطاته في scripts/parse. حين يغيّر موقعٌ ترميزه (markup)، تُظهر اختبارات المحلّل في test/parse (على نسخ مقتطعة من صفحات حقيقية في test/fixtures/sources) ما الذي انكسر.

أسعار فائدة جديدة

• التجاري: تنشر FOD Financiën السعر لكل نصف سنة. أضف فترة بـfrom وto وrate، وتاريخ النشر في Staatsblad في note.
• القانوني: يُنشر لكل سنة تقويمية. أضف فترة للسنة.

إضافة مجموعة بيانات

تحظى كل مجموعة بيانات بالمعاملة نفسها، حتى يتمكن المستخدمون من الاعتماد عليها:

1. البيانات: data/<name>.json، مصفوفة سجلات. كل قيمة من مصدر رسمي.
2. المعرّفات: اتبع قواعد المعرّفات: رمز رسمي حين يوجد، وإلا فـkebab-case بأحرف صغيرة من الاسم باللغة المحلية (scripts/id.ts).
3. روابط لا نسخ: أشر إلى الدوائر القضائية والكانتونات والبلديات بالمعرّف، وأعد استخدام الأنواع المشتركة (Translated، Address، Contact، SourceRef).
4. المصادر: sources: [{ url, retrieved }] على كل سجل، ومدخل في datapackage.json بمصادر مجموعة البيانات وترخيصها وlastReviewed وreviewEveryMonths.
5. الأنواع والدوال المساعدة: src/<name>.ts، مُصدَّر من src/index.ts، مع entry point في tsup.config.ts وفي exports في package.json.
6. المخطط: أضف نوع الملف إلى scripts/schema-types.ts وscripts/build-schemas.ts.
7. المصدر والمحلّل: walk في scripts/sources/catalog.ts يجلب الصفحات الرسمية، ومحلّل في scripts/parse يبني الملف من اللقطات، مع fixtures واختبارات. لا يقرأ إلا ما يستطيع قراءته بيقين ويبلّغ عن الباقي.
8. الاختبارات: معرّفات فريدة، وإشارات تُحَل، والعدد الذي يعطيه المصدر الرسمي.
9. التوثيق: صفحة تحت docs/data/ تشرح فائدتها، ومصدرها وتحديثاتها، مع جدول للحقول.

الفحوص

الأمر	ما يفعله
pnpm check	كل ما يشغّله CI: generate، typecheck، lint، build، test:coverage، test:package، lint:package، وفحص أن الملفات المولَّدة مضافة في commit
pnpm test	اختبارات الوحدات والسلامة والمخططات والأنواع على الكود المصدري (لا حاجة إلى بناء)
pnpm test:package	اختبارات smoke للحزمة المبنية بـimport وrequire(): شغّل pnpm build أولًا
pnpm test:coverage	الشيء نفسه، ويفشل إذا قلّت تغطية src/ عن 100 %
pnpm lint / pnpm format	ESLint وPrettier: فحص / إصلاح
pnpm generate	يعيد توليد src/ids.generated.ts (أنواع المعرّفات) وschema/ من البيانات والأنواع، ويضيف المعرّفات الجديدة إلى ids.lock.json
pnpm lint:package	publint وarethetypeswrong على الحزمة المحزومة
pnpm test:freshness	فحوص قائمة على التاريخ: أسعار ناقصة، مراجعات متأخرة. ليست جزءًا من check؛ وFRESHNESS_ONLINE=1 يفحص أيضًا روابط المصادر
pnpm fetch:sources	يجلب المصادر الرسمية إلى .sources/
pnpm build:data	يعيد بناء المحاكم والسجون والـjustitiehuizen / maisons de justice والرموز البريدية والأقاليم والمقاطعات وحدود الكانتونات من .sources/
pnpm build:csv	يكتب البيانات بوصفها جداول CSV في csv/

الإصدار

1. انقل مدخلات Unreleased في CHANGELOG.md تحت الإصدار الجديد.
2. ارفع version في package.json وأنشئ commit.
3. ضع tag وادفع: git tag v0.3.0 && git push && git push --tags.

يشغّل workflow الإصدار pnpm check، وينشر الـtag على npm مع provenance، وينشئ إصدارًا على GitHub مرفقة به البيانات والمخططات وجداول CSV. يجب أن يطابق الـtag قيمة version.

هذا الموقع

يعيش الموقع في docs/ ويُبنى بـVitePress. تستورد الجداول التفاعلية src/ وdata/ الخاصين بالحزمة نفسها، فتعرض دائمًا البيانات الموجودة في المستودع.

pnpm docs:dev      # خادم محلي مع hot reload
pnpm docs:build    # موقع ثابت في docs/.vitepress/dist
pnpm docs:preview  # تقديم الموقع المبني

كل دفع (push) إلى main ينشره على GitHub Pages. ويبنيه CI في كل pull request، فتُكتشف الصفحة المعطوبة قبل الدمج.

الترجمات

الصفحات الإنجليزية في docs/ هي المصدر المرجعي. لكل لغة أخرى الشجرة نفسها تحت مجلدها الخاص: الهولندية (docs/nl/) والفرنسية (docs/fr/)، والألمانية والإسبانية والإيطالية والبرتغالية والبولندية والتركية والعربية والأوكرانية والصينية واليابانية (docs/de/ وdocs/es/ وهكذا). وهي ترجمات للصفحة الإنجليزية وتُحدَّث بعد تغييرها. حين تغيّر صفحة إنجليزية، غيّر الصفحة نفسها في docs/nl/ وdocs/fr/ أيضًا، أو اذكر في الـpull request أن الترجمات متأخرة؛ ويجوز أن تتأخر اللغات الأخرى بإصدار واحد. كلمات القالب (theme) والمكونات التفاعلية في تلك اللغات الأخرى موجودة في docs/.vitepress/locales/.

يبقى الكود والمعرّفات وأسماء الحقول والأسماء الرسمية كما هي في كل لغة، ويحتفظ كل عنوان بالمرساة الإنجليزية (## Heading {#english-anchor}) حتى تستمر الروابط المتبادلة ومبدّل اللغة في العمل. وتحتفظ المؤسسة البلجيكية أو المصطلح القانوني باسمه الرسمي الهولندي أو الفرنسي (أو الألماني، حيث تنشر بلجيكا اسمًا ألمانيًا) بدلًا من ترجمة مستحدثة: الصفحة الصينية تقول vredegerecht / justice de paix، لا كلمة مختلقة لها. ويُحفظ سجل التغييرات بالإنجليزية فقط.