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.ru.md
+++ b/docs/tech-specs/graph-contexts.ru.md
@ -0,0 +1,415 @@
+---
+layout: default
+title: "Техническая спецификация контекстов графов"
+parent: "Russian (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 утверждает, что это неправда"
+  - Обеспечение оценки надежности и обнаружения конфликтов
+
+**Гипотеза**: Реификация (RDF-star / цитируемые тройки) является ключевым
+механизмом для достижения этих результатов, поскольку все они требуют
+создания утверждений об утверждениях.
+
+## Предыстория
+
+Чтобы выразить фразу "факт (Алиса знает Боба) был обнаружен 15 января 2024 года"
+или "источник 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 (RDF-star)**
+   - Ребра, указывающие на другие ребра
+   - Тройка может быть субъектом или объектом другой тройки
+   - Позволяет делать утверждения об утверждениях (реификация)
+   - Основной механизм для аннотирования отдельных фактов
+
+2. **Набор данных RDF / Именованные графы**
+   - Поддержка нескольких именованных графов внутри набора данных
+   - Каждый граф идентифицируется IRI
+   - Переход от троек (s, p, o) к квадам (s, p, o, g)
+   - Включает граф по умолчанию и ноль или более именованных графов
+   - IRI графа может быть субъектом в утверждениях, например:
+     ```
+     <graph-source-A> <discoveredOn> "2024-01-15"
+     <graph-source-A> <hasVeracity> "high"
+     ```
+   - Обратите внимание: Именованные графы - это отдельная функция от
+     реификации. Они имеют другие применения (разделение, контроль доступа,
+     организация набора данных) и должны рассматриваться как отдельная
+     возможность.
+
+3. **Анонимные узлы** (Ограниченная поддержка)
+   - Анонимные узлы без глобального URI
+   - Поддерживаются для совместимости при загрузке внешних данных RDF
+   - **Ограниченный статус**: Без гарантий стабильной идентичности после
+     загрузки
+   - Находите их с помощью запросов по подстановочным знакам (сопоставляйте по
+     связям, а не по ID)
+   - Не являются основной функцией - не полагайтесь на точную обработку
+     анонимных узлов
+
+#### Временные исправления (радикальное изменение в 2.0)
+
+Эти функции не связаны напрямую с целями реификации, но являются ценными
+улучшениями, которые следует включить при внесении радикальных изменений:
+
+4. **Типы литералов**
+   - Правильное использование поля `type` для типов данных XSD
+   - Примеры: xsd:string, xsd:integer, xsd:dateTime и т.д.
+   - Исправляет текущее ограничение: невозможно правильно представлять даты
+     или целые числа
+
+5. **Языковые теги**
+   - Поддержка языковых атрибутов для строковых литералов (@en, @fr и т.д.)
+   - Обратите внимание: у литерала либо языковой тег, ЛИБО тип данных, но не
+     оба (за исключением rdf:langString)
+   - Важно для сценариев использования ИИ/многоязычности
+
+### Модели данных
+
+#### Термин (переименование из Value)
+
+Класс `Value` будет переименован в `Term`, чтобы лучше отражать терминологию
+RDF. Это переименование имеет две цели:
+1. Согласование наименований с концепциями RDF ( "Term" может быть IRI,
+   литералом, анонимным узлом или цитируемой тройкой - а не просто
+   "значением")
+2. Вызывает проверку кода на интерфейсе радикальных изменений - любой код,
+   который все еще ссылается на `Value`, явно не работает и требует
+   обновления
+
+Термин может представлять:
+
+- **IRI/URI** - Именованный узел/ресурс
+- **Анонимный узел** - Анонимный узел с локальной областью
+- **Литерал** - Значение данных с одним из следующих:
+  - Тип данных (тип XSD) ИЛИ
+  - Языковой тег
+- **Цитируемая тройка** - Тройка, используемая в качестве термина (RDF 1.2)
+
+##### Выбранный подход: Одиночный класс с дискриминатором типа
+
+Структура определяется требованиями сериализации - в формате передачи данных
+необходим дискриминатор типа, независимо от представления на Python.
+Одиночный класс с полем типа - это естественный выбор и соответствует
+текущему шаблону `Value`.
+
+Односимвольный код типа обеспечивает компактную сериализацию:
+
+```python
+from dataclasses import dataclass
+
+# Константы типа Term
+IRI = "i"      # IRI/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)
+    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    # Subject
+    p: Term | None = None    # Predicate
+    o: Term | None = None    # Object
+    g: str | None = None     # Имя графа (IRI), None = граф по умолчанию
+```
+
+Решения в дизайне:
+- **Имя поля**: `g` для согласованности с `s`, `p`, `o`
+- **Необязательно**: `None` означает граф по умолчанию (неименованный)
+- **Тип**: Обычная строка (IRI) вместо Term
+  - Имена графов всегда являются IRI
+  - Анонимные узлы в качестве имен графов не допускаются (слишком
+    путано)
+  - Нет необходимости в полной машинерии Term
+
+Обратите внимание: Имя класса остается `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> >>          # цитируемая тройка как субъект
+P: <believedTrueFrom>
+O: ?                                    # возвращает дату
+```
+
+**Найти факты, которые были признаны ложными:**
+```
+S: ?                                    # любая цитируемая тройка
+P: <discoveredFalseOn>
+O: ?                                    # имеет любое значение (существует)
+```
+
+#### Запросы происхождения
+
+**Найти все факты, подтвержденные определенным источником:**
+```
+S: ?                                    # любая цитируемая тройка
+P: <supportedBy>
+O: <source:document-123>
+```
+
+**Найти, какие источники подтверждают определенный факт:**
+```
+S: << <DrugA> <treats> <DiseaseB> >>    # цитируемая тройка как субъект
+P: <supportedBy>
+O: ?                                    # возвращает IRI источника
+```
+
+#### Запросы достоверности
+
+**Найти утверждения, которые пользователь отметил как истинные:**
+```
+S: ?                                    # любая цитируемая тройка
+P: <assertedTrueBy>
+O: <person:Alice>
+```
+
+**Найти конфликтующие утверждения (один и тот же факт, разная достоверность):**
+```
+# Первый запрос: факты, отмеченные как истинные
+S: ?
+P: <assertedTrueBy>
+O: ?
+
+# Второй запрос: факты, отмеченные как ложные
+S: ?
+P: <assertedFalseBy>
+O: ?
+
+# Логика приложения: найти пересечение субъектов
+```
+
+**Найти факты со значением надежности ниже определенного значения:**
+- **Vector store impact**
+```
+S: ?
+P: <value>
+O: <threshold>
+```
+
+### Граница хранилища векторов
+
+Хранилища векторов всегда ссылаются только на IRI:
+- Никогда на ребра (цитируемые тройки)
+- Никогда на литеральные значения
+- Никогда на анонимные узлы
+
+Это упрощает хранилище векторов - оно обрабатывает семантическое сходство
+именованных сущностей. Структура графа обрабатывает отношения,
+реификацию и метаданные. Цитируемые тройки и именованные графы не
+усложняют операции с векторами.
+
+## Соображения безопасности
+
+Именованные графы не являются функцией безопасности. Пользователи и
+коллекции остаются границами безопасности. Именованные графы предназначены
+исключительно для организации данных и поддержки реификации.
+
+## Соображения производительности
+
+- Цитируемые тройки добавляют глубину вложенности - могут повлиять на
+  производительность запросов
+- Необходимы стратегии индексирования именованных графов для эффективных
+  запросов, охватывающих графы
+- Проект схемы Cassandra должен учитывать эффективное хранение квадов.
+
+### Vector store boundary
+
+Vector stores always reference IRIs only:
+- Never edges (quoted triples)
+- Never literal values
+- Never blank nodes
+
+This keeps the vector store simple - it handles semantic similarity of named
+entities. The graph structure handles relationships, reification, and metadata.
+Quoted triples and named graphs don't complicate vector operations.
+
+## Стратегия тестирования
+
+Используйте существующую стратегию тестирования. Поскольку это радикальное
+изменение, особое внимание уделяется комплексному набору тестов для
+проверки правильности работы новых структур во всех компонентах.
+
+## План миграции
+
+- 2.0 - это радикальное изменение; обратная совместимость не требуется
+- Существующие данные могут потребовать миграции на новую схему (будет
+  определено на основе окончательного проекта)
+- Рассмотрите возможность использования инструментов миграции для преобразования
+  существующих троек
+
+## Открытые вопросы
+
+- **Анонимные узлы**: Подтверждена ограниченная поддержка. Возможно, потребуется
+  определить стратегию сколемизации (генерировать IRI при загрузке или
+  сохранять идентификаторы анонимных узлов).
+- **Синтаксис запросов**: Какой конкретный синтаксис используется для
+  указания цитируемых троек в запросах? Необходимо определить API запросов.
+- ~~**Словарь предикатов**~~: Решено. Допускаются любые допустимые
+  предикаты RDF, включая пользовательские. Минимальные предположения о
+  валидности RDF. Очень мало жестко заданных значений (например,
+  `rdfs:label` используется в некоторых местах). Стратегия: избегать
+  фиксирования чего-либо, если это абсолютно необходимо.
+- ~~**Влияние на хранилище векторов**~~: Решено. Хранилища векторов
+  всегда указывают только на IRI - никогда на ребра, литеральные значения или
+  анонимные узлы. Цитируемые тройки и реификация не влияют на хранилище
+  векторов.
+- ~~**Семантика именованных графов**~~: Решено. Запросы по умолчанию
+  выполняются к графу по умолчанию (соответствует поведению 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)
+```