Arquitetura e Uso do Sistema de Tradução (i18n On-Demand)

Visão Geral

A plataforma utiliza um modelo Híbrido On-Demand com Cache Persistente (Lazy Translation Pattern) para tradução de posts e comentários em tempo real, permitindo que usuários globais se comuniquem no idioma nativo de cada um (estilo Reddit / Circle.so).

---

Componentes

1. Docker Service (LibreTranslate):

   • Rodando via Docker Compose na porta 5000.
   • Baixa e persiste automaticamente os modelos de idioma (en, pt, es) no volume Docker libretranslate_data.

2. Serviço de Tradução Resiliente (apps.utils.services.translation):

   • translate_text: Suporta múltiplos provedores (libretranslate, argos, llm).
   • safe_translate: Resiliência com fallback automático. Caso o LibreTranslate esteja indisponível ou estoure o timeout (configurável via TRANSLATION_TIMEOUT_SECONDS), tenta um LLM secundário (ex: OpenAI gpt-4o-mini) ou retorna graciosamente o texto original sem travar a requisição do usuário.

3. Cache de Tradução (TranslatableModel):

   • Os models Post e Comment herdam de TranslatableModel, fornecendo a coluna i18n (JSONField).
   • Estrutura do cache no banco:

     {
       "en": { "body": "Hello world!", "title": "Welcome" },
       "es": { "body": "¡Hola mundo!", "title": "Bienvenido" }
     }

---

Endpoints REST API

Traduzir Post

• URL: POST /api/v1/spaces/posts/{post_id}/translate/
• Payload:

  {
    "target_lang": "en"
  }

• Resposta:

  {
    "translated_text": "Hello world!",
    "status": "success",
    "target_lang": "en"
  }

• Nota: Se a tradução para en já existir no cache do post, o resultado é retornado instantaneamente sem nenhuma chamada a APIs externas.

Traduzir Comentário

• URL: POST /api/v1/spaces/comments/{comment_id}/translate/
• Payload:

  {
    "target_lang": "es"
  }

---

Configurações no settings.py / .env

• LIBRETRANSLATE_URL: http://libretranslate:5000
• TRANSLATION_PRIMARY_PROVIDER: libretranslate
• TRANSLATION_TIMEOUT_SECONDS: 3.0