---
tags:
  - translation
  - nllb
  - nllb-200
  - seq2seq
  - game-localization
  - renpy
  - RenExtract
  - transformers
license: cc-by-nc-4.0
pipeline_tag: translation
library_name: transformers
base_model: facebook/nllb-200-distilled-600M
language:
  - en
  - fr
inference: false
---

# **virusf/nllb-renpy-rory-v6 — 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 [`RenExtract`](https://github.com/Rory-Mercury-91/RenExtract) ainsi que par Ren'Py Translator (NLLB) de [`TranslationToolsIA`](https://github.com/Virusf/TranslationToolsIA).

> 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`](https://huggingface.co/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)

---

## 🔧 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
- **≈ 12 000** paires **traduction humaine** (VN/jeux narratifs : tutoriels, UI, dialogues)
- **+** paires **dialogues adultes 18+**
- **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  

### 🔄 Par rapport à [`virusf/nllb-renpy-rory-v4`](https://huggingface.co/virusf/nllb-renpy-rory-v4)
- Ajout de **nouveaux dialogues narratifs** (issus de VN récents) pour enrichir la couverture  
- Amélioration du **pré-traitement** via `rory_tool` (meilleure gestion des balises/variables) 

---

## 🏗️ Détails d'entraînement
- **Script** : `00_finetune_nllb.py`
- **Base** : `facebook/nllb-200-distilled-600M`
- **Direction** : `eng_Latn → fra_Latn`
- **Epochs** : 3
- **Batch** : 4 (avec `gradient_accumulation_steps=4`)
- **LR** : 3e-5 ; **weight_decay** : 0.01 ; **warmup_ratio** : 0.03 ; **scheduler** : cosine ; **max_grad_norm** : 1.0
- **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=True` ; **gradient checkpointing** ON ; `use_cache=False`
- **Sauvegardes** : `save_steps=400`, `save_total_limit=3`, `overwrite_output_dir=True`
- **Eval** : `evaluation_strategy="steps"`, `eval_steps=400`, `metric_for_best_model=eval_loss`, `load_best_model_at_end=True`

**Format des données attendu par le script** :
- **TSV** (sans header) : chaque ligne = `source	target`

---

## 🚀 Utilisation (🤗 Transformers)

### Exemple minimal (préserve les balises encodées)
```python
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

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

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`
```python
from transformers import pipeline
translator = pipeline(
    task="translation",
    model="virusf/nllb-renpy-rory-v5",
    tokenizer="virusf/nllb-renpy-rory-v5",
)
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_v5,
  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-v5}
}
```

---