agent_platform_oci/LOCALIZACAO.md

# Termos e frases configuráveis — pt-BR e en

Esta distribuição inclui dois catálogos completos, em JSON UTF-8:

- `libs/agent_framework/src/agent_framework/locales/pt-BR.json`
- `libs/agent_framework/src/agent_framework/locales/en.json`

Cada arquivo reúne termos reconhecidos, mensagens padronizadas, instruções de
recuperação de guardrails e padrões de extração. JSON permite editar o catálogo
sem uma dependência adicional no carregador. Os dois arquivos usam as mesmas chaves.

## Selecionar o idioma

No `.env` do backend:

```dotenv
AGENT_LOCALE=en
```

Para português, use `AGENT_LOCALE=pt-BR` ou omita a variável. Também são aceitos
`pt`, `pt_BR`, `en-US` e `en-GB`. Uma opção inexistente gera erro; não há troca
silenciosa para português quando o idioma solicitado não está disponível.

O idioma é o padrão do backend. Os prompts e as configurações de negócio dos
agentes continuam sendo definidos pelo projeto; use prompts e descrições no
idioma desejado. Esta alteração não traduz automaticamente conteúdos de RAG,
respostas dos servidores MCP, mensagens declaradas por um workflow, arquivos de
exemplo, regras de negócio ou textos personalizados do aplicativo/frontend.
Prompts internos de classificação podem continuar em português: as decisões são
estruturadas. As instruções de recuperação que impunham português foram separadas
nos catálogos, incluindo sua variante em inglês.

## Personalizar sem alterar a biblioteca

Copie os catálogos para um diretório da aplicação e configure:

```dotenv
AGENT_LOCALE=en
AGENT_LOCALES_DIR=./config/locales
```

Nesse exemplo, o arquivo usado será `./config/locales/en.json`. O catálogo é
completo, e não um arquivo de alterações parciais. Preserve as chaves e os campos
como `{action}`, `{target}`, `{options}` e `{subject}` ao traduzir as frases.
Não é necessário manter a mesma quantidade de termos nas listas.

Reinicie o backend após editar os arquivos: o carregador mantém os catálogos em
cache. Na inicialização, ele verifica a estrutura, os campos das mensagens, a
sintaxe dos padrões e conflitos entre confirmação e recusa.

As principais seções são:

| Seção | Conteúdo |
|---|---|
| `terms.confirmation` | Confirmações e recusas explícitas de transações |
| `terms.workflow` | Respostas de compatibilidade para checkpoints antigos |
| `terms.multi_intent` | Conjunções, verbos e prefixos de confirmação |
| `terms.global_router` | Termos de continuidade e encerramento |
| `terms.groundedness` | Indícios de especificidade e incerteza |
| `terms.mock` | Termos dos classificadores locais usados em testes/desenvolvimento |
| `messages` | Frases de confirmação, nova tentativa, esclarecimento e fallback |
| `prompts.fallback` | Instruções de reescrita e regeneração por guardrail |
| `prompts.judge_rewrite` | Instruções de recuperação dos judges |
| `memory` | Padrões para extração de memória de longo prazo |
| `protocol` | Dígitos, letras e nomes usados na vocalização de protocolos |
| `safety` | Padrões determinísticos de segurança e escopo |
| `legacy_extraction` | Padrões do extrator legado de pedido/motivo |

## Decisões internas e contratos de workflow

Os códigos internos permanecem estáveis: `confirm`, `reject`, `SIM`, `NAO`,
`OUTRO` e nomes de estados não devem ser traduzidos em arquivos existentes.
O catálogo trata as palavras reconhecidas e os textos apresentados.

Um workflow que declara `expected_input`, `reprompt` ou mensagens próprias
continua tendo precedência. Para aceitar `YES` e `NO` em um contrato enumerado,
configure essas opções no workflow e ajuste suas transições, ou mantenha os
códigos atuais e use seu classificador semântico para mapear as respostas.
O dicionário global não substitui silenciosamente o contrato de um fluxo.

As listas de confirmação transacional usam correspondência da frase completa,
ignorando maiúsculas, espaços repetidos e pontuação final simples. Não inclua
frases ambíguas como “entendi”/“understood” nessas listas: compreender uma
explicação não equivale a autorizar uma operação. O fallback semântico existente
continua disponível para respostas que não constam do catálogo.

Os padrões de segurança mantêm cobertura em português e inglês nos dois arquivos.
Nomes de concorrentes presentes em `safety` preservam a configuração original de
telecom; adapte essas regras quando mudar o domínio da aplicação.

## Vários idiomas no mesmo processo

Para aplicações que selecionam o idioma por agente ou atendimento, envolva a
execução completa (roteamento, runtime e guardrails) no contexto correspondente:

```python
from agent_framework.localization import use_locale

with use_locale("en"):
    # Execute aqui o roteamento, o agente e seus guardrails.
    result = await handle_turn(...)
```

`handle_turn` representa o ponto de entrada da sua aplicação; não é uma nova API
do framework. O contexto usa `ContextVar`, é isolado entre tarefas assíncronas e
restaura o idioma anterior ao sair. Não altere `os.environ` a cada atendimento.
O idioma da conversa não é detectado automaticamente.

## Validação desta entrega

- 41 testes novos de localização aprovados.
- 160 testes selecionados aprovados após a atualização de oito testes antigos.
- As oito expectativas antigas estavam desalinhadas com mudanças de contrato
  anteriores à localização. Histórico, escopo e validação estão em
  `ATUALIZACAO_TESTES.md`. Os 66 testes dos quatro arquivos atualizados também
  passaram com a biblioteca original do ZIP.
- As verificações incluem execução/cancelamento real do runtime com ferramentas
  simuladas, confirmação determinística no roteador sem LLM, múltiplas intenções,
  retomada de workflows, memória, protocolos, segurança, concorrência e catálogo
  personalizado.
- Não foram feitas chamadas a modelos remotos, OCI ou ferramentas reais de negócio.

Os testes novos estão em `tests/test_locale_catalogs.py`. Para executá-los em um
ambiente com as dependências do projeto e pytest/pytest-asyncio:

```bash
PYTHONPATH=libs/agent_framework/src pytest -q tests/test_locale_catalogs.py
```

O pacote de entrega conserva os arquivos do projeto e remove metadados do macOS,
cache de bytecode, builds antigos e diretórios de Git/IDE. As fontes corrigidas
ficam em `libs/agent_framework/src`. As variantes de demonstração em
`Tuning-Performance` mantêm suas configurações de domínio originais.