TransForge: Traduza um site estático com um LLM local – apenas as páginas que foram alteradas

Este site está disponível em inglês e mais sete idiomas; nunca traduzi uma página manualmente. O TransForge faz isso: é uma ferramenta de linha de comando que envia cada página em Markdown para um modelo rodando no meu próprio servidor GPU, verifica o resultado e cria o arquivo page.ja.md ao lado de page.md. O que torna esse processo viável é o sistema de controle de versões: ele mantém um registro de cada página original e de cada tradução gerada, de modo que uma execução noturna traduz apenas o que mudou; além disso, uma tradução editada manualmente nunca é sobrescrita.

O que você obtém ao final

Um único comando informa o status de todas as traduções. Este é o estado deste site em 19/10/2026 (43 páginas em inglês, sete idiomas):

$ transforge status --site laserlloyd
site laserlloyd: 43 source pages x 7 languages | model mradermacher/Hy-MT2-30B-A3B-i1-GGUF/Hy-MT2-30B-A3B.i1-Q4_K_S
  lang     missing     stale    edited untracked     drift   current
  ja             1         0        10         0         0        32
  zh             1         0         8         0         0        34
  ...
  -> 7 sibling(s) need translation

O comando status não se conecta ao servidor de modelos; ele apenas lê o site e os registros existentes. Já o comando transforge run --site laserlloyd traduz apenas as sete páginas que ainda não têm tradução. A coluna “edited” indica páginas cuja tradução foi alterada manualmente após a geração automática; essas permanecem inalteradas até que eu decida o contrário.

Também é possível traduzir textos isolados, o que é útil para testar rapidamente um modelo:

$ echo "Only the pages that changed get translated again." | transforge text --to ja
変更されたページのみ、再翻訳されます。

Isso levou 15 segundos, considerando que o modelo já estava carregado no GPU.

Como ele decide o que traduzir

Para cada página original e idioma, o TransForge armazena o hash do conteúdo em inglês, o hash da tradução gerada e o hash das configurações usadas (modelo, prompt, termos a manter, temperatura). A comparação desses valores define o estado de cada página/idioma:

Estado	Significado	O run traduz?
missing	ainda não há arquivo de tradução	sim
stale	o conteúdo original mudou desde a última tradução	sim
edited	alguém editou a tradução manualmente	não, só com --force e --files
untracked	existe uma tradução que o TransForge não gerou	não; use accept para adotá-la
drift	conteúdo original e tradução permanecem iguais, mas as configurações do modelo/prompt mudaram	não; apenas informa ao usuário
current	nada a fazer	não

Dois desses estados são especialmente importantes: uma edição manual tem prioridade sobre alterações no conteúdo original; portanto, se ambos ocorrerem, a página é marcada como “edited” e a correção manual nunca é perdida. Mudar o modelo também não força a retradução de todo o site automaticamente; em vez disso, o sistema sinaliza “drift”, permitindo que você decida quais páginas merecem nova tradução.

Antes de salvar uma tradução, são feitas verificações: número igual de títulos, blocos de código, tabelas, imagens e links em relação ao original; presença do script de idioma correto (por exemplo, caracteres japoneses em uma página japonesa); ausência de termos protegidos alterados indevidamente; e comprimento mínimo do texto. Caso alguma verificação falhe, a tradução anterior permanece intacta. Os links internos são reescritos pelo TransForge após a geração da tradução, nunca pelo modelo: /projects/foo/ vira /ja/projects/foo/ somente se a página japonesa já existir. Qualquer arquivo sobrescrito é copiado primeiro para uma pasta de backup.

Instalação e primeira execução

uv tool install --python 3.13 git+https://github.com/LaserLloyd/TransForge
mkdir -p ~/.config/transforge
cat > ~/.config/transforge/config.toml <<'EOF'
[defaults]
endpoint = "http://localhost:1234"
model = "publisher/repo/file-stem"

[sites.example]
root = "~/sites/example"
content_dirs = ["content/projects", "content/pages"]
languages = ["ja", "de"]
lang_names = { ja = "Japanese", de = "German" }
link_dirs = ["projects"]
no_translate = ["MyProduct"]
translate_fields = ["title", "excerpt"]
EOF
export TRANSFORGE_LLM_API_KEY=...        # só se o servidor exigir uma chave
transforge config                         # exibe a configuração resolvida; nunca mostra a chave
transforge models                         # lista os modelos disponíveis; copie o ID completo para a configuração
transforge run --site example --dry-run   # simula quais páginas seriam traduzidas
transforge run --site example --limit 2   # traduz duas páginas e exibe o resultado

O parâmetro endpoint deve conter a raiz do servidor, sem /v1; o model deve ser o ID completo listado pelo servidor (os IDs do StudioForge têm formato publisher/repo/file-stem; um ID desconhecido gera erro com código 5 e sugere os IDs mais próximos). A opção no_translate lista termos que devem permanecer inalterados, enquanto translate_fields define quais chaves do frontmatter serão traduzidas; todas as demais são copiadas sem alterações. Em Debian e Ubuntu, não utilize pip install . com o Python do sistema: isso é bloqueado pela norma PEP 668. As opções uv tool, pipx ou ambientes virtuais funcionam perfeitamente.

Se seu site já possui traduções feitas por outro método, execute transforge accept --site example uma única vez; isso registra os arquivos existentes como “current”, evitando novas traduções.

Os códigos de saída são úteis para scripts e agendamentos: 0 indica conclusão ou ausência de tarefas; 1 significa falha em alguma página (e, segundo status, ainda há trabalho pendente); 2 aponta erro de configuração ou recusa do servidor quanto à chave API; 4 indica que o servidor está inacessível; 5 o modelo solicitado não está disponível no servidor; 6 um benchmark está ocupando o GPU, adiando as tarefas.

Docker

O repositório também oferece uma configuração Compose que executa o TransForge como ferramenta de tradução para seu site; os registros ficam num volume e há opcionalmente um serviço agendador:

git clone https://github.com/LaserLloyd/TransForge.git && cd TransForge
cp deploy/compose/.env.example deploy/compose/.env    # defina LLM_BASE_URL e TRANSFORGE_LLM_API_KEY
docker compose -f deploy/compose/compose.yml run --rm app status --all

Nenhum porta é aberta. Dentro do contêiner, “localhost” refere-se ao próprio contêiner; portanto, o servidor de modelos deve escutar num endereço acessível a ele. Eu uso o TransForge nativamente e nunca testei o contêiner; o arquivo docs/deploy/docker.md traz detalhes, incluindo como fazer backups.

Novidades na versão 0.2.0

O lançamento 0.2.0 (outubro de 2026) foca principalmente na compatibilidade com servidores StudioForge 2.0, que exigem chave API:

• Suporte a chaves API. O TransForge envia o cabeçalho Authorization: Bearer em todas as requisições. A chave é lida a partir de TRANSFORGE_LLM_API_KEY (ou STUDIOFORGE_API_KEY, ou outra variável definida via api_key_env); a rotação da chave não marca nenhuma página como “stale”. Sem chave, servidores que a exigem respondem com mensagem simples e código de erro 2 (descrito abaixo).
• Proteção segura contra benchmarks. Antes de traduzir, o TransForge verifica se algum benchmark está utilizando o GPU; caso positivo, aborta a tarefa. Anteriormente, uma falha na verificação era interpretada como “nada rodando”, desativando essa proteção; agora gera erro 2.
• Compatibilidade com Windows. Os manifestos usam sempre / independentemente do sistema operacional, permitindo transferência entre Windows, Linux e contêineres. Manifestos antigos no Windows são reconfigurados automaticamente ao serem lidos. Não execute accept --all para “reconstruir” tudo: isso marcaria traduções desatualizadas como “current”.
• O PIN de gerenciamento antigo está obsoleto. O carregamento e descarregamento de modelos agora usam a chave API; o PIN ainda funciona por mais uma versão, exibindo aviso quando for o único método de autenticação.

rig returned HTTP 401 Unauthorized for http://<server>:1234/api/status -- StudioForge requires credentials: set $TRANSFORGE_LLM_API_KEY (or `api_key_env` / `api_key` in the config)

Atualização: execute uv tool install --reinstall --python 3.13 git+https://github.com/LaserLloyd/TransForge e defina TRANSFORGE_LLM_API_KEY se seu servidor exigir chaves.

Pontos de atenção

• Revise as primeiras traduções. As verificações garantem estrutura correta, mas não detectam erros de sentido. Eu uso um modelo de tradução dedicado, o Hy-MT2 30B, com prompt_template = "hunyuan-mt" (o prompt curto esperado por modelos puros de tradução); modelos genéricos de instrução funcionam com o template padrão. Em qualquer caso, conteúdos importantes merecem revisão humana.
• Traduções editadas permanecem congeladas. É exatamente esse o propósito; porém, uma correção no conteúdo original não afetará essas páginas. O comando status -v as lista; use run --force --files <page> para traduzi-las novamente.
• Mudar de modelo não retraduz nada. O sistema sinaliza “drift” em todas as páginas; para atualizá-las, use --force --files.
• Desenvolvido para StudioForge. O pré-carregamento do modelo e a verificação de benchmarks dependem da API própria do StudioForge. O README afirma que servidores llama.cpp também funcionam; porém, só testei com o StudioForge.
• Não é recursivo. Os diretórios listados em content_dirs são escaneados apenas num nível; inclua cada pasta que contenha páginas.
• Páginas que devem permanecer em inglês devem ter en_only: true (ou translate: false) no frontmatter; elas são totalmente ignoradas.

Obtenha o TransForge

github.com/LaserLloyd/TransForge, licenciado sob MIT. O README traz instruções de instalação para Windows, Linux e macOS, a referência completa de configuração e um estágio opcional de revisão por segundo modelo; essa etapa só é ativada mediante solicitação, enquanto a tradução em si ocorre sempre localmente.

Relacionado: StudioForge (o servidor GPU onde os modelos rodam), gerenciando meus sites com uma caixa de agentes IA local e como fazer um LLM adaptar qualquer projeto ao seu sistema.