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.
2026-04-26 00:46:22 +02:00 · 2026-04-14 07:07:58 -04:00 · 2026-04-14 07:07:58 -04:00 · f95fd4f052
commit f95fd4f052
parent 19f73e4cdc
560 changed files with 236300 additions and 99 deletions
--- a/docs/tech-specs/graph-contexts.he.md
+++ b/docs/tech-specs/graph-contexts.he.md
@ -0,0 +1,324 @@
+---
+layout: default
+title: "מפרט טכני של הקשרים בגרף"
+parent: "Hebrew (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 / משולשות מצוטטות) הוא המנגנון העיקרי
+לשם השגת תוצאות אלה, מכיוון שכולן דורשות הצהרות על הצהרות.
+
+## רקע
+
+כדי להביע "העובדה (אליס יודעת את בוב) התגלתה ב-2024-01-15" או
+"מקור X תומך בטענה (Y גורם ל-Z)", אתה צריך להתייחס לקצה
+כאל דבר שאפשר להצהיר עליו. משולשות סטנדרטיים אינם תומכים בכך.
+
+### מגבלות נוכחיות
+
+המחלקת `Value` הנוכחית ב-`trustgraph-base/trustgraph/schema/core/primitives.py`
+יכולה לייצג:
+- צומתי URI (`is_uri=True`)
+- ערכים מילוליים (`is_uri=False`)
+
+השדה `type` קיים אך אינו משמש לייצוג טיפוסי נתונים של XSD.
+
+## עיצוב טכני
+
+### תכונות RDF לתמיכה
+
+#### תכונות ליבה (קשור למטרות ה-Reification)
+
+תכונות אלו קשורות ישירות למטרות הזמן, המקור והנכונות:
+
+1. **משולשות מצוטטות של RDF 1.2 (RDF-star)**
+   - קצוות המצביעים על קצוות אחרים
+   - משולש יכול להופיע כנושא או כאובייקט של משולש אחר
+   - מאפשר הצהרות על הצהרות (reification)
+   - מנגנון ליבה לסימון עובדות בודדות
+
+2. **סט נתונים RDF / גרפים בעלי שם**
+   - תמיכה במספר גרפים בעלי שם בתוך סט נתונים
+   - כל גרף מזוהה על ידי IRI
+   - מעבר משלשות (s, p, o) לארבעיות (s, p, o, g)
+   - כולל גרף ברירת מחדל ואחד או יותר גרפים בעלי שם
+   - ניתן להשתמש ב-IRI של הגרף כנושא בהצהרות, לדוגמה:
+     ```
+     <graph-source-A> <discoveredOn> "2024-01-15"
+     <graph-source-A> <hasVeracity> "high"
+     ```
+   - הערה: גרפים בעלי שם הם תכונה נפרדת מ-reification. יש להם
+     שימושים מעבר לסימון הצהרות (מחיצה, בקרת גישה, ארגון סט נתונים)
+     ועליהם להתייחס אליהם כלי יכולת נפרדת.
+
+3. **צמתים ריקים** (תמיכה מוגבלת)
+   - צמתים אנונימיים ללא URI גלובלי
+   - נתמך לצורך תאימות בעת טעינת נתוני RDF חיצוניים
+   - **סטטוס מוגבל**: אין ערובות לזהות יציבה לאחר הטעינה
+   - ניתן למצוא אותם באמצעות שאילתות wildcard (התאמה לפי חיבורים, לא לפי מזהה)
+   - לא תכונה ראשית - אין להסתמך על טיפול מדויק בצמתים ריקים
+
+#### תיקונים הזדמנותיים (שינוי שבירה 2.0)
+
+תכונות אלה אינן קשורות ישירות למטרות ה-reification, אך הן שיפורים
+חשובים שצריך לכלול בעת ביצוע שינויים שבירים:
+
+4. **טיפוסי מילוליים**
+   - שימוש נכון בשדה `type` עבור טיפוסי נתונים של XSD
+   - דוגמאות: xsd:string, xsd:integer, xsd:dateTime וכו'
+   - פותר מגבלה קיימת: לא ניתן לייצג תאריכים או מספרים שלמים כראוי
+
+5. **תגיות שפה**
+   - תמיכה בתכונות שפה על מילוליים (en, fr וכו')
+   - הערה: למילול יש תגית שפה או טיפוס נתונים, לא את שניהם
+     (מלבד rdf:langString)
+   - חשוב עבור מקרי שימוש בבינה מלאכותית/רב-לשוניים
+
+### מודלים של נתונים
+
+#### Term (שינוי שם מ-Value)
+
+המחלקת `Value` תשנה את שמה ל-`Term` כדי לשקף טוב יותר את המונחים של RDF.
+שינוי שם זה משרת שני מטרות:
+1. מיישר את שמות עם מושגים של RDF (ה- "Term" יכול להיות IRI, מילול, צומת ריק או משולש מצוטט - ולא רק "ערך")
+2. גורם לסקירת קוד בממשק לשינוי השבירה - כל קוד שעדיין מתייחס ל-`Value`
+   נראה שבור באופן גלוי ויש לעדכן אותו
+
+Term יכול לייצג:
+
+- **IRI/URI** - צומת/משאב בעל שם
+- **צומת ריק** - צומת אנונימי עם תחום מקומי
+- **מילול** - ערך נתונים עם:
+  - טיפוס נתונים (טיפוס XSD), או
+  - תגית שפה
+- **משולש מצוטט** - משולש המשמש כ-term (RDF 1.2)
+
+##### גישה שנבחרה: מחלקה אחת עם מפריד טיפוס
+
+דרישות הסתרה חשובות למבנה - מפריד טיפוס נחוץ
+בפורמט ה-wire ללא קשר לייצוג ה-Python. מחלקה אחת עם שדה טיפוס היא
+ההתאמה הטבעית ותואמת לדפוס ה-`Value` הנוכחי.
+
+קודים חד-תווים של טיפוסים מספקים הסתרה קומפקטית:
+
+```python
+from dataclasses import dataclass
+
+# קבועים של סוג Term
+IRI = "i"      # צומת IRI/URI
+BLANK = "b"    # צומת ריק
+LITERAL = "l"  # ערך מילולי
+TRIPLE = "t"   # משולש מצוטט (RDF-star)
+
+@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)
+    language: str = ""   # תגית שפה (בלעדי ל-datatype)
+
+    # עבור משולשות מצוטטות (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` רוכשת שדה גרף אופציונלי כדי להפוך לארבעייה:
+
+```python
+@dataclass
+class Triple:
+    s: Term | None = None    # נושא
+    p: Term | None = None    # תכונה
+    o: Term | None = None    # אובייקט
+    g: str | None = None     # שם גרף (IRI), None = גרף ברירת מחדל
+```
+
+החלטות עיצוב:
+- **שם שדה**: `g` לעקביות עם `s`, `p`, `o`
+- **אופציונלי**: `None` פירושו הגרף כברירת מחדל (חסר שם)
+- **סוג**: מחרוזת פשוטה (IRI) ולא Term
+  - שמות גרפים הם תמיד IRIs
+  - צמתים ריקים כשמות גרפים נשללו (מבלבלים)
+  - אין צורך במכניקת ה-Term המלאה
+
+שים לב: שם המחלקה נשאר `Triple` גם אם היא טכנית ארבעייה.
+זה מונע שינויים ו"משולש" הוא עדיין המונח הנפוץ. הקונטקסט של הגרף
+הוא מטא-נתונים לגבי היכן שוכנת השלישייה.
+
+### תבניות שאילתות מועמדות
+
+מנוע השאילתות הנוכחי מקבל שילובים של מונחי S, P, O. עם משולשות מצוטטות,
+משולש בעצמו הופך ל-term חוקי בעמדות אלה. להלן תבניות שאילתות מועמדות
+התומכות במטרות המקוריות.
+
+#### סמנטיקת פרמטר גרף
+
+בהתאם לקונבנציות SPARQL עבור תאימות לאחור:
+
+- **`g` מושמט / None**: שאילתא רק את הגרף כברירת מחדל
+- **`g` = IRI ספציפי**: שאילתא רק את הגרף בעל השם הזה
+- **`g` = wildcard / `*`**: שאילתא על פני כל הגרפים (שווה ערך ל-SPARQL
+  `GRAPH ?g { ... }`)
+
+זה שומר על שאילתות פשוטות כפשוטות ומאפשר שאילתות על גרפים בעלי
+שמות כבחירה.
+
+שאילתות חוצות גרפים (g=wildcard) נתמכות במלואן. סכימת Cassandra
+כוללת טבלאות ייעודיות (SPOG, POSG, OSPG) כאשר g הוא עמודת clustering
+ולא מפתח מחיצה, המאפשר שאילתות יעילות על פני כל הגרפים.
+
+#### שאילתות זמניות
+
+**מצא את כל העובדות שהתגלו בתאריך 2024-01-15:**
+```
+SELECT * FROM triples WHERE ?s p1 ?o1 .
+```
+
+#### שיקולי ביצועים
+
+- משולשות מצוטטות מוסיפות עומק קינון - עשויות להשפיע על ביצועי השאילתות
+- אסטרטגיות אינדוקס לגרפים בעלי שם נחוצות עבור שאילתות יעילות מבוססות גרפים
+- עיצוב סכימת Cassandra יצטרך להתאים אחסון ארבעיות ביעילות
+
+### גבולת מאגר וקטורי
+
+מאגרי וקטורים תמיד מתייחסים ל-IRIs בלבד:
+- לעולם לא קצוות (משולשות מצוטטות)
+- לעולם לא ערכים מילוליים
+- לעולם לא צמתים ריקים
+
+זה שומר על מאגר הווקטורים פשוט - הוא מטפל בדמיון סמנטי של ישויות בעלות שם.
+המבנה של הגרף מטפל ביחסים, reification ומטא-נתונים. משולשות מצוטטות
+וגרפים בעלי שם אינם מסבכים פעולות וקטוריות.
+
+## שיקולי אבטחה
+
+גרפים בעלי שם אינם תכונה של אבטחה. משתמשים ואוספים הם גבולות האבטחה.
+גרפים בעלי שם הם אך ורק עבור ארגון נתונים ו-reification תמיכה.
+
+## שיקולי ביצועים
+
+- משולשות מצוטטות מוסיפות עומק קינון - עשויות להשפיע על ביצועי השאילתות
+- אסטרטגיות אינדוקס לגרפים בעלי שם נחוצות עבור שאילתות יעילות מבוססות גרפים
+- עיצוב סכימת Cassandra יצטרך להתאים אחסון ארבעיות ביעילות
+
+### גבולת מאגר וקטורי
+
+מאגרי וקטורים תמיד מתייחסים ל-IRIs בלבד:
+- לעולם לא קצוות (משולשות מצוטטות)
+- לעולם לא ערכים מילוליים
+- לעולם לא צמתים ריקים
+
+זה שומר על מאגר הווקטורים פשוט - הוא מטפל בדמיון סמנטי של ישויות בעלות שם.
+המבנה של הגרף מטפל ביחסים, reification ומטא-נתונים. משולשות מצוטטות
+וגרפים בעלי שם אינם מסבכים פעולות וקטוריות.
+
+## אסטרטגיית בדיקה
+
+השתמש באסטרטגיית הבדיקה הקיימת. מכיוון שזוהי גרסה שבירה, יש להתמקד
+בבדיקות הקצה כדי לוודא שהמבנים החדשים עובדים כראוי בכל הרכיבים.
+
+## תוכנית העברה
+
+- 2.0 היא גרסה שבירה; אין צורך בתאימות לאחור
+- ייתכן שיהיה צורך להעביר נתונים קיימים לסכימה חדשה (בהתאם לעיצוב הסופי)
+- שקול כלי העברה להמרת משולשות קיימות
+
+## שאלות פתוחות
+
+- **צמתים ריקים**: תמיכה מוגבלת אושרה. ייתכן שיהיה צורך להחליט על
+  אסטרטגיית skolemization (ליצור IRIs בעת הטעינה, או לשמר מזהי צמתים ריקים).
+- **תחביר שאילתא**: מהו התחביר הקונקרטי לציין משולשות מצוטטות
+  בשאלות? יש להגדיר את ממשק ה-API של השאילתא.
+- ~~**אוצר מילים של תכונות**~~: נפתר. כל תכונות RDF חוקיות מותרות,
+  כולל מילים מוגדרות על ידי משתמש. הנחות מינימליות לגבי תוקף RDF.
+  אסטרטגיה: הימנע מנעילה אלא אם הכרחי לחלוטין.
+- ~~**השפעה על מאגר הווקטורים**~~: נפתר. מאגרי וקטורים תמיד מצביעים על
+  IRIs בלבד - לעולם לא קצוות, מילויים או צמתים ריקים. משולשות מצוטטות
+  וגרפים בעלי שם אינם משפיעים על מאגר הווקטורים.
+- ~~**סמנטיקת גרפים בעלי שם**~~: נפתר. שאילתות כברירת מחדל לגרף
+  כברירת מחדל (מתאים להתנהגות SPARQL, תואם לאחור). פרמטר גרף ספציפי
+  נדרש לשאילתא על גרפים בעלי שם או כל הגרפים.
+
+## הפניות
+
+- [מושגים של RDF 1.2](https://www.w3.org/TR/rdf12-concepts/)
+- [RDF-star ו-SPARQL-star](https://w3c.github.io/rdf-star/)
+- [סט נתונים RDF](https://www.w3.org/TR/rdf11-concepts/#section-dataset)