nllb-renpy-rory-v3

virusf/nllb-renpy-rory-v3 — NLLB-200-distilled-600M fine‑tuné pour dialogues Ren'Py

Résumé. Modèle de traduction eng_Latn → fra_Latn spécialisé pour les dialogues Ren'Py. Il préserve les balises/variables (p. ex. {color=#f00}, {size=30}, [player_name]) via l'encodage fourni par le nouvel extractor de rory_tool (version à venir).

Objectif : obtenir des traductions naturelles in‑game tout en gardant intacte la mise en forme Ren'Py.

---

🧠 Modèle d'origine

• Base : facebook/nllb-200-distilled-600M
• Archi : M2M100 (Seq2Seq)
• Lib : 🤗 Transformers

---

🗣️ Langues

• Source : eng_Latn (anglais — script latin)
• Cible : fra_Latn (français — script latin)

---

📦 Contenu du repo

• Poids du modèle fine‑tuné
• Tokenizer NLLB‑200 (mêmes codes de langue)
• Exemples d'inférence (ci‑dessous)

Le dataset d'entraînement n'est pas redistribué.

---

🔧 Cas d'usage ciblés

• Localisation de jeux Ren'Py (extraction → traduction → ré‑injection)
• Répliques courtes, menus, choix, messages système
• Préservation stricte des balises/variables Ren'Py

Moins adapté : textes longs hors jeu, entrées sans encodage rory_tool.

---

📊 Données & Pré‑traitement

• ≈ 17 000 paires traduction humaine (VN/jeux narratifs : tutoriels, UI, dialogues)
• Extraction : nouvelle version de rory_tool — encodage/masquage des balises et variables pour empêcher leur altération
• Nettoyage : dé‑duplication, normalisation Unicode, trimming ponctuation, filtrage des outliers de longueur
• Split : train/valid ≈ 95/5

Pour reproduire l'inférence, utilisez le même encodage de rory_tool côté prédiction.

---

🏗️ Détails d'entraînement

• Script : 00_finetune_nllb.py
• Base : facebook/nllb-200-distilled-600M
• Direction : eng_Latn → fra_Latn
• Epochs : 3
• Batch : 8 (avec gradient_accumulation_steps=4)
• LR : 2e‑5 ; weight_decay : 0.01 ; warmup_ratio : 0.03 ; scheduler : linear
• Label smoothing : 0.1
• Tokenisation : max_length=256, pad_to_multiple_of=8
• Génération (éval) : generation_max_length=128, num_beams=1, predict_with_generate=True
• Précision & perf : bf16=True, fp16=False, TF32 activé ; gradient checkpointing ON ; use_cache=False
• Sauvegardes : save_steps=300, save_total_limit=3, overwrite_output_dir=True
• Eval : evaluation_strategy="steps", eval_steps=save_steps, metric_for_best_model=eval_loss

Format des données attendu par le script :

• TSV (sans header) : chaque ligne = source target
• ou JSONL : objets avec clés src/tgt ou source/target

---

🚀 Utilisation (🤗 Transformers)

Exemple minimal (préserve les balises encodées)

from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

model_id = "virusf/nllb-renpy-rory-v3"

source = "eng_Latn"
cible  = "fra_Latn"
text = "{color=#f00}Hello{/color}, [player_name]!"

# 1) Charger
_tok = AutoTokenizer.from_pretrained(model_id)
_mod = AutoModelForSeq2SeqLM.from_pretrained(model_id)

# 2) Fixer la langue source et forcer le BOS cible
_tok.src_lang = source
inputs = _tok(text, return_tensors="pt")

gen = _mod.generate(
    **inputs,
    forced_bos_token_id=_tok.convert_tokens_to_ids(cible),
    max_new_tokens=128,
)
print(_tok.batch_decode(gen, skip_special_tokens=True)[0])

Avec pipeline

from transformers import pipeline
translator = pipeline(
    task="translation",
    model="virusf/nllb-renpy-rory-v3",
    tokenizer="virusf/nllb-renpy-rory-v3",
)
translator.tokenizer.src_lang = "eng_Latn"
print(translator("{size=30}Start{/size}"))

Bonnes pratiques Ren'Py

1. Toujours passer par rory_tool pour encoder/décoder balises & variables
2. Éviter toute post‑édition qui casserait les jetons de balise
3. Sur UI sensibles, vérifier la longueur et les lignes mono‑caractère

---

⚠️ Limites

• Entrées sans encodage rory_tool : risque d'altération de balises
• Contexte long : segmenter par réplique ; relire les jeux de mots/humour

---

📥 Intégration avec rory_tool

• Extraction → Encodage (balises/variables protégées) → Traduction (ce modèle) → Décodage → Ré‑injection .rpy
• Compatible avec la nouvelle version de l'extractor (à venir)

---

📝 Licence

• CC-BY-NC-4.0

---

📚 Citation

@software{nllb_renpy_rory_v3,
  title  = {NLLB-200-distilled-600M fine-tuné pour Ren'Py avec balises protégées via rory_tool},
  author = {virusf},
  year   = {2025},
  url    = {https://huggingface.co/virusf/nllb-renpy-rory-v3}
}

---