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.

docs/tech-specs/structured-diag-service.he.md

@@ -0,0 +1,281 @@
+---
+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. השירות שואב פונקציונליות מכלי שורת הפקודה הקיים `tg-load-structured-data` ומציג אותו כשירות בקשה/תגובה, ומאפשר גישה תכנותית ליכולות זיהוי סוג נתונים ויצירת תיאורים.
+
+השירות תומך בשלוש פעולות עיקריות:
+
+1. **זיהוי סוג נתונים**: ניתוח דוגמת נתונים כדי לקבוע את הפורמט שלה (CSV, JSON או XML)
+2. **יצירת תיאור**: יצירת תיאור נתונים מובנים עבור דוגמת נתונים מסוימת וסוג
+3. **אבחון משולב**: ביצוע גם זיהוי סוג וגם יצירת תיאור ברצף
+
+## מטרות
+
+**מודולריזציה של ניתוח נתונים**: העברת לוגיקת אבחון נתונים משורת הפקודה לרכיבי שירות הניתנים לשימוש חוזר
+**אפשרות לגישה תכנותית**: מתן גישה מבוססת API ליכולות ניתוח נתונים
+**תמיכה במספר פורמטים של נתונים**: טיפול בפורמטי נתונים של CSV, JSON ו-XML באופן עקבי
+**יצירת תיאורים מדויקים**: יצירת תיאורי נתונים מובנים המתאימים בצורה מדויקת לנתוני המקור לתוך סכימות TrustGraph
+**שמירה על תאימות לאחור**: הבטחה שפונקציונליות קיימת של שורת הפקודה תמשיך לעבוד
+**אפשרות לחיבור שירותים**: לאפשר לשירותים אחרים לנצל יכולות אבחון נתונים
+**שיפור יכולת בדיקה**: הפרדת לוגיקה עסקית מממשק שורת הפקודה לצורך בדיקות טובות יותר
+**תמיכה בניתוח סטרימינג**: אפשרות לניתוח דוגמאות נתונים מבלי לטעון קבצים שלמים
+
+## רקע
+
+כיום, הפקודה `tg-load-structured-data` מספקת פונקציונליות מקיפה לניתוח נתונים מובנים ויצירת תיאורים. עם זאת, פונקציונליות זו קשורה הדוקות לממשק שורת הפקודה, מה שמגביל את יכולת השימוש החוזר בה.
+
+מגבלות נוכחיות כוללות:
+לוגיקת אבחון נתונים מוטמעת בקוד שורת הפקודה
+אין גישה תכנותית לזיהוי סוג ויצירת תיאורים
+קשה לשלב יכולות אבחון בשירותים אחרים
+יכולת מוגבלת ליצור זרימות עבודה לניתוח נתונים
+
+מפרט זה מתייחס לפערים אלה על ידי יצירת שירות ייעודי לאבחון נתונים מובנים. על ידי חשיפת יכולות אלה כשירות, TrustGraph יכולה:
+לאפשר לשירותים אחרים לנתח נתונים באופן תכנותי
+לתמוך בצינורות עיבוד נתונים מורכבים יותר
+להקל על שילוב עם מערכות חיצוניות
+לשפר את תחזוקת המערכת באמצעות הפרדת אחריות
+
+## עיצוב טכני
+
+### ארכיטקטורה
+
+שירות האבחון של נתונים מובנים דורש את הרכיבים הטכניים הבאים:
+
+1. **מעבד שירות אבחון**
+   מטפל בבקשות אבחון נכנסות
+   מתאם זיהוי סוג ויצירת תיאורים
+   מחזיר תגובות מובנות עם תוצאות אבחון
+
+   מודול: `trustgraph-flow/trustgraph/diagnosis/structured_data/service.py`
+
+2. **מגַלֶּה סוג נתונים**
+   משתמש בגילוי אלגוריתמי כדי לזהות פורמט נתונים (CSV, JSON, XML)
+   מנתח מבנה נתונים, מפרידים ותבניות תחביר
+   מחזיר פורמט מזוהה וציוני אמון
+
+   מודול: `trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py`
+
+3. **יוצר תיאורים**
+   משתמש בשירות פרומפטים כדי ליצור תיאורים
+   מפעיל פרומפטים ספציפיים לפורמט (diagnose-csv, diagnose-json, diagnose-xml)
+   ממפה שדות נתונים לשדות סכימת TrustGraph באמצעות תגובות פרומפטים
+
+   מודול: `trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py`
+
+### מודלים של נתונים
+
+#### StructuredDataDiagnosisRequest
+
+הודעת בקשה לפעולות אבחון נתונים מובנים:
+
+```python
+class StructuredDataDiagnosisRequest:
+    operation: str  # "detect-type", "generate-descriptor", or "diagnose"
+    sample: str     # Data sample to analyze (text content)
+    type: Optional[str]  # Data type (csv, json, xml) - required for generate-descriptor
+    schema_name: Optional[str]  # Target schema name for descriptor generation
+    options: Dict[str, Any]  # Additional options (e.g., delimiter for CSV)
+```
+
+#### תגובת אבחון נתונים מובנים
+
+הודעת תגובה המכילה תוצאות אבחון:
+
+```python
+class StructuredDataDiagnosisResponse:
+    operation: str  # The operation that was performed
+    detected_type: Optional[str]  # Detected data type (for detect-type/diagnose)
+    confidence: Optional[float]  # Confidence score for type detection
+    descriptor: Optional[Dict]  # Generated descriptor (for generate-descriptor/diagnose)
+    error: Optional[str]  # Error message if operation failed
+    metadata: Dict[str, Any]  # Additional metadata (e.g., field count, sample records)
+```
+
+#### מבנה תיאור
+
+התיאור שנוצר עוקב אחר פורמט התיאור המובנה הקיים:
+
+```json
+{
+  "format": {
+    "type": "csv",
+    "encoding": "utf-8",
+    "options": {
+      "delimiter": ",",
+      "has_header": true
+    }
+  },
+  "mappings": [
+    {
+      "source_field": "customer_id",
+      "target_field": "id",
+      "transforms": [
+        {"type": "trim"}
+      ]
+    }
+  ],
+  "output": {
+    "schema_name": "customer",
+    "options": {
+      "batch_size": 1000,
+      "confidence": 0.9
+    }
+  }
+}
+```
+
+### ממשק שירות
+
+השירות יחשוף את הפעולות הבאות באמצעות תבנית בקשה/תגובה:
+
+1. **פעולת זיהוי סוג**
+   קלט: דוגמת נתונים
+   עיבוד: ניתוח מבנה הנתונים באמצעות זיהוי אלגוריתמי
+   פלט: סוג מזוהה עם ציון אמון
+
+2. **פעולת יצירת תיאור**
+   קלט: דוגמת נתונים, סוג, שם סכימה יעד
+   עיבוד:
+     הפעלת שירות הפרומפט עם מזהה הפרומפט הספציפי לפורמט (diagnose-csv, diagnose-json או diagnose-xml)
+     העברת דוגמת הנתונים והסכימות הזמינות לפרומפט
+     קבלת התיאור שנוצר מתגובת הפרומפט
+   פלט: תיאור נתונים מובנים
+
+3. **פעולת אבחון משולבת**
+   קלט: דוגמת נתונים, שם סכימה אופציונלי
+   עיבוד:
+     שימוש בזיהוי אלגוריתמי לזיהוי הפורמט תחילה
+     בחירת פרומפט ספציפי לפורמט בהתאם לסוג המזוהה
+     הפעלת שירות הפרומפט ליצירת תיאור
+   פלט: גם הסוג המזוהה וגם התיאור
+
+### פרטי יישום
+
+השירות יפעל בהתאם לקונבנציות של שירות TrustGraph:
+
+1. **רישום שירות**
+   רישום כסוג שירות `structured-diag`
+   שימוש בנושאים סטנדרטיים של בקשה/תגובה
+   יישום מחלקת FlowProcessor בסיסית
+   רישום PromptClientSpec עבור אינטראקציה עם שירות הפרומפט
+
+2. **ניהול תצורה**
+   גישה לתצורות סכימה באמצעות שירות התצורה
+   שמירת סכימות במטמון לביצועים
+   טיפול בעדכוני תצורה באופן דינמי
+
+3. **שילוב פרומפט**
+   שימוש בתשתית קיימת של שירות הפרומפט
+   הפעלת שירות הפרומפט עם מזהי פרומפט ספציפיים לפורמט:
+     `diagnose-csv`: לניתוח נתוני CSV
+     `diagnose-json`: לניתוח נתוני JSON
+     `diagnose-xml`: לניתוח נתוני XML
+   הפרומפטים מוגדרים בתצורת הפרומפט, ולא מקודדים קשות בשירות
+   העברת סכימות ודוגמאות נתונים כמשתני פרומפט
+   ניתוח תגובות פרומפט לחילוץ תיאורים
+
+4. **טיפול בשגיאות**
+   אימות דוגמאות נתונים
+   מתן הודעות שגיאה תיאוריות
+   טיפול מסודר בנתונים פגומים
+   טיפול בכשלים בשירות הפרומפט
+
+5. **דגימת נתונים**
+   עיבוד גדלי דגימה הניתנים לתצורה
+   טיפול מתאים ברשומות חסרות
+   שמירה על עקביות דגימה
+
+### שילוב API
+
+השירות ישולב עם ממשקי TrustGraph קיימים:
+
+רכיבים שעברו שינוי:
+`tg-load-structured-data` CLI - שופץ לשימוש בשירות החדש לפעולות אבחון
+Flow API - הורחב לתמיכה בבקשות אבחון נתונים מובנים
+
+נקודות שירות חדשות:
+`/api/v1/flow/{flow}/diagnose/structured-data` - נקודת קצה WebSocket לבקשות אבחון
+`/api/v1/diagnose/structured-data` - נקודת קצה REST לאבחון סינכרוני
+
+### זרימת הודעות
+
+```
+Client → Gateway → Structured Diag Service → Config Service (for schemas)
+                                           ↓
+                                    Type Detector (algorithmic)
+                                           ↓
+                                    Prompt Service (diagnose-csv/json/xml)
+                                           ↓
+                                 Descriptor Generator (parses prompt response)
+                                           ↓
+Client ← Gateway ← Structured Diag Service (response)
+```
+
+## שיקולי אבטחה
+
+אימות קלט למניעת התקפות הזרקה
+מגבלות גודל על דוגמאות נתונים למניעת התקפות מניעת שירות (DoS)
+ניקוי של מזהים שנוצרו
+בקרת גישה באמצעות אימות TrustGraph הקיים
+
+## שיקולי ביצועים
+
+שמירת הגדרות סכימה במטמון להפחתת קריאות לשירות התצורה
+הגבלת גודל הדוגמאות לשמירה על ביצועים מהירים
+שימוש בעיבוד סטרימינג עבור דוגמאות נתונים גדולות
+הטמעת מנגנוני זמן קצוב עבור ניתוחים ארוכים
+
+## אסטרטגיית בדיקות
+
+1. **בדיקות יחידה**
+   זיהוי סוג עבור פורמטי נתונים שונים
+   דיוק יצירת מזהים
+   תרחישי טיפול בשגיאות
+
+2. **בדיקות אינטגרציה**
+   זרימת בקשות/תגובות של שירות
+   שליפה ושמירה במטמון של סכימות
+   אינטגרציה עם שורת הפקודה (CLI)
+
+3. **בדיקות ביצועים**
+   עיבוד של דוגמאות גדולות
+   טיפול בבקשות מקבילות
+   שימוש בזיכרון בתנאי עומס
+
+## תוכנית מעבר
+
+1. **שלב 1**: הטמעת שירות עם פונקציונליות בסיסית
+2. **שלב 2**: שינוי שורת הפקודה (CLI) לשימוש בשירות (שמירה על תאימות לאחור)
+3. **שלב 3**: הוספת נקודות קצה של ממשק API REST
+4. **שלב 4**: הפסקת השימוש בלוגיקה מוטמעת של שורת הפקודה (עם תקופת התראה)
+
+## ציר זמן
+
+שבוע 1-2: הטמעת שירות וזיהוי סוג בסיסי
+שבוע 3-4: הוספת יצירת מזהים ואינטגרציה
+שבוע 5: בדיקות ותיעוד
+שבוע 6: שינוי שורת הפקודה (CLI) ומעבר
+
+## שאלות פתוחות
+
+האם השירות צריך לתמוך בפורמטי נתונים נוספים (לדוגמה, Parquet, Avro)?
+מהו גודל הדוגמה המקסימלי לניתוח?
+האם תוצאות האבחון צריכות להיות שמורות במטמון עבור בקשות חוזרות?
+כיצד השירות צריך להתמודד עם תרחישים של סכימות מרובות?
+האם מזהי הבקשות צריכים להיות פרמטרים הניתנים להגדרה עבור השירות?
+
+## הפניות
+
+[מפרט מזהה נתונים מובנים](structured-data-descriptor.md)
+[תיעוד טעינת נתונים מובנים](structured-data.md)
+`tg-load-structured-data` יישום: `trustgraph-cli/trustgraph/cli/load_structured_data.py`