Pular para o conteúdo principal

Como o Sync Funciona

O comando sync é a operação principal do rosetta. Aqui está o que acontece quando você executa npx i18n-rosetta sync.

Visão Geral do Pipeline​

Passo a Passo​

1. Resolução de Configuração​

O rosetta carrega o i18n-rosetta.config.json (ou detecta as configurações automaticamente). Ele resolve:

  • Localidade de origem e localidades de destino
  • O grafo de pares (quais combinações origem→destino processar)
  • Configurações de método, modelo e qualidade por par

2. Varredura da Origem​

O arquivo de localidade de origem é carregado e convertido em um mapa plano de chave→valor:

// Input (nested)
{ "hero": { "title": "Welcome", "subtitle": "Build" } }

// Flattened
{ "hero.title": "Welcome", "hero.subtitle": "Build" }

3. Detecção de Alterações​

O rosetta lê o .i18n-rosetta.lock, que armazena hashes SHA-256 de valores de origem traduzidos anteriormente. Para cada chave, ele verifica:

CondiçãoAção
Chave ausente no destinoTraduzir
Hash de origem alterado desde o último syncRetraduzir (desatualizado)
Valor de destino começa com [EN]Retraduzir (placeholder de fallback)
Hash de origem inalterado, chave existeIgnorar

É por isso que o rosetta traduz apenas o que mudou — ele não retraduz o arquivo inteiro a cada sync.

4. Agrupamento em Lotes​

As chaves são agrupadas em lotes (padrão: 30 chaves/lote para LLM, 128 para o Google Translate). O agrupamento em lotes reduz as requisições (round trips) à API, mantendo os prompts gerenciáveis.

5. Tradução​

Cada lote é enviado para o método de tradução configurado:

  • llm: Prompt estruturado para o OpenRouter com instruções de registro e orientação de gênero
  • llm-coached: O mesmo, mas com regras gramaticais, dicionário e notas de estilo injetados
  • google-translate: Requisição em lote para a Google Cloud Translation API v2
  • api: HTTP POST para um endpoint remoto

A mensagem do sistema (registro, orientação de gênero, regras) é idêntica em todos os lotes para uma determinada localidade, permitindo o cache de prompt — provedores como Anthropic e Google fazem cache de mensagens de sistema repetidas, reduzindo os custos de tokens.

6. Quality Gate​

Cada tradução é validada antes de ser gravada no disco. Cinco verificações são executadas:

VerificaçãoO que ela detectaExemplo
Vazio/em brancoO modelo não retornou nada""
Eco da origemO modelo retornou a entrada em inglês"Welcome" para japonês
Loop de alucinaçãoTrigramas repetidos"Qo' Qo' Qo' Qo'"
Inflação de tamanhoA saída é 4x+ maior que a origemOrigem de 10 caracteres → Saída de 50 caracteres
Conformidade de escritaSistema de escrita errado para a localidadeTexto latino para localidade árabe

As falhas são registradas com um prefixo [GATE]. Não há fallbacks silenciosos.

Consulte Quality Gate para mais detalhes.

7. Cascata de Retentativas​

Em caso de falha na análise (parse) do JSON ou erros no nível do lote, o rosetta tenta novamente com lotes progressivamente menores:

Full batch (30 keys) → Failed
Half batch (15 keys) → Failed
Individual keys (1 each) → Isolates the problem key

O orçamento de retentativas é limitado por maxRetries (padrão: 3) para evitar gastos descontrolados com tokens.

8. Gravação e Lock​

As traduções aprovadas são gravadas no arquivo de localidade de destino, preservando a estrutura de aninhamento original. O arquivo de lock é atualizado com os novos hashes SHA-256.

Sucesso Parcial​

Um lote com falha não bloqueia o restante. Se 9 de 10 lotes forem bem-sucedidos, esses 9 serão gravados. O lote que falhou é registrado no log, e você pode executar sync novamente para tentar de novo.

Dry Run​

Visualize o que mudaria sem gravar nenhum arquivo:

npx i18n-rosetta sync --dry

Forçar Retradução​

Force chaves específicas a serem retraduzidas, mesmo se inalteradas:

npx i18n-rosetta sync --force-keys "hero.title,nav.about"

Estimativa de Custos​

Antes de traduzir, o rosetta gera um relatório de custos pré-sync mostrando os custos estimados por par. Isso é executado automaticamente durante cada sync — você o vê antes que qualquer chamada de API seja feita.

╔══════════════════════════════════════════════════════════╗
║  Cost Estimate                                          ║
╠════════════╦═══════╦════════════╦════════════════════════╣
║ Pair       ║ Keys  ║ Est. Cost  ║ Method                 ║
╠════════════╬═══════╬════════════╬════════════════════════╣
║ en → fr    ║   142 ║ $0.07      ║ google-translate       ║
║ en → ja    ║    38 ║   —        ║ llm (model-dependent)  ║
║ en → crk   ║    38 ║   —        ║ llm-coached            ║
╚════════════╩═══════╩════════════╩════════════════════════╝

O Que é Estimado​

Cada método de tradução fornece sua própria estimativa de custo:

MétodoBase de CustoPrecisão
google-translateTaxa publicada pelo Google (US$ 20/milhão de caracteres)Precisa
llmVaria de acordo com o modelo no OpenRouterDepende do modelo — consulte os preços do OpenRouter
llm-coachedO mesmo que llm mais tokens de contexto de coachingDepende do modelo
apiDeterminado pelo servidorDesconhecida — não é possível estimar sem consultar o endpoint

Quando um método não consegue determinar o custo (métodos LLM, APIs remotas), o rosetta relata — em vez de adivinhar. Use --dry para ver as estimativas de custo sem realmente traduzir.

Veja Também​