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/vector-store-lifecycle.pt.md

@@ -0,0 +1,307 @@
+---
+layout: default
+title: "Gerenciamento do Ciclo de Vida do Vector Store"
+parent: "Portuguese (Beta)"
+---
+
+# Gerenciamento do Ciclo de Vida do Vector Store
+
+> **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.
+
+## Visão Geral
+
+Este documento descreve como o TrustGraph gerencia coleções de vector store em diferentes implementações de backend (Qdrant, Pinecone, Milvus). O design aborda o desafio de suportar embeddings com diferentes dimensões sem codificar valores de dimensão.
+
+## Declaração do Problema
+
+Os vector stores exigem que a dimensão do embedding seja especificada ao criar coleções/índices. No entanto:
+Modelos de embedding diferentes produzem dimensões diferentes (por exemplo, 384, 768, 1536)
+A dimensão não é conhecida até que o primeiro embedding seja gerado
+Uma única coleção do TrustGraph pode receber embeddings de vários modelos
+A codificação de uma dimensão (por exemplo, 384) causa falhas com outros tamanhos de embedding
+
+## Princípios de Design
+
+1. **Criação Preguiçosa (Lazy Creation)**: As coleções são criadas sob demanda durante a primeira escrita, e não durante as operações de gerenciamento de coleção.
+2. **Nomeação Baseada em Dimensão**: Os nomes das coleções incluem a dimensão do embedding como um sufixo.
+3. **Degradação Graciosa**: As consultas contra coleções inexistentes retornam resultados vazios, e não erros.
+4. **Suporte a Múltiplas Dimensões**: Uma única coleção lógica pode ter várias coleções físicas (uma por dimensão).
+
+## Arquitetura
+
+### Convenção de Nomenclatura de Coleções
+
+As coleções de vector store usam sufixos de dimensão para suportar vários tamanhos de embedding:
+
+**Embeddings de Documentos:**
+Qdrant: `d_{user}_{collection}_{dimension}`
+Pinecone: `d-{user}-{collection}-{dimension}`
+Milvus: `doc_{user}_{collection}_{dimension}`
+
+**Embeddings de Grafos:**
+Qdrant: `t_{user}_{collection}_{dimension}`
+Pinecone: `t-{user}-{collection}-{dimension}`
+Milvus: `entity_{user}_{collection}_{dimension}`
+
+Exemplos:
+`d_alice_papers_384` - Coleção de artigos da Alice com embeddings de 384 dimensões
+`d_alice_papers_768` - Mesma coleção lógica com embeddings de 768 dimensões
+`t_bob_knowledge_1536` - Grafo de conhecimento do Bob com embeddings de 1536 dimensões
+
+### Fases do Ciclo de Vida
+
+#### 1. Solicitação de Criação de Coleção
+
+**Fluxo da Solicitação:**
+```
+User/System → Librarian → Storage Management Topic → Vector Stores
+```
+
+**Comportamento:**
+O bibliotecário transmite solicitações `create-collection` para todos os backends de armazenamento.
+Os processadores de armazenamento vetorial confirmam a solicitação, mas **não criam coleções físicas**.
+A resposta é retornada imediatamente com sucesso.
+A criação real da coleção é adiada até a primeira escrita.
+
+**Justificativa:**
+A dimensão é desconhecida no momento da criação.
+Evita a criação de coleções com dimensões incorretas.
+Simplifica a lógica de gerenciamento de coleções.
+
+#### 2. Operações de Escrita (Criação Preguiçosa)
+
+**Fluxo de Escrita:**
+```
+Data → Storage Processor → Check Collection → Create if Needed → Insert
+```
+
+**Comportamento:**
+1. Extrair a dimensão do embedding do vetor: `dim = len(vector)`
+2. Construir o nome da coleção com o sufixo da dimensão
+3. Verificar se a coleção existe com essa dimensão específica
+4. Se não existir:
+   Criar a coleção com a dimensão correta
+   Registrar: `"Lazily creating collection {name} with dimension {dim}"`
+5. Inserir o embedding na coleção específica da dimensão
+
+**Cenário de Exemplo:**
+```
+1. User creates collection "papers"
+   → No physical collections created yet
+
+2. First document with 384-dim embedding arrives
+   → Creates d_user_papers_384
+   → Inserts data
+
+3. Second document with 768-dim embedding arrives
+   → Creates d_user_papers_768
+   → Inserts data
+
+Result: Two physical collections for one logical collection
+```
+
+#### 3. Operações de Consulta
+
+**Fluxo de Consulta:**
+```
+Query Vector → Determine Dimension → Check Collection → Search or Return Empty
+```
+
+**Comportamento:**
+1. Extrair a dimensão do vetor de consulta: `dim = len(vector)`
+2. Construir o nome da coleção com o sufixo da dimensão
+3. Verificar se a coleção existe
+4. Se existir:
+   Realizar uma busca de similaridade
+   Retornar os resultados
+5. Se não existir:
+   Registrar: `"Collection {name} does not exist, returning empty results"`
+   Retornar uma lista vazia (nenhum erro é gerado)
+
+**Múltiplas Dimensões na Mesma Consulta:**
+Se a consulta contiver vetores de dimensões diferentes
+Cada dimensão consulta sua coleção correspondente
+Os resultados são agregados
+As coleções ausentes são ignoradas (não são tratadas como erros)
+
+**Justificativa:**
+Consultar uma coleção vazia é um caso de uso válido
+Retornar resultados vazios é semanticamente correto
+Evita erros durante a inicialização do sistema ou antes da ingestão de dados
+
+#### 4. Exclusão de Coleção
+
+**Fluxo de Exclusão:**
+```
+Delete Request → List All Collections → Filter by Prefix → Delete All Matches
+```
+
+**Comportamento:**
+1. Construir o padrão de prefixo: `d_{user}_{collection}_` (observe o sublinhado no final)
+2. Listar todas as coleções no armazenamento vetorial
+3. Filtrar as coleções que correspondem ao prefixo
+4. Excluir todas as coleções correspondentes
+5. Registrar cada exclusão: `"Deleted collection {name}"`
+6. Registro resumido: `"Deleted {count} collection(s) for {user}/{collection}"`
+
+**Exemplo:**
+```
+Collections in store:
+- d_alice_papers_384
+- d_alice_papers_768
+- d_alice_reports_384
+- d_bob_papers_384
+
+Delete "papers" for alice:
+→ Deletes: d_alice_papers_384, d_alice_papers_768
+→ Keeps: d_alice_reports_384, d_bob_papers_384
+```
+
+**Justificativa:**
+Garante a limpeza completa de todas as variantes de dimensão.
+A correspondência de padrões evita a exclusão acidental de coleções não relacionadas.
+Operação atômica da perspectiva do usuário (todas as dimensões são excluídas juntas).
+
+## Características Comportamentais
+
+### Operações Normais
+
+**Criação de Coleção:**
+✓ Retorna sucesso imediatamente.
+✓ Nenhum armazenamento físico é alocado.
+✓ Operação rápida (sem E/S de backend).
+
+**Primeira Escrita:**
+✓ Cria a coleção com a dimensão correta.
+✓ Ligeiramente mais lenta devido à sobrecarga da criação da coleção.
+✓ Escritas subsequentes na mesma dimensão são rápidas.
+
+**Consultas Antes de Qualquer Escrita:**
+✓ Retorna resultados vazios.
+✓ Nenhum erro ou exceção.
+✓ O sistema permanece estável.
+
+**Escritas de Dimensões Mistas:**
+✓ Cria automaticamente coleções separadas por dimensão.
+✓ Cada dimensão é isolada em sua própria coleção.
+✓ Nenhum conflito de dimensão ou erro de esquema.
+
+**Exclusão de Coleção:**
+✓ Remove todas as variantes de dimensão.
+✓ Limpeza completa.
+✓ Nenhuma coleção órfã.
+
+### Casos Limite
+
+**Múltiplos Modelos de Incorporação:**
+```
+Scenario: User switches from model A (384-dim) to model B (768-dim)
+Behavior:
+- Both dimensions coexist in separate collections
+- Old data (384-dim) remains queryable with 384-dim vectors
+- New data (768-dim) queryable with 768-dim vectors
+- Cross-dimension queries return results only for matching dimension
+```
+
+**Primeiras Escritas Concorrentes:**
+```
+Scenario: Multiple processes write to same collection simultaneously
+Behavior:
+- Each process checks for existence before creating
+- Most vector stores handle concurrent creation gracefully
+- If race condition occurs, second create is typically idempotent
+- Final state: Collection exists and both writes succeed
+```
+
+**Migração de Dimensões:**
+```
+Scenario: User wants to migrate from 384-dim to 768-dim embeddings
+Behavior:
+- No automatic migration
+- Old collection (384-dim) persists
+- New collection (768-dim) created on first new write
+- Both dimensions remain accessible
+- Manual deletion of old dimension collections possible
+```
+
+**Consultas de Coleção Vazia:**
+```
+Scenario: Query a collection that has never received data
+Behavior:
+- Collection doesn't exist (never created)
+- Query returns empty list
+- No error state
+- System logs: "Collection does not exist, returning empty results"
+```
+
+## Notas de Implementação
+
+### Especificidades do Backend de Armazenamento
+
+**Qdrant:**
+Usa `collection_exists()` para verificações de existência
+Usa `get_collections()` para listagem durante a exclusão
+A criação de coleções requer `VectorParams(size=dim, distance=Distance.COSINE)`
+
+**Pinecone:**
+Usa `has_index()` para verificações de existência
+Usa `list_indexes()` para listagem durante a exclusão
+A criação de índices requer esperar pelo status "ready"
+Especificação serverless configurada com cloud/região
+
+**Milvus:**
+Classes diretas (`DocVectors`, `EntityVectors`) gerenciam o ciclo de vida
+Cache interno `self.collections[(dim, user, collection)]` para desempenho
+Nomes de coleções são sanitizados (apenas alfanumérico + underscore)
+Suporta esquema com IDs de incremento automático
+
+### Considerações de Desempenho
+
+**Latência da Primeira Gravação:**
+Overhead adicional devido à criação da coleção
+Qdrant: ~100-500ms
+Pinecone: ~10-30 segundos (provisionamento serverless)
+Milvus: ~500-2000ms (inclui indexação)
+
+**Desempenho da Consulta:**
+A verificação de existência adiciona um overhead mínimo (~1-10ms)
+Nenhum impacto no desempenho depois que a coleção existe
+Cada coleção de dimensões é otimizada independentemente
+
+**Overhead de Armazenamento:**
+Metadados mínimos por coleção
+O principal overhead é por armazenamento de dimensão
+Compromisso: Espaço de armazenamento vs. flexibilidade de dimensão
+
+## Considerações Futuras
+
+**Consolidação Automática de Dimensões:**
+Poderia adicionar um processo em segundo plano para identificar e mesclar variantes de dimensões não utilizadas
+Requereria re-embedding ou redução de dimensão
+
+**Descoberta de Dimensões:**
+Poderia expor uma API para listar todas as dimensões em uso para uma coleção
+Útil para administração e monitoramento
+
+**Preferência de Dimensão Padrão:**
+Poderia rastrear a "dimensão primária" por coleção
+Usar para consultas quando o contexto da dimensão não está disponível
+
+**Quotas de Armazenamento:**
+Pode ser necessário limites de dimensão por coleção
+Prevenir a proliferação de variantes de dimensão
+
+## Notas de Migração
+
+**Do Sistema de Sufixo de Pré-Dimensão:**
+Coleções antigas: `d_{user}_{collection}` (sem sufixo de dimensão)
+Coleções novas: `d_{user}_{collection}_{dim}` (com sufixo de dimensão)
+Nenhuma migração automática - coleções antigas permanecem acessíveis
+Considere um script de migração manual, se necessário
+Pode executar ambos os esquemas de nomenclatura simultaneamente
+
+## Referências
+
+Gerenciamento de Coleções: `docs/tech-specs/collection-management.md`
+Esquema de Armazenamento: `trustgraph-base/trustgraph/schema/services/storage.py`
+Serviço Librarian: `trustgraph-flow/trustgraph/librarian/service.py`