Um tradutor comum trata um manual técnico como uma fila de frases. Esse é o erro central. Em um documento de desenvolvimento, comando-de-instalacao, códigos de status, nomes de funções, caminhos de arquivo e blocos inteiros de código não são texto natural. São peças que precisam continuar exatamente iguais.
Nesta matéria, vamos construir um fluxo de tradução técnica com três propriedades: ele identifica o que pode ser traduzido, protege o que não pode ser alterado e valida o resultado antes de devolver o documento. O resultado final será um arquivo Markdown traduzido, com comandos, códigos de erro, links e marcação preservados.
A ideia vale para outros formatos, mas começaremos pelo caso mínimo. Primeiro fazemos o pipeline funcionar. Depois acrescentamos glossário, validação semântica e suporte a documentos maiores.
O documento precisa virar uma árvore de peças
Antes de chamar um modelo de linguagem, separe o documento em unidades com papéis diferentes. Um parágrafo comum pode ser traduzido. Um bloco cercado por três crases não deve ser enviado para tradução. Um link precisa manter seu endereço, mesmo que o texto visível mude.
Essa separação é mais importante que o prompt. Se o modelo recebe código misturado com explicação, ele pode corrigir uma sintaxe, traduzir um nome de variável ou trocar um código de erro por uma expressão “mais natural”. A resposta parecerá boa para um leitor casual e estará errada para quem precisa executar o procedimento.
Para a primeira versão, usaremos quatro tipos de segmento:
- texto natural;
- bloco de código;
- linha de comando;
- marcador protegido, como URL, código de erro ou identificador técnico.
A estratégia é substituir cada trecho sensível por um marcador temporário, traduzir apenas o texto natural e restaurar os valores originais depois. O marcador funciona como uma etiqueta de bagagem: o modelo pode mover a frase ao redor, mas não deve abrir a mala.
A versão mínima começa com Markdown
Crie uma pasta com um arquivo chamado traduzir.py. O programa abaixo usa apenas a biblioteca padrão do Python e faz chamadas HTTP diretas à API da HiNow.
import json
import os
import re
import sys
import urllib.request
API_URL = "https://api.hinow.ai/v1/chat/completions"
MODELO = "hinow/himax"
PADRAO_CODIGO = re.compile(r"```.*?```", re.DOTALL)
PADRAO_COMANDO = re.compile(r"(?m)^\s{0,3}\$ .+$")
PADRAO_ERRO = re.compile(r"\b(?:HTTP|ERR|EAI|SQLSTATE)[-_ ]?[0-9A-Z_]+\b")
PADRAO_URL = re.compile(r"https?://[^\s)]+")
def proteger(texto):
protegidos = {}
def guardar(valor):
chave = f"__PROTEGIDO_{len(protegidos)}__"
protegidos[chave] = valor
return chave
texto = PADRAO_CODIGO.sub(lambda m: guardar(m.group(0)), texto)
texto = PADRAO_COMANDO.sub(lambda m: guardar(m.group(0)), texto)
texto = PADRAO_URL.sub(lambda m: guardar(m.group(0)), texto)
texto = PADRAO_ERRO.sub(lambda m: guardar(m.group(0)), texto)
return texto, protegidos
def traduzir(texto):
chave = os.environ["HINOW_API_KEY"]
payload = {
"model": MODELO,
"messages": [
{
"role": "system",
"content": (
"Traduza para português do Brasil. Preserve exatamente todos "
"os marcadores no formato __PROTEGIDO_N__. Não traduza nem "
"altere esses marcadores. Preserve a marcação Markdown."
)
},
{"role": "user", "content": texto}
]
}
dados = json.dumps(payload).encode("utf-8")
requisicao = urllib.request.Request(
API_URL,
data=dados,
headers={
"Authorization": f"Bearer {chave}",
"Content-Type": "application/json"
},
method="POST"
)
with urllib.request.urlopen(requisicao, timeout=120) as resposta:
corpo = json.loads(resposta.read().decode("utf-8"))
return corpo["choices"][0]["message"]["content"]
def restaurar(texto, protegidos):
for chave, valor in protegidos.items():
texto = texto.replace(chave, valor)
return texto
def main():
if len(sys.argv) != 3:
print("Uso: python traduzir.py entrada.md saida.md")
sys.exit(1)
with open(sys.argv[1], "r", encoding="utf-8") as arquivo:
original = arquivo.read()
protegido, mapa = proteger(original)
traduzido = traduzir(protegido)
resultado = restaurar(traduzido, mapa)
with open(sys.argv[2], "w", encoding="utf-8") as arquivo:
arquivo.write(resultado)
validar(original, resultado, mapa)
def validar(original, resultado, mapa):
faltantes = [chave for chave in mapa if chave not in resultado]
alterados = [
valor for valor in mapa.values()
if valor not in resultado
]
if faltantes or alterados:
raise RuntimeError(
f"Validação falhou: {len(faltantes)} marcadores ausentes e "
f"{len(alterados)} valores protegidos não encontrados."
)
print(f"Validação concluída: {len(mapa)} elementos protegidos.")
if __name__ == "__main__":
main()
O programa protege blocos de código antes das linhas de comando porque um comando pode estar dentro de um bloco. O padrão usado aqui é simples e serve para a primeira execução, não para qualquer Markdown possível. Documentos com HTML embutido, tabelas complexas ou blocos aninhados exigem um analisador específico.
A função traduzir envia somente o texto com marcadores. A função restaurar recoloca o conteúdo original. Já validar impede que o processo termine silenciosamente quando o modelo remove uma etiqueta.
Faça um teste que possa falhar
Crie entrada.md:
# Installing the service
Run the following command:
```bash
requisição-http https://dominio-de-exemplo.invalid/v1/items
If the request fails with HTTP 401, verify the token.
Execute:
```bash
export HINOW_API_KEY="sua-chave"
python traduzir.py entrada.md saida.md
O texto ao redor deve aparecer em português. O comando requisição-http, a URL e HTTP 401 precisam permanecer idênticos. A saída esperada no terminal é semelhante a:
Validação concluída: 3 elementos protegidos.
Esse número não é uma característica fixa do programa. Ele depende do conteúdo do arquivo. O teste importante é outro: compare cada valor protegido do original com o arquivo final. Se um único comando mudou, o documento não está pronto para distribuição.
O que a primeira versão ainda não entende
Regex reconhece padrões, não significado. Ela pode proteger HTTP 401, mas não sabe que “Unauthorized” é a descrição associada ao erro e talvez deva permanecer em inglês em uma tabela de referência. Também não distingue automaticamente uma palavra técnica que deve ser traduzida de um identificador que precisa ficar intacto.
A próxima melhoria é um glossário explícito. Antes da tradução, substitua termos controlados por marcadores adicionais. Por exemplo, se worker, endpoint e rollback precisam seguir uma convenção interna, crie um mapa de termos e valide a presença das traduções aprovadas depois da resposta.
Outra melhoria é dividir documentos longos em blocos. Suponha que cada chamada leve 300 ms para preparar e que cada rodada de inferência leve 2 segundos. Oito rodadas custam cerca de 18,4 segundos, sem contar transferência e reprocessamento. Um manual de 80 páginas pode exigir muitas chamadas, então agrupar parágrafos preservando os marcadores reduz espera e custo. Essa conta é uma estimativa ilustrativa baseada nas premissas apresentadas, não uma medição universal.
Quando a HiNow entra no fluxo
A API da HiNow é útil aqui porque o mesmo formato de chamada pode receber texto e, em uma etapa posterior, imagens de páginas. Para um PDF escaneado, o fluxo pode primeiro detectar texto e layout com leitura de imagem, depois aplicar a mesma proteção semântica.
O ponto decisivo é não pedir ao modelo que “preserve tudo” como uma promessa vaga. Preserve você mesmo o que é estrutural, envie ao modelo apenas o que ele deve reescrever e verifique o retorno com regras mecânicas. A inteligência interpreta linguagem; o programa protege invariantes.
Como expandir sem perder controle
Adicione validação de contagem para títulos, links, blocos de código e marcadores. Compare também a sequência dos comandos, não apenas sua existência. Em seguida, crie uma revisão humana para avisos de segurança, unidades de medida, passos numerados e termos que dependem do domínio.
Para PDFs com colunas, tabelas e imagens, extraia uma representação estruturada antes de traduzir. O objetivo não é produzir texto novo e tentar remontar o desenho depois. É manter cada elemento associado à sua posição e traduzir somente o conteúdo permitido.
Esse desenho tende a tornar o projeto mais verificável, mas deve ser validado no contexto do manual. A tradução deixa de ser uma operação única e passa a ser um pipeline com fronteiras claras: detectar, proteger, traduzir, restaurar e validar. Essa ordem transforma um modelo de linguagem de grande porte em uma peça de um sistema verificável, em vez de colocá-lo no papel impossível de cuidar sozinho da integridade do manual.
