TransForge: Traducir un sitio estático con un LLM local, solo las páginas que hayan cambiado

Este sitio está disponible en inglés y otros siete idiomas; nunca he traducido ninguna página a mano. TransForge se encarga de ello: es una herramienta de línea de comandos que envía cada página en formato Markdown a un modelo en mi propio servidor GPU, verifica el resultado y crea page.ja.md junto a page.md. Lo que hace posible todo esto es su sistema de seguimiento: guarda una “huella” de cada página original y de cada traducción generada, de modo que al ejecutarse cada noche solo se traducen los cambios; además, las correcciones hechas manualmente nunca se sobrescriben.

Resultado final

Un único comando muestra el estado de cada idioma en el sitio. Este es el estado de este sitio el 19 de octubre de 2026 (43 páginas en inglés, siete 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

El comando status no contacta al servidor de modelos; simplemente lee el sitio y el manifiesto. Luego, transforge run --site laserlloyd traduce únicamente las siete páginas que faltaban. La columna “edited” indica páginas cuya traducción fue modificada manualmente después de ser generada por TransForge; esas permanecen tal cual hasta que yo decida lo contrario.

También puede traducir texto suelto, lo cual resulta útil para probar un modelo de forma puntual:

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

Esto tardó 15 segundos, ya que el modelo estaba previamente cargado en el servidor GPU.

Cómo decide qué traducir

Para cada página original y cada idioma de destino, TransForge guarda el hash del contenido en inglés, el hash de la traducción generada y el hash de los parámetros que configuran el proceso (modelo, prompt, términos a conservar, temperatura). La comparación de estos valores determina el estado de cada página:

Estado	Significado	¿run lo traduce?
missing	no existe archivo de traducción	sí
stale	el contenido original cambió desde la última traducción	sí
edited	alguien modificó la traducción manualmente	no, salvo con --force y --files
untracked	hay una traducción que TransForge no generó	no; accept la adopta
drift	el contenido original y la traducción permanecen iguales, pero cambiaron los parámetros del modelo o prompt	no; solo se informa
current	no hay nada que hacer	no

Dos de estos estados son especialmente importantes: una edición manual prevalece sobre cualquier cambio en el contenido original; si ambos ocurren, la página queda marcada como “edited”, evitando así que las correcciones se pierdan. Asimismo, cambiar el modelo no provoca la re-traducción automática de todo el sitio; en su lugar, aparece el estado “drift” y usted decide qué páginas merecen ser procesadas de nuevo.

Antes de escribir una traducción, se realizan varias comprobaciones: debe haber el mismo número de títulos, bloques de código, tablas, figuras, imágenes y enlaces que en la versión original; el idioma objetivo debe estar correctamente representado (por ejemplo, caracteres japoneses en una página en japonés); no pueden aparecer términos protegidos inventados por el modelo, y debe cumplirse un mínimo de longitud. Si alguna comprobación falla, la traducción anterior se mantiene intacta. Los enlaces internos son reescritos por TransForge tras la generación de la traducción; nunca lo hace el modelo: /projects/foo/ pasa a ser /ja/projects/foo/ únicamente si ya existe la página en japonés. Cualquier archivo sobrescrito se copia primero a una carpeta de respaldo.

Instalación y primer uso

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=...        # solo si el servidor exige una clave
transforge config                         # muestra la configuración resuelta; nunca revela la clave
transforge models                         # lista los modelos disponibles; copie el identificador completo al config
transforge run --site example --dry-run   # simula qué páginas se traducirían
transforge run --site example --limit 2   # traduce dos páginas y luego las muestra

endpoint debe ser la raíz del servidor sin incluir /v1; model requiere el identificador completo que el servidor ofrece (los identificadores de StudioForge tienen formato publisher/repo/file-stem; si el modelo no se encuentra, el programa devuelve código 5 y sugiere opciones cercanas). no_translate contiene términos que deben permanecer sin cambios; translate_fields especifica las claves del frontmatter que deben traducirse; todas las demás se copian tal cual. En Debian y Ubuntu, no utilice pip install . con el intérprete Python del sistema: está prohibido por PEP 668. Se recomienda usar uv tool, pipx o un entorno virtual.

Si su sitio ya cuenta con traducciones realizadas por otros medios, ejecute transforge accept --site example una sola vez; esto registrará esos archivos como “current” y evitará que se vuelvan a traducir.

Los códigos de salida están pensados para scripts y tareas programadas: 0 significa éxito o que no hay nada por hacer; 1 indica fallo en alguna página (y, según status, aún quedan tareas pendientes); 2 señala error de configuración o rechazo de la clave API por el servidor; 4 indica que el servidor no está accesible; 5 significa que el modelo solicitado no se encuentra en el servidor; 6 aparece cuando una prueba de rendimiento ocupa el GPU y las tareas se han pospuesto.

Docker

El repositorio incluye también una configuración Compose que ejecuta TransForge como herramienta sobre su carpeta de sitio; los manifiestos se almacenan en un volumen y existe un servicio programador opcional:

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

Este contenedor no abre ningún puerto. Dentro del mismo, localhost hace referencia al propio contenedor; por ello, el servidor de modelos debe escuchar en una dirección a la que el contenedor pueda acceder. Yo ejecuto TransForge de forma nativa y no he usado el contenedor personalmente; los detalles, incluyendo copias de seguridad, se describen en docs/deploy/docker.md del repositorio.

Novedades en la versión 0.2.0

El lanzamiento 0.2.0 (octubre de 2026) se centra principalmente en la compatibilidad con servidores StudioForge 2.0, que requieren una clave API:

• Soporte para claves API. TransForge incluye el encabezado Authorization: Bearer en cada solicitud al servidor. La clave se obtiene de TRANSFORGE_LLM_API_KEY (o STUDIOFORGE_API_KEY, o cualquier variable definida mediante api_key_env). El cambio de clave no marca ninguna página como “stale”. Si el servidor exige una clave y esta no se proporciona, TransForge responde con un mensaje breve y devuelve código 2.
• Protección ante pruebas de rendimiento. Antes de iniciar la traducción, TransForge verifica si alguna prueba de rendimiento está utilizando el GPU; en ese caso, aborta la operación. Anteriormente, un fallo al comprobar esa reserva se interpretaba erróneamente como “no hay procesos activos”, desactivando la protección; ahora se detiene con código 2.
• Compatibilidad con Windows. Los manifiestos usan siempre la barra /, independientemente del sistema operativo, de modo que pueden moverse entre Windows, Linux o el contenedor. Los manifiestos antiguos de Windows se reconfiguran automáticamente al leerse. No ejecute accept --all para “reconstruir” nada: eso marcaría como “current” traducciones que en realidad están desactualizadas.
• El PIN de gestión queda obsoleto. La carga y descarga de modelos ahora se gestionan mediante la clave API; el PIN seguirá funcionando durante una versión más, pero mostrará una advertencia si es el único método de autenticación disponible.

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)

Para actualizar: ejecute uv tool install --reinstall --python 3.13 git+https://github.com/LaserLloyd/TransForge y, si su servidor exige claves, defina TRANSFORGE_LLM_API_KEY.

Consideraciones importantes

• Revise usted mismo las primeras traducciones. Las comprobaciones automáticas detectan errores estructurales, pero no errores de significado. Yo utilizo un modelo de traducción especializado, Hy-MT2 30B, con prompt_template = "hunyuan-mt" (el prompt corto que esperan los modelos puros de traducción); un modelo genérico de instrucciones funciona con la plantilla predeterminada. En cualquier caso, todo contenido relevante merece una revisión humana.
• Las traducciones editadas permanecen fijas hasta que usted decida. Ese es el propósito del sistema; sin embargo, implica que las correcciones al contenido original no se propagarán a esos idiomas. El comando status -v enumera dichas páginas; run --force --files <page> permite traducir una en particular si así lo desea.
• Cambiar el modelo no re-traduce nada. En su lugar, aparece el estado “drift” para todas las páginas. Para corregirlo, utilice --force --files sobre las páginas que requieran atención.
• Diseñado para StudioForge. El proceso de calentamiento (carga del modelo con suficientes slots paralelos) y la comprobación de pruebas de rendimiento se realizan mediante la API propia de StudioForge. En el README se afirma que un servidor llama.cpp también sirve para traducciones; sin embargo, yo solo lo he probado con StudioForge.
• No es recursivo. El parámetro content_dirs solo escanea un nivel de profundidad; por ello, debe listar cada carpeta que contenga páginas.
• Para páginas que deben permanecer en inglés, añada en_only: true (o translate: false) al frontmatter; esas páginas se omitirán por completo.

Descarga

github.com/LaserLloyd/TransForge, bajo licencia MIT. El README incluye instrucciones de instalación para Windows, Linux y macOS, la referencia completa de configuración y una fase opcional de revisión secundaria que puede emplear un modelo alojado (desactivada por defecto; la traducción siempre se realiza localmente).

Relacionado: StudioForge (el servidor GPU donde se ejecutan los modelos), gestión de mis sitios mediante un cuadro local de IA, y cómo hacer que una IA adapte cualquier proyecto a su sistema.