mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
344
docs/tech-specs/graph-contexts.ar.md
Normal file
344
docs/tech-specs/graph-contexts.ar.md
Normal file
|
|
@ -0,0 +1,344 @@
|
|||
---
|
||||
layout: default
|
||||
title: "مواصفات تقنية لسياق الرسم البياني"
|
||||
parent: "Arabic (Beta)"
|
||||
---
|
||||
|
||||
# مواصفات تقنية لسياق الرسم البياني
|
||||
|
||||
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
تصف هذه المواصفات التغييرات التي تم إجراؤها على المكونات الأساسية للرسم البياني في TrustGraph لمواءمتها مع RDF 1.2 ولتقديم دعم كامل لسمات مجموعة بيانات RDF. هذا تغيير جذري لإصدار 2.x.
|
||||
|
||||
### إصدارات
|
||||
|
||||
- **2.0**: إصدار للمستخدمين الأوائل. تتوفر الميزات الأساسية، وقد لا تكون جاهزة تمامًا للإنتاج.
|
||||
- **2.1 / 2.2**: إصدار جاهز للإنتاج. الاستقرار والشمولية تم التحقق منهما.
|
||||
|
||||
إن توفير مرونة بشأن مستوى النضج هو مقصود - يمكن للمستخدمين الأوائل الوصول إلى إمكانيات جديدة قبل أن تصبح جميع الميزات جاهزة للإنتاج.
|
||||
|
||||
## الأهداف
|
||||
|
||||
الأهداف الرئيسية لهذا العمل هي تمكين البيانات الوصفية حول الحقائق/البيانات:
|
||||
|
||||
- **المعلومات الزمنية**: ربط الحقائق ببيانات وصفية تتعلق بالوقت
|
||||
- متى اعتبرت حقيقة صحيحة
|
||||
- متى أصبحت حقيقة صحيحة
|
||||
- متى اكتشف أن حقيقة غير صحيحة
|
||||
|
||||
- **الأصل/المصادر**: تتبع المصادر التي تدعم حقيقة ما
|
||||
- "هذه الحقيقة مدعومة من المصدر X"
|
||||
- ربط الحقائق بوثائقها الأصلية
|
||||
|
||||
- **الموثوقية/الثقة**: تسجيل التأكيدات حول الحقيقة
|
||||
- "الشخص P أعلن أن هذا صحيح"
|
||||
- "الشخص Q يدعي أن هذا غير صحيح"
|
||||
- تمكين تسجيل النقاط والتحقق من التعارض
|
||||
|
||||
**الفرضية**: Reification (RDF-star / quoted triples) هي الآلية الرئيسية لتحقيق هذه النتائج، حيث تتطلب جميعها إجراء بيانات حول البيانات.
|
||||
|
||||
## الخلفية
|
||||
|
||||
للتعبير عن "تم اكتشاف حقيقة (تعرف أليس بوب) في 2024-01-15" أو "يدعم المصدر X الادعاء (يسبب Y Z)"، تحتاج إلى الرجوع إلى حافة كشيء يمكنك إجراء بيانات حوله. لا تدعم الثلاثيات القياسية هذا.
|
||||
|
||||
### القيود الحالية
|
||||
|
||||
يمكن للفئة `Value` الحالية في `trustgraph-base/trustgraph/schema/core/primitives.py` أن تمثل:
|
||||
- عقد URI (`is_uri=True`)
|
||||
- قيم حرفية (`is_uri=False`)
|
||||
|
||||
يوجد الحقل `type` ولكنه لا يستخدم لتمثيل أنواع بيانات XSD.
|
||||
|
||||
## التصميم التقني
|
||||
|
||||
### ميزات RDF المدعومة
|
||||
|
||||
#### الميزات الأساسية (المرتبطة بأهداف إعادة التعريف)
|
||||
|
||||
ترتبط هذه الميزات بشكل مباشر بالأهداف الزمنية والأصل والموثوقية:
|
||||
|
||||
1. **RDF 1.2 Quoted Triples (RDF-star)**
|
||||
- حواف تشير إلى حواف أخرى
|
||||
- يمكن أن تظهر الثلاثية كـ subject أو object في ثلاثية أخرى
|
||||
- تمكن البيانات حول البيانات (reification)
|
||||
- الآلية الأساسية لتعليق الحقائق الفردية
|
||||
|
||||
2. **RDF Dataset / Named Graphs**
|
||||
- دعم رسوم بيانية مسماة متعددة داخل مجموعة بيانات
|
||||
- يتم تحديد كل رسم بياني بواسطة IRI
|
||||
- الانتقال من ثلاثيات (s, p, o) إلى أرباع (s, p, o, g)
|
||||
- يتضمن الرسم البياني الافتراضي بالإضافة إلى رسم بياني مسمى واحد أو أكثر
|
||||
- يمكن أن يكون IRI الرسم البياني subject في البيانات، على سبيل المثال:
|
||||
```
|
||||
<graph-source-A> <discoveredOn> "2024-01-15"
|
||||
<graph-source-A> <hasVeracity> "high"
|
||||
```
|
||||
- ملاحظة: الرسوم البيانية المسماة ميزة منفصلة عن إعادة التعريف. لها استخدامات تتجاوز تعليق البيانات (التقسيم، التحكم في الوصول، تنظيم مجموعة البيانات) ويجب اعتبارها قدرة متميزة.
|
||||
|
||||
3. **Blank Nodes** (دعم محدود)
|
||||
- عقد مجهولة الهوية بدون URI عالمي
|
||||
- مدعوم من أجل التوافق عند تحميل بيانات RDF خارجية
|
||||
- **حالة محدودة**: لا توجد ضمانات بشأن الهوية المستقرة بعد التحميل
|
||||
- ابحث عنها عبر استعلامات wildcard (تطابق عن طريق الاتصالات، وليس عن طريق المعرف)
|
||||
- ليست ميزة أساسية - لا تعتمد على معالجة دقيقة لعقد فارغة
|
||||
|
||||
#### إصلاحات فرعية (تغيير جذري للإصدار 2.0)
|
||||
|
||||
هذه الميزات ليست مرتبطة بشكل مباشر بأهداف إعادة التعريف ولكنها تحسينات قيمة يجب تضمينها أثناء إجراء تغييرات جذرية:
|
||||
|
||||
4. **Literal Datatypes**
|
||||
- استخدام الحقل `type` بشكل صحيح لأنواع بيانات XSD
|
||||
- أمثلة: xsd:string, xsd:integer, xsd:dateTime، إلخ.
|
||||
- يحل مشكلة حالية: لا يمكن تمثيل التواريخ أو الأعداد الصحيحة بشكل صحيح
|
||||
|
||||
5. **Language Tags**
|
||||
- دعم سمات اللغة على الحرفيات (`@en`, `@fr`, إلخ)
|
||||
- ملاحظة: تحتوي الحرفية على إما علامة لغة أو نوع بيانات، وليس كلاهما (باستثناء `rdf:langString`)
|
||||
- مهم لحالات الاستخدام المتعلقة بالذكاء الاصطناعي/اللغات المتعددة
|
||||
|
||||
### نماذج البيانات
|
||||
|
||||
#### Term (تغيير من Value)
|
||||
|
||||
سيتم إعادة تسمية الفئة `Value` إلى `Term` لتعكس بشكل أفضل المصطلحات الخاصة بـ RDF. تخدم عملية إعادة التسمية هذه غرضين:
|
||||
1. توافق التسمية مع مفاهيم RDF (يمكن أن يكون "Term" IRI أو عقدة فارغة أو حرفية أو ثلاثية مقتبسة - وليس مجرد "value")
|
||||
2. إجبار مراجعة التعليمات البرمجية عند واجهة التغيير الجذري - أي تعليمات برمجية لا تزال تشير إلى `Value` ستظهر بشكل واضح أنها معطلة وتحتاج إلى التحديث
|
||||
|
||||
يمكن أن يمثل Term:
|
||||
|
||||
- **IRI/URI** - عقدة/مورد مسماة
|
||||
- **Blank Node** - عقدة مجهولة الهوية ذات نطاق محلي
|
||||
- **Literal** - قيمة بيانات مع إما:
|
||||
- نوع بيانات (XSD type)، أو
|
||||
- علامة لغة
|
||||
- **Quoted Triple** - ثلاثية تستخدم كـ term (RDF 1.2)
|
||||
|
||||
##### النهج المختار: فئة واحدة مع مُميز نوع
|
||||
|
||||
تحدد متطلبات التسلسل الهيكل - هناك حاجة إلى مُميز نوع في التنسيق السلكي بغض النظر عن التمثيل في Python. الفئة الواحدة ذات نوع التمييز هي الأنسب وتتوافق مع نمط `Value` الحالي.
|
||||
|
||||
توفر رموز النوع أحادية الحرف تسلسلًا مضغوطًا:
|
||||
|
||||
```python
|
||||
from dataclasses import dataclass
|
||||
|
||||
# ثوابت أنواع Term
|
||||
IRI = "i" # عقدة URI
|
||||
BLANK = "b" # عقدة فارغة
|
||||
LITERAL = "l" # قيمة حرفية
|
||||
TRIPLE = "t" # ثلاثية مقتبسة (RDF 1.2)
|
||||
|
||||
@dataclass
|
||||
class Term:
|
||||
type: str = "" # واحد من: IRI, BLANK, LITERAL, TRIPLE
|
||||
|
||||
# لـ مصطلحات IRI (type == IRI)
|
||||
iri: str = ""
|
||||
|
||||
# لـ عقد فارغة (type == BLANK)
|
||||
id: str = ""
|
||||
|
||||
# لـ الحرفيات (type == LITERAL)
|
||||
value: str = ""
|
||||
datatype: str = "" # URI لنوع بيانات XSD (مستبعدة مع اللغة)
|
||||
language: str = "" # علامة لغة (مستبعدة مع نوع البيانات)
|
||||
|
||||
# لـ ثلاثيات مقتبسة (type == TRIPLE)
|
||||
triple: "Triple | None" = None
|
||||
```
|
||||
|
||||
أمثلة على الاستخدام:
|
||||
|
||||
```python
|
||||
# مصطلح IRI
|
||||
node = Term(type=IRI, iri="http://example.org/Alice")
|
||||
|
||||
# حرفية مع نوع بيانات
|
||||
age = Term(type=LITERAL, value="42", datatype="xsd:integer")
|
||||
|
||||
# حرفية مع علامة لغة
|
||||
label = Term(type=LITERAL, value="Hello", language="en")
|
||||
|
||||
# عقدة فارغة
|
||||
anon = Term(type=BLANK, id="_:b1")
|
||||
|
||||
# ثلاثية مقتبسة (بيانات حول بيانات)
|
||||
inner = Triple(
|
||||
s=Term(type=IRI, iri="http://example.org/Alice"),
|
||||
p=Term(type=IRI, iri="http://example.org/knows"),
|
||||
o=Term(type=IRI, iri="http://example.org/Bob"),
|
||||
)
|
||||
reified = Term(type=TRIPLE, triple=inner)
|
||||
```
|
||||
|
||||
#### البدائل التي تم أخذها في الاعتبار
|
||||
|
||||
**الخيار B: اتحاد الفئات المتخصصة** (`Term = IRI | BlankNode | Literal | QuotedTriple`)
|
||||
- مرفوض: لا يزال التسلسل يحتاج إلى مُميز نوع، مما يضيف تعقيدًا
|
||||
|
||||
**الخيار C: فئة أساسية مع فئات فرعية**
|
||||
- مرفوض: نفس مشكلة التسلسل، بالإضافة إلى تعقيدات وراثة dataclass
|
||||
|
||||
#### Triple / Quad
|
||||
|
||||
تكتسب الفئة `Triple` حقل اختياري للرسم البياني ليصبح أربعة:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class Triple:
|
||||
s: Term | None = None # Subject
|
||||
p: Term | None = None # Predicate
|
||||
o: Term | None = None # Object
|
||||
g: str | None = None # اسم الرسم البياني (IRI)، None = الرسم البياني الافتراضي
|
||||
```
|
||||
|
||||
قرارات التصميم:
|
||||
- **اسم الحقل**: `g` لضمان الاتساق مع `s`, `p`, `o`
|
||||
- **اختياري**: `None` يعني الرسم البياني الافتراضي (غير المسمى)
|
||||
- **النوع**: سلسلة عادية (IRI) بدلاً من Term
|
||||
- أسماء الرسم البياني هي دائمًا IRIs
|
||||
- تم استبعاد العقد الفارغة كأسماء للرسوم البيانية (مربكة جدًا)
|
||||
- لا حاجة إلى آليات Term الكاملة
|
||||
|
||||
لاحظ أن اسم الفئة يظل `Triple` حتى لو كانت ثلاثية الآن. هذا يتجنب التغييرات الجذرية و "triple" هي لا تزال المصطلحات الشائعة. السياق البياني هو بيانات وصفية حول مكان وجود الثلاثية.
|
||||
|
||||
### أنماط استعلام مرشحة
|
||||
|
||||
يقبل محرك الاستعلام الحالي مجموعات من مصطلحات S, P, O. مع ثلاثيات مقتبسة، تصبح الثلاثية نفسها مصطلحًا صالحًا في هذه المواضع. فيما يلي أنماط استعلام مرشحة تدعم الأهداف الأصلية.
|
||||
|
||||
#### معاني معلمات الرسم البياني
|
||||
|
||||
باتباع اصطلاحات SPARQL للتوافق مع الإصدارات السابقة:
|
||||
|
||||
- **تم حذف `g` / None**: استعلام للرسم البياني الافتراضي فقط
|
||||
- **`g` = IRI محدد**: استعلام لهذا الرسم البياني المسمى فقط
|
||||
- **`g` = حرف جاموسي / `*`**: استعلام عبر جميع الرسوم البيانية (مكافئ لـ SPARQL
|
||||
`GRAPH ?g { ... }`)
|
||||
|
||||
هذا يحافظ على بساطة الاستعلامات البسيطة ويجعل استعلامات الرسم البياني المسماة اختيارية.
|
||||
|
||||
تدعم الاستعلامات عبر الرسوم البيانية (g=حرف جاموسي). يحتوي مخطط Cassandra على جداول مخصصة (SPOG, POSG, OSPG) حيث g هو عمود تجميع بدلاً من مفتاح التقسيم، مما يتيح استعلامات فعالة عبر جميع الرسوم البيانية.
|
||||
|
||||
#### استعلامات زمنية
|
||||
|
||||
**ابحث عن جميع الحقائق التي تم اكتشافها بعد تاريخ معين:**
|
||||
```
|
||||
S: ? # أي ثلاثية مقتبسة
|
||||
P: <discoveredOn>
|
||||
O: > "2024-01-15"^^xsd:date # مقارنة التاريخ
|
||||
```
|
||||
|
||||
**ابحث عن الوقت الذي اعتبرت فيه حقيقة صحيحة:**
|
||||
```
|
||||
S: << <Alice> <knows> <Bob> >> # ثلاثية مقتبسة كـ subject
|
||||
P: <believedTrueFrom>
|
||||
O: ? # يعيد التاريخ
|
||||
```
|
||||
|
||||
**ابحث عن الحقائق التي تبين أنها خاطئة:**
|
||||
```
|
||||
S: ? # أي ثلاثية مقتبسة
|
||||
P: <discoveredFalseOn>
|
||||
O: ? # له أي قيمة (موجود)
|
||||
```
|
||||
|
||||
#### استعلامات الأصل
|
||||
|
||||
**ابحث عن جميع الحقائق التي يدعمها مصدر معين:**
|
||||
```
|
||||
S: ? # أي ثلاثية مقتبسة
|
||||
P: <supportedBy>
|
||||
O: <source:document-123>
|
||||
```
|
||||
|
||||
**ابحث عن المصادر التي تدعم حقيقة معينة:**
|
||||
```
|
||||
S: << <DrugA> <treats> <DiseaseB> >> # ثلاثية مقتبسة كـ subject
|
||||
P: <supportedBy>
|
||||
O: ? # يعيد IRIs المصدر
|
||||
```
|
||||
|
||||
#### استعلامات الموثوقية
|
||||
|
||||
**ابحث عن التأكيدات التي أعلن شخص ما أنها صحيحة:**
|
||||
```
|
||||
S: ? # أي ثلاثية مقتبسة
|
||||
P: <assertedTrueBy>
|
||||
O: <person:Alice>
|
||||
```
|
||||
|
||||
**ابحث عن التأكيدات المتعارضة (نفس الحقيقة، موثوقية مختلفة):**
|
||||
```
|
||||
# الاستعلام الأول: الحقائق التي أعلنت صحتها
|
||||
S: ?
|
||||
P: <assertedTrueBy>
|
||||
O: ?
|
||||
|
||||
# الاستعلام الثاني: الحقائق التي أعلنت أنها خاطئة
|
||||
S: ?
|
||||
P: <assertedFalseBy>
|
||||
O: ?
|
||||
|
||||
# منطق التطبيق: ابحث عن تقاطع الـ subjects
|
||||
```
|
||||
|
||||
**ابحث عن الحقائق التي تقل فيها درجة الثقة عن حد معين:**
|
||||
```
|
||||
S: ?
|
||||
P: <trustScore>
|
||||
O: [threshold]
|
||||
```
|
||||
|
||||
### حد تخزين المتجهات
|
||||
|
||||
تستخدم مخازن المتجهات دائمًا IRIs فقط:
|
||||
- لا توجد حواف (ثلاثيات مقتبسة)
|
||||
- لا توجد قيم حرفية
|
||||
- لا توجد عقد فارغة
|
||||
|
||||
هذا يبقي تخزين المتجهات بسيطًا - يتعامل مع التشابه الدلالي للكائنات المسماة. يتعامل هيكل الرسم البياني مع العلاقات وإعادة التعريف والبيانات الوصفية. لا تعقد الثلاثيات المقتبسة والرسوم البيانية المسماة عمليات المتجهات.
|
||||
|
||||
## اعتبارات الأمان
|
||||
|
||||
الرسوم البيانية المسماة ليست ميزة أمان. تظل المستخدمون والمجموعات هي حدود الأمان. الرسوم البيانية المسماة مخصصة لتنظيم البيانات فقط وليست لإعادة التعريف.
|
||||
|
||||
## اعتبارات الأداء
|
||||
|
||||
- يمكن أن تضيف الثلاثيات المقتبسة عمق التداخل - قد تؤثر على أداء الاستعلام
|
||||
- هناك حاجة إلى استراتيجيات فهرسة الرسم البياني المسماة للاستعلامات الفعالة الموجهة للرسم البياني
|
||||
- يجب أن يستوعب تصميم مخطط Cassandra تخزين الأربعة بكفاءة
|
||||
|
||||
### واجهة مستخدم مخزن المتجهات
|
||||
|
||||
دائمًا ما تشير مخازن المتجهات إلى IRIs فقط:
|
||||
- لا توجد حواف (ثلاثيات مقتبسة)
|
||||
- لا توجد قيم حرفية
|
||||
- لا توجد عقد فارغة
|
||||
|
||||
هذا يبقي مخزن المتجهات بسيطًا - يتعامل مع التشابه الدلالي للكائنات المسماة. يتعامل هيكل الرسم البياني مع العلاقات وإعادة التعريف والبيانات الوصفية. لا تعقد الثلاثيات المقتبسة والرسوم البيانية المسماة عمليات المتجهات.
|
||||
|
||||
## استراتيجية الاختبار
|
||||
|
||||
استخدم استراتيجية الاختبار الحالية. نظرًا لأن هذا تغيير جذري، ركز بشكل كبير على مجموعة الاختبار الشاملة للتحقق من أن الهياكل الجديدة تعمل بشكل صحيح عبر جميع المكونات.
|
||||
|
||||
## خطة الترحيل
|
||||
|
||||
- 2.0 هو إصدار جذري؛ لا توجد توافقية مع الإصدارات السابقة مطلوبة
|
||||
- قد تتطلب البيانات الحالية ترحيلًا إلى مخطط جديد (سيتم تحديده بناءً على التصميم النهائي)
|
||||
- ضع في اعتبارك أدوات الترحيل لتحويل الثلاثيات الموجودة
|
||||
|
||||
## أسئلة مفتوحة
|
||||
|
||||
- **العقد الفارغة**: تم تأكيد الدعم المحدود. قد تحتاج إلى تحديد استراتيجية skolemization (إنشاء IRIs عند التحميل أو الحفاظ على معرفات العقد الفارغة).
|
||||
- **بناء جملة الاستعلام**: ما هي البنية النحوية الملموسة لتحديد الثلاثيات المقتبسة في الاستعلامات؟ تحتاج إلى تعريف واجهة برمجة تطبيقات الاستعلام.
|
||||
- ~~**مفردات السمة**~~: تم الحل. أي عناصر من المفردات RDF الصالحة مسموح بها، بما في ذلك العناصر المخصصة التي يحددها المستخدم. افتراضات قليلة جدًا عن صلاحية RDF.
|
||||
- ~~**تأثير مستودع المتجهات**~~: تم الحل. تشير مستودعات المتجهات دائمًا إلى IRIs فقط - لا توجد حواف أو قيم حرفية أو عقد فارغة. لا تؤثر الثلاثيات المقتبسة وإعادة التعريف على مستودع المتجهات.
|
||||
- ~~**دلالات الرسم البياني المسماة**~~: تم الحل. الاستعلامات افتراضيًا هي الرسم البياني الافتراضي (تتوافق مع سلوك SPARQL، متوافقة مع الإصدارات السابقة). مطلوب معلمة رسم بياني صريحة للاستعلام عن الرسوم البيانية المسماة أو جميع الرسوم البيانية.
|
||||
|
||||
## المراجع
|
||||
|
||||
- [RDF 1.2 Concepts](https://www.w3.org/TR/rdf12-concepts/)
|
||||
- [RDF-star and SPARQL-star](https://w3c.github.io/rdf-star/)
|
||||
- [RDF Dataset](https://www.w3.org/TR/rdf11-concepts/#section-dataset)
|
||||
Loading…
Add table
Add a link
Reference in a new issue