Localisation et import/export

Cette page couvre l'ensemble du workflow de localisation de Libretto ainsi que l'échange de données CSV autour des dialogues : le déroulement d'une passe de traduction de bout en bout (configuration de la cible, suivi des lignes qui progressent à travers leurs statuts, découpage d'un lot CSV daté, envoi, puis réimport des traductions), l'import d'un dialogue depuis un CSV et l'export de dialogues vers un CSV à des fins de relecture.

Elle est autonome : tout ce qui concerne la traduction des dialogues, les mécaniques de localisation dans l'éditeur, l'import/export CSV et le suivi des statuts est réuni ici.

Deux types de localisation

Libretto distingue deux passes de localisation, chacune suivie par son propre statut par ligne :

• Base loca — la langue de base (pour nous, l'anglais écrit à partir d'une source française) qui est envoyée pour être traduite dans toutes les autres langues. Elle existe pour les pipelines qui pré-traduisent vers une langue de base avant de traduire vers les langues de production. Si vous écrivez directement dans la langue de base, vous ne quittez jamais Writing pour elle.
• Multi loca — toutes les autres langues de production, traduites à partir de la base.

Un troisième statut, Audio, suit l'état d'enregistrement et obéit à la même logique (exporter un lot, l'envoyer pour enregistrement/retakes, réimporter). Il n'est pas détaillé ici mais se comporte comme les statuts de localisation.

Chaque ligne porte donc trois statuts — Status Base Loca, Status Multi Loca, Status Audio — visibles dans Line Details ▸ Line. Chacun affiche son Status actuel, le dernier Batch, la Modification Date et l'Modification Author, ainsi qu'un bouton Open History (et un Reset à côté).

1. Configurer la cible

La localisation s'appuie sur une cible du Localization Dashboard (Tools ▸ Localization Dashboard). Chaque Dialogue que vous voulez traduire doit appartenir à une cible (une cible nommée « Dialogues » est une bonne pratique — vous pouvez en avoir plusieurs).

La configuration ponctuelle sur le dashboard :

1. Choisissez (ou créez) la cible de localisation.
2. Cochez la case et renseignez le chemin du dossier contenant les dialogues à localiser — ajoutez /* pour inclure les sous-dossiers. ⚠️ Décochez les autres cases « Gather from » afin que seuls vos dialogues soient collectés.
3. Définissez les langues. La langue native est celle dans laquelle les dialogues sont écrits ; ajoutez les langues localisées en dessous — il vous faut au moins une culture au-delà de la native, sans quoi il n'y a rien à traduire et les exports n'ont aucun intérêt.
4. Le nombre de mots / pourcentage de mots traduits par culture offre un aperçu rapide de l'avancement au cours d'une passe.
5. Les icônes d'édition par langue ouvrent la fenêtre d'édition des traductions. Le Dialogue Editor le fait pour vous, mais cette fenêtre reste pratique pour les corrections et le débogage.

Lancez le Gather Text initial

Une fois la cible configurée, lancez un Gather Text (bouton au-dessus de la liste des langues) pour référencer les dialogues existants — enregistrez-les d'abord. L'éditeur le fait automatiquement pour les nouveaux dialogues et les futures modifications ; la passe manuelle n'est nécessaire que pour amorcer le contenu existant.

Éditer les traductions dans l'éditeur

Vous traduisez normalement les lignes depuis le Dialogue Editor plutôt que depuis la fenêtre du dashboard. Faites un clic droit sur un subdialogue dans la liste pour l'ouvrir dans une langue spécifique ; vous pouvez ensuite éditer ses traductions directement.

• Une ligne sans traduction est affichée dans le texte natif (pour que vous voyiez ce qu'il y a à traduire).
• Éditer le texte natif d'une ligne efface ses traductions, forçant une re-traduction des autres langues.
• Le copier/coller perd la localisation d'une ligne — utilisez le paste special (clic droit ▸ Paste special) pour dupliquer la localisation et les autres assets associés en même temps que les lignes copiées.

Contrôle de version

Lorsqu'un Dialogue est référencé pour la localisation, les modifications de texte changent aussi les fichiers .manifest/.archive sous Content/Localization/<Target>[/<Language>]. Committez-les avec le Dialogue.

2. Le cycle de vie des statuts

Les statuts sont la manière dont une ligne progresse au fil d'une passe. Vous pouvez les définir à la main dans Line Details, mais l'export et l'import les font aussi progresser automatiquement. Voici le chemin que suit une ligne.

Une ligne neuve

Une nouvelle ligne démarre en MultiLoca AwaitingBase : elle ne peut pas être exportée pour la traduction multi-loca tant qu'une passe de base n'existe pas.

• Si vous utilisez une passe de pré-traduction de base, importer la base loca fait sortir la ligne de AwaitingBase.
• Si vous sautez la passe de base et traduisez directement, passez la ligne à ToLocalize à la main lorsque vous voulez qu'elle soit prise en compte par un export.

ToLocalize est le verrou : seules les lignes en ToLocalize sont exportées (l'export multi-loca ramasse aussi les lignes MissingCulture — voir ci-dessous). Tout le reste est laissé tel quel.

Le flux de relecture BaseLoca

Lorsque le texte d'un dialogue est stabilisé, le flux prévu consiste à passer ses lignes en ToReview, puis les responsables les promeuvent en ToLocalize pour les rendre éligibles à l'export. Tant qu'une ligne n'atteint pas ToLocalize, rien ne part.

Listes complètes des statuts (référence)

Vérifié contre ELBRStatus*Type dans LBRStatus.h (module LBRCore) :

• BaseLoca : Writing, TemporaryLocalized, ToLocalize, Sent, ToReview, Localized, Different
• MultiLoca : AwaitingBase, ToLocalize, Sent, Localized, MissingCulture, Different
• Audio : TtsToIntegrate, AwaitingBase, ToRecord, Sent, RecToIntegrate, RecIntegrated, ToRetake, SentToRetake, RetakeToIntegrate, MissingAudio, NoAudioNeeded

3. Exporter un lot

1. Dans le Content Browser, sélectionnez un ou plusieurs Dialogues — un même lot peut en porter autant que vous voulez.
2. Clic droit ▸ Export Dialogue To CSV File ▸ Localization (dans la section Import/Export du menu contextuel de l'asset).
3. La fenêtre Export Localization Options s'ouvre :
   • Change Line(s) Status — quand cette case est cochée, seules les lignes en ToLocalize sont exportées et leur statut bascule en Sent (estampillé avec le lot). Laissez-la décochée pour exporter le texte sans toucher aux statuts.
   • Only missing localization — n'exporter que les lignes dont la traduction est encore manquante, par langue.
   • Skip Duplicate — ignorer les chaînes dupliquées.
   • une case à cocher par langue à exporter (p. ex. fr).
   • Ok / Cancel.
4. Choisissez un dossier de sortie. Libretto crée un dossier de lot daté nommé YYYY.MM.DD-HH.MM (p. ex. 2024.07.31-14.56) contenant les CSV à envoyer.

Que l'export écrive du BaseLoca ou du MultiLoca est déduit des langues exportées : un export uniquement en base touche BaseLoca, sinon MultiLoca.

L'export peut soumettre automatiquement au contrôle de version

Lorsque Change Line(s) Status est cochée, Libretto bascule les lignes exportées en Sent et enregistre également les assets Dialogue concernés puis les soumet au contrôle de version — un unique check-in décrit « Export localization batch <batch> ». Cela suppose que les dialogues n'ont aucune modification locale avant l'export (annulez ou soumettez d'abord) ; si le check-in échoue, on vous demande de committer ou d'annuler à la main. Le check-in passe par l'API de contrôle de version d'Unreal : il fonctionne avec n'importe quel fournisseur (Subversion, Perforce, Git…). Pour exporter sans aucun effet de bord sur le contrôle de version, laissez Change Line(s) Status décochée.

Le dossier de lot

Le dossier contient un CSV par dialogue (D_Barks_John.csv) plus un Merged.csv qui les concatène tous — le fichier fusionné est celui que vous transmettez habituellement. Lorsqu'un dialogue comporte plus d'un subdialogue, les noms de fichiers individuels reçoivent un suffixe de subdialogue ; un dialogue à subdialogue unique s'exporte en simple D_Barks_John.csv.

Le format CSV

Le séparateur est le pipe | (choisi parce qu'il n'apparaît quasiment jamais dans le texte des dialogues). L'en-tête est fixe :

ID|SPEAKER|WORKSTRING|<culture…>|EMOTION|STAGEDIRECTION|CONTEXT|TYPE|NAMESPACE|INDEX|DIALOGUE|SUBDIALOGUE|<batch>

ID|SPEAKER|WORKSTRING|fr|EMOTION|STAGEDIRECTION|CONTEXT|TYPE|NAMESPACE|INDEX|DIALOGUE|SUBDIALOGUE|2024.07.31-14.56
13|BP_John_C [John]|Speak to me|||||Text|5B0E47C74A11D963A99B248E4CE1CDA8|8|D_Barks_John|Random_timed_barks

• Une colonne par langue exportée, vide et en attente de la traduction.
• La dernière cellule d'en-tête est le nom du lot.
• SPEAKER vaut ClassName [CharacterName] (avec (Off) lorsque le locuteur est l'auditeur) ; NAMESPACE est le GUID de localisation de la ligne ; INDEX est l'index de la ligne au sein du subdialogue.
• Les fichiers sont terminés en CRLF ; ouvrez le CSV dans un tableur plutôt que dans un éditeur de texte pour remplir la ou les colonnes de langue.

Réenregistrer le CSV

Enregistrez en UTF-8, avec le séparateur | uniquement et le délimiteur de chaîne ", et assurez-vous que « Edit filter settings » est coché lors de l'enregistrement depuis LibreOffice. Ces réglages exacts s'appliquent à chaque CSV que Libretto lit (import de localisation, import de dialogue).

4. Réimporter les traductions

Importez via Import Localization dans le menu déroulant Libretto de la barre d'outils de la fenêtre principale, puis sélectionnez le ou les CSV renvoyés par la traduction. Une fenêtre Import Localization Options propose alors Change Lines Status et Trim Quotes.

Libretto fait automatiquement correspondre chaque ligne du fichier à sa ligne (par dialogue et index) et écrit les traductions dans la cible de localisation Unreal — vous n'avez pas à lui indiquer à quel dialogue appartient une ligne.

Lors d'un import multi-loca, une ligne devient Localized (ou MissingCulture si certaines de ses langues sont encore non traduites) ; le lot est enregistré dans le statut. Lors d'un import base, BaseLoca devient ToReview et toute MultiLoca safeguardée est repoussée en Different.

Le statut doit correspondre à l'import

Le statut d'une ligne est censé être Sent (issu de l'export) lorsque sa traduction revient. Chaque ligne est mise en correspondance avec sa ligne et son statut est vérifié : s'il est Sent, la traduction est intégrée ; sinon, l'import entier est annulé et journalisé plutôt qu'appliqué à moitié.

Vous pouvez également importer via les boutons Import Text par langue du Localization Dashboard.

L'onglet traduit du subdialogue affiche désormais le texte importé, et la ligne indique Localized avec son lot.

5. Réédition d'une ligne traduite — le Safeguard

Une fois qu'une ligne est traduite, elle est safeguardée : son statut porte un poids logistique et un coût, aussi Libretto se prémunit contre son invalidation silencieuse. Éditer le texte d'une ligne safeguardée déclenche une popup Safeguard line <ID> :

You are trying to modify the text of a safeguarded line. Do you want to update the status to "Different" or don't modify the status ?

Elle affiche une case à cocher par type de statut concerné — Base loca / Multi loca / Audio — et trois boutons :

• Update Status — les statuts concernés passent en Different (Audio passe en ToRetake) ; la ligne sera de nouveau ramassée dans un futur lot pour être re-traduite ou ré-enregistrée.
• Keep Status — conserver le statut actuel ; vous acceptez que le sous-titre de cette ligne soit désormais désynchronisé de sa traduction (utile lorsque vous êtes trop proche de la sortie pour re-traduire).
• Cancel — abandonner la modification du texte.

Les statuts safeguardés sont, par type : BaseLoca Sent/ToReview/Localized, MultiLoca Sent/Localized, Audio Sent/RecToIntegrate/RecIntegrated/SentToRetake/RetakeToIntegrate/MissingAudio.

Safeguard à l'import

Une variante par lot du même garde-fou se déclenche à l'import lorsque le texte entrant écraserait des lignes safeguardées, listant d'un coup chaque ligne concernée.

Historique stocké dans l'asset

Chaque changement de statut enregistre la date, l'auteur et le lot, si bien que chaque ligne conserve une piste d'audit complète. Open History (sur l'un des trois blocs de statut dans Line Details) ouvre, par exemple, Status Multi Loca History for Line 13 of D_Barks_John — un tableau Status | Batch | Modification Date | Modification Author — retraçant le parcours de la ligne depuis AwaitingBase en passant par ToLocalize, Sent (avec le lot), jusqu'à Localized.

Cet historique vit à l'intérieur de l'asset Dialogue lui-même (un objet ULBRStatusHistory dans le package du dialogue), il voyage donc avec le fichier et survit d'une machine à l'autre.

D'où vient l'auteur

Le Modification Author est le UserName de votre fournisseur de contrôle de version actif (Subversion, Perforce…), lu dans ses réglages. Quand le fournisseur n'a pas de nom d'utilisateur (Git, ou pas de contrôle de version), Libretto prend le nom de votre compte système.

Importer un dialogue depuis un CSV

Outre les CSV de localisation, Libretto peut créer des dialogues entiers à partir d'un CSV de lignes écrites. Utilisez Import Dialogue dans le menu déroulant Libretto de la barre d'outils de la fenêtre principale (le bouton au-dessus du viewport). Il prend un ou plusieurs CSV avec cet en-tête :

Colonne	Signification
Title	Le nom du Dialogue
Character	Le nom du personnage
Intention	Correspond à la Stage Direction de la ligne
FP	(Final Pass) le texte de la ligne

Après avoir choisi le ou les CSV, une fenêtre d'options demande :

• un préfixe de nom de Dialogue (p. ex. D_QX_),
• le chemin des dialogues créés — il doit commencer par /Game/ (p. ex. /Game/Dialogues/QX),
• un mapping de chaque nom de personnage trouvé dans le CSV vers son Blueprint.

Les dialogues sont alors créés avec leur texte et leurs lignes de Speaker renseignés. Si un Dialogue portant ce nom existe déjà, les lignes sont ajoutées à son premier subdialogue plutôt que de créer un nouvel asset.

Pas à pas (depuis un tableur)

1. Exportez la feuille en CSV.
2. Ouvrez-la dans LibreOffice.
3. Assurez-vous que la ligne 1 contient les en-têtes (Title, Character, Intention, FP) ; supprimez toute ligne au-dessus. Le texte à importer doit se trouver dans la colonne FP.
4. Enregistrez en UTF-8 avec le séparateur | (cochez « Edit filter settings »).
5. Fermez LibreOffice.
6. Dans Unreal, Import Dialogue.
7. Remplissez la fenêtre d'import : un préfixe (p. ex. D_QX_) et un chemin (p. ex. /Game/Dialogues/QX), puis mappez les personnages vers leurs Blueprints (créez les Blueprints au préalable pour éviter de les mapper à la main).
8. Faites un check-out / enregistrez les fichiers créés ou modifiés.

Exporter des dialogues vers CSV

Faites un clic droit sur un ou plusieurs Dialogues dans le Content Browser pour les actions d'export (dans la section Import/Export du menu contextuel de l'asset) :

• Export Dialogue To CSV File ▸ Localization — l'export de passe de traduction décrit dans Exporter un lot ci-dessus.
• Export Dialogue To CSV File ▸ Choices And Replies — des CSV listant les Choices et Replies du dialogue (pour relire le branchement sans le pipeline de texte complet).
• Fix localization — force chaque ligne qui devrait être localisée à l'être (vous pouvez décocher la localisation sur des champs Text individuels ; cette action la réactive là où elle avait été abandonnée).