TransForge : Traduisez un site statique avec un LLM local, uniquement les pages qui ont changé

Ce site est disponible en anglais ainsi que dans sept autres langues, et je n’ai jamais traduit une seule page manuellement. TransForge s’en charge : il s’agit d’un outil en ligne de commande qui envoie chaque page au format Markdown à un modèle hébergé sur mon propre serveur GPU, vérifie le résultat, puis crée page.ja.md à côté de page.md. Ce qui rend cet outil pratique, c’est sa gestion méticuleuse des données. Il conserve une empreinte numérique de chaque page source ainsi que de chaque traduction produite ; ainsi, une exécution nocturne ne traduit que les modifications apportées, et toute traduction corrigée manuellement ne sera jamais écrasée.

Résultat final

Une seule commande permet de connaître l’état des traductions pour chaque langue. Voici l’état de ce site le 19 octobre 2026 (43 pages en anglais, sept langues) :

$ 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

La commande status ne contacte jamais le serveur de modèles ; elle se contente de lire le site et son manifeste. Ensuite, transforge run --site laserlloyd traduit uniquement les sept pages manquantes. La colonne « edited » indique les pages dont la traduction a été modifiée manuellement après avoir été générée par TransForge ; elles restent inchangées tant que je ne le décide pas autrement.

L’outil traduit également du texte isolé, ce qui est utile pour tester rapidement un modèle :

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

Cette traduction a pris 15 secondes, le modèle étant déjà chargé sur le GPU.

Comment détermine-t-il ce qui doit être traduit ?

Pour chaque page source et chaque langue cible, TransForge conserve le hash de la version anglaise, celui de la traduction produite, ainsi que le hash des paramètres influençant le résultat (modèle utilisé, prompt, termes à conserver, température). La comparaison de ces données définit un état pour chaque combinaison page-langue :

État	Signification	run traduit-il ?
missing	Aucun fichier de traduction n’existe encore	Oui
stale	Le contenu anglais a changé depuis la dernière traduction	Oui
edited	Une modification manuelle a été apportée à la traduction	Non, sauf avec --force et --files
untracked	Il existe une traduction non générée par TransForge	Non ; accept permet de l’intégrer
drift	Contenu source et traduction inchangés, mais les paramètres du modèle ou du prompt ont varié	Non ; l’outil se contente d’en informer
current	Rien à faire	Non

Deux cas méritent une attention particulière. Une modification manuelle prime sur un changement source : si les deux se produisent, la page est classée comme « edited », ainsi aucune correction ne sera perdue lors d’une exécution automatique. De plus, le changement de modèle n’entraîne pas de traduction globale en arrière-plan ; on observe simplement un état « drift » afin de décider quelles pages méritent d’être retraduites.

Avant d’enregistrer une traduction, TransForge effectue plusieurs vérifications : nombre identique de titres, blocs de code, tableaux, images et liens par rapport à la source ; présence du script cible (ex. caractères japonais dans une page japonaise) ; absence de termes protégés modifiés de façon anormale ; longueur minimale du texte produit. En cas d’échec, la traduction précédente demeure intacte. Les liens internes sont ensuite réécrits par TransForge après l’exécution du modèle, jamais par celui-ci : /projects/foo/ devient /ja/projects/foo/ uniquement si la page japonaise existe déjà. Chaque fichier écrasé est d’abord copié dans un dossier de sauvegarde.

Installation et première utilisation

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=...        # uniquement si le serveur exige une clé
transforge config                         # affiche la configuration résolue ; ne montre pas la clé
transforge models                         # liste les modèles disponibles ; copiez-en un dans la config
transforge run --site example --dry-run   # simulation de la traduction
transforge run --site example --limit 2   # traduit deux pages, puis affiche le résultat

endpoint correspond au chemin racine du serveur sans /v1, tandis que model doit contenir l’identifiant complet indiqué par le serveur (les identifiants StudioForge ressemblent à publisher/repo/file-stem) ; un identifiant inconnu provoque une sortie avec le code 5 et les suggestions proches. no_translate liste les termes à conserver tels quels, et translate_fields définit les champs du frontmatter à traduire ; tous les autres sont copiés sans modification. Sur Debian et Ubuntu, il ne faut pas utiliser pip install . avec le Python système : cela est interdit (PEP 668). Privilégiez plutôt uv tool, pipx ou un environnement virtuel.

Si votre site possède déjà des traductions obtenues par d’autres moyens, exécutez une seule fois transforge accept --site example. Cela enregistre les fichiers existants comme « à jour », évitant ainsi toute nouvelle traduction.

Les codes de sortie servent aux scripts et aux tâches planifiées : 0 signifie que tout est fait ou qu’il n’y a rien à faire ; 1 indique un échec sur une page (et, via status, qu’une action reste en suspens) ; 2 correspond à une erreur de configuration ou à un rejet de la clé API par le serveur ; 4 signifie que le serveur est injoignable ; 5 indique qu’aucun modèle n’est disponible sur le serveur ; 6 signifie qu’un benchmark occupe le GPU, retardant ainsi les tâches.

Docker

Le dépôt propose également une configuration Compose permettant d’utiliser TransForge en tant qu’outil sur votre dossier de site, avec les manifestes stockés dans un volume et un service planificateur optionnel :

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

Aucun port n’est ouvert. À l’intérieur du conteneur, localhost désigne le conteneur lui-même ; le serveur de modèles doit donc écouter sur une adresse accessible depuis ce dernier. J’utilise TransForge en mode natif et ne me suis pas encore servi du conteneur ; le fichier docs/deploy/docker.md du dépôt fournit tous les détails, y compris la gestion des sauvegardes.

Nouveautés de la version 0.2.0

La version 0.2.0 (octobre 2026) vise principalement à fonctionner avec un serveur StudioForge 2.0, lequel exige une clé API :

• Prise en charge des clés API. TransForge ajoute Authorization: Bearer dans chaque requête envoyée au serveur. La clé est lue via TRANSFORGE_LLM_API_KEY (ou STUDIOFORGE_API_KEY, ou une variable nommée api_key_env) ; la rotation de cette clé ne marque aucune page comme obsolète. Sans clé, un serveur exigeant celle-ci renvoie un message succinct et renvoie le code 2 (détails ci-dessous).
• Gestion sécurisée des benchmarks. Avant toute traduction, TransForge vérifie si un benchmark occupe le GPU et s’en abstient en cas de présence. Autrefois, une vérification infructueuse était interprétée comme « aucune tâche en cours » et désactivait cette protection ; dorénavant, l’outil renvoie le code 2.
• Compatibilité Windows. Les manifestes utilisent désormais / sur tous les systèmes, facilitant ainsi le partage entre Windows, Linux et conteneurs. Les anciens manifestes Windows sont automatiquement mis à jour lors de leur lecture. Ne lancez pas accept --all pour « reconstruire » quoi que ce soit : cela classerait à tort des traductions encore valides comme obsolètes.
• Dépréciation du code PIN. Le chargement et le déchargement des modèles utilisent désormais la clé API ; le code PIN reste utilisable pour une dernière version, mais affiche alors un avertissement s’il constitue le seul moyen d’authentification.

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)

Mise à jour : utilisez uv tool install --reinstall --python 3.13 git+https://github.com/LaserLloyd/TransForge, puis définissez TRANSFORGE_LLM_API_KEY si votre serveur impose l’utilisation de clés.

Points de vigilance

• Relisez les premières traductions. Les vérifications effectuées permettent d’éviter les erreurs structurelles, mais pas les fautes de sens. J’emploie un modèle dédié à la traduction, Hy-MT2 30B, avec prompt_template = "hunyuan-mt" (le prompt court attendu par les modèles de traduction purs) ; un modèle d’instruction général fonctionne également avec le template par défaut. Quoi qu’il en soit, tout contenu important mérite une relecture humaine.
• Une traduction modifiée manuellement reste inchangée. C’est là l’objectif même de l’outil, mais cela signifie aussi qu’une correction apportée à la version anglaise ne se propagera pas dans cette langue. La commande status -v en liste les exemples ; run --force --files <page> permet de retraduire volontairement une page.
• Le changement de modèle n’entraîne aucune retraduction. On observe simplement un état « drift » pour chaque page. Pour retraduire les pages concernées, il faut utiliser --force --files.
• Conçu spécifiquement pour StudioForge. Le préchargement du modèle (avec gestion des slots parallèles) ainsi que la vérification des benchmarks communiquent via l’API propre à StudioForge. Le README indique qu’un serveur llama.cpp peut aussi servir à la traduction ; personnellement, je ne l’ai testé qu’avec StudioForge.
• Pas de récursivité. Les dossiers listés dans content_dirs ne sont scannés qu’à un seul niveau. Il faut donc énumérer chaque répertoire contenant des pages.
• Une page devant rester en anglais doit porter l’option en_only: true (ou translate: false) dans son frontmatter ; elle sera alors totalement ignorée par TransForge.

Où le trouver ?

github.com/LaserLloyd/TransForge, sous licence MIT. Le README propose des instructions d’installation pour Windows, Linux et macOS, la référence complète de configuration, ainsi qu’une étape optionnelle de relecture par un modèle hébergé (désactivée par défaut ; la traduction elle-même se fait toujours en local).

Voir aussi : StudioForge (le serveur GPU sur lequel tourne le modèle), gestion de mes sites web grâce à un agent IA local, et comment faire en sorte qu’un modèle IA adapte n’importe quel projet à votre système.