Localisation

Loreline intègre nativement la traduction de vos scripts en plusieurs langues.

Comment ça marche

La localisation dans Loreline suit trois étapes :

1. Annoter le texte traduisible avec des commentaires #key dans votre script.
2. Créer un fichier de traduction (.lang.lor) pour chaque langue cible.
3. Charger le fichier de traduction à l'exécution et le passer à l'interpréteur.

L'interpréteur cherche chaque #key à l'exécution et remplace le texte original par sa traduction. Si une clé n'a pas de traduction, le texte original est utilisé par défaut.

Annoter le texte pour la traduction

Pas besoin d'ajouter ces clés à la main : le CLI peut les générer automatiquement. Voir Utiliser le CLI ci-dessous.

Pour marquer du texte comme traduisible, ajoutez un commentaire #key après l'élément concerné. Trois types de contenu peuvent être annotés :

Les textes narratifs :

"Le café sent très bon." #intro

Les dialogues :

barista: "Bienvenue ! Qu'est-ce que je te sers ?" #welcome

Les options de choix :

choice
  Expresso #opt-espresso
  Latté #opt-latte

Les clés peuvent contenir des lettres, chiffres, tirets et underscores, par exemple #intro, #opt-espresso ou #chapitre2_salut.

Caractères dièse littéraux

Si vous avez besoin d'un # littéral dans votre texte, utilisez ## (doublé) ou \# (échappé) :

Ce texte contient un ##hashtag littéral.
barista: "Utilisez \#échappé pour un dièse littéral."

Exemple complet

Voici un script complet avec des clés de localisation :

character barista
  name: Alex

beat Menu
  "The cafe smells wonderful." #intro
  barista: "Welcome! What can I get you?" #welcome
  choice
    Espresso #opt-espresso
      barista: One espresso! #espresso-reply
    Latte #opt-latte
      barista: One latte! #latte-reply

La lisibilité vous inquiète ? Dans l'extension VS Code, appuyez sur Cmd+Shift+H (Mac) ou Ctrl+Shift+H (Windows/Linux), ou via la palette de commandes, pour masquer toutes les clés de localisation afin qu'elles ne nuisent en aucun cas à la lisibilité de votre script. L'Atelier sur ce site propose aussi cette option.

Les fichiers de traduction

Les fichiers de traduction suivent la convention de nommage Fichier.lang.lor, par exemple CoffeeShop.fr.lor pour le français ou CoffeeShop.de.lor pour l'allemand.

Chaque entrée dans un fichier de traduction se compose de :

• Une #key suivie de // et du texte original en référence
• Le texte traduit sur la ligne suivante

Voici la traduction française de l'exemple précédent (CoffeeShop.fr.lor) :

#intro // "The cafe smells wonderful."
Le café sent très bon.

#welcome // "Welcome! What can I get you?"
Bienvenue ! Qu'est-ce que je te sers ?

#opt-espresso // Espresso
Expresso

#espresso-reply // One espresso!
Un expresso !

#opt-latte // Latte
Latté

#latte-reply // One latte!
Un latté

Le commentaire // sur chaque ligne de clé est purement indicatif. L'interpréteur l'ignore. Les traducteurs peuvent voir le texte original sans avoir à ouvrir le fichier source.

Utiliser le CLI

La commande loreline translate automatise le processus de localisation. Elle peut générer des clés, créer des fichiers de traduction et nettoyer le tout.

Générer des clés automatiquement

Si votre script n'a pas encore de clés #key, le CLI peut les ajouter automatiquement :

loreline translate CoffeeShop.lor --auto-ids

Cette commande parcourt tous les textes, dialogues et options de choix du script et insère des clés aléatoires (comme #a7k2m) sur chaque ligne qui n'en a pas encore. Vos commentaires et votre mise en forme sont préservés.

Générer un fichier de traduction

Pour créer ou mettre à jour un fichier de traduction pour une langue donnée :

loreline translate CoffeeShop.lor --lang fr

Cela crée CoffeeShop.fr.lor avec toutes les entrées traduisibles. Si le fichier existe déjà, les traductions existantes sont conservées et les nouvelles entrées sont ajoutées.

Supprimer les clés

Pour retirer tous les commentaires #key d'un fichier source :

loreline translate CoffeeShop.lor --clear

Workflow type

# 1. Ajouter des clés au script
loreline translate CoffeeShop.lor --auto-ids

# 2. Générer un fichier de traduction français
loreline translate CoffeeShop.lor --lang fr

# 3. Éditer CoffeeShop.fr.lor, remplacer chaque placeholder par le texte français

# 4. Ajouter d'autres langues au besoin
loreline translate CoffeeShop.lor --lang de
loreline translate CoffeeShop.lor --lang es

Quand vous ajoutez du texte à votre script, relancez --auto-ids pour annoter les nouvelles lignes, puis --lang fr pour mettre à jour le fichier de traduction. Les traductions existantes ne seront pas écrasées.

Interpolation dans les traductions

Les traductions fonctionnent de manière transparente avec l'interpolation de texte. Les variables comme $count ou ${expression} sont préservées dans le fichier de traduction et évaluées à l'exécution :

Script source :

state
  count: 3

beat Start
  You have $count items #item-count
  barista: You ordered $count drinks #drink-reply

Fichier de traduction (Story.fr.lor) :

#item-count // You have $count items
Vous avez $count articles

#drink-reply // You ordered $count drinks
Vous avez commandé $count boissons

À l'exécution, $count est remplacé par sa valeur courante (3), ce qui produit « Vous avez 3 articles ».

Charger les traductions à l'exécution

Pour utiliser les traductions dans votre application, parsez le fichier de traduction et passez les traductions extraites à l'interpréteur. Voici un exemple en JavaScript :

import { Loreline } from 'loreline';

// Parser le script principal
const script = Loreline.parse(sourceContent);

// Parser le fichier de traduction
const translationScript = Loreline.parse(frenchContent);
const translations = Loreline.extractTranslations(translationScript);

// Jouer avec les traductions françaises
Loreline.play(script, onDialogue, onChoice, onFinish, {
  translations: translations
});

Le même principe s'applique dans tous les langages supportés. Consultez les guides d'intégration pour les détails en C#, C++, Python, Lua et Haxe.