Guide du traducteur / Translators guide
🇫🇷 Cette page existe en deux langues dans ce même fichier : le français, qui est la version de référence, et l'anglais.
🇬🇧 This page holds both languages in this one file: the English version, or the French original it is translated from.
⚠️ Aux personnes qui modifient cette page / To whoever edits this page. Les deux moitiés ne font qu'une seule page : mêmes sections, même numérotation, même contenu, modifiées dans le même commit. Le français est la source, l'anglais sa traduction fidèle. The two halves are one single page: same sections, same numbering, same content, changed in the same commit. French is the source, English its faithful translation.
Français​
Cette moitié est la version de référence. Sa traduction anglaise est plus bas sur cette même page et doit suivre toute modification faite ici.
1. En deux mots​
Les textes du plugin Lasers-Enigma — messages du chat, noms d'objets, titres de menus — existent en 25 langues. Vous allez les traduire dans un logiciel fait pour ça, l'éditeur de traductions.
Vous n'aurez jamais Ă taper une commande ni Ă ouvrir un fichier Ă la main, et vous ne pouvez rien casser : votre travail part sous forme de proposition, que le mainteneur relit avant qu'elle n'atteigne le jeu.
Trois préalables, à faire une seule fois : un compte GitLab et l'accès au projet (§2), un jeton d'accès (§3), l'éditeur lui-même (§4). Ensuite, chaque session suit toujours le même déroulé : ouvrir le projet, créer une branche, traduire, envoyer pour relecture, prévenir les développeurs (§6).
2. Le compte GitLab et l'accès au projet​
GitLab est le site web où sont rangés les fichiers du projet : une sorte de Drive partagé, qui garde en plus l'historique complet de chaque modification et de son auteur. Vos traductions y sont stockées, et l'éditeur y renvoie votre travail en votre nom.
- Créez un compte, gratuit, sur https://gitlab.com/users/sign_up. Choisissez un nom d'utilisateur que vous assumez : il apparaîtra à côté de chacune de vos modifications, et toute l'équipe le verra.
- Confirmez l'e-mail que GitLab vous envoie.
- Demandez au mainteneur de vous ajouter au projet, en rôle Developer — sur Discord par exemple, en lui donnant votre nom d'utilisateur GitLab. Personne ne peut deviner que vous en avez besoin.
Le rôle Developer permet de proposer des modifications, pas de les publier : c'est là qu'est le filet de sécurité. Attendez la confirmation avant de continuer — tant que l'accès n'est pas accordé, l'éditeur ne verra aucun projet à ouvrir.
L'éditeur refait ce chemin avec vous, écran par écran, sous Setup help… (menu en haut à droite) : il rédige même le message à envoyer au mainteneur. Cette section et la suivante sont la même route, à lire avant d'avoir le logiciel.
3. Votre jeton d'accès personnel​
Un jeton (token) est une longue chaîne secrète, comme un mot de passe limité à un seul usage : il autorise l'éditeur à agir sur GitLab en votre nom — télécharger les textes, renvoyer vos modifications, ouvrir la demande de relecture.
Rendez-vous sur https://gitlab.com/-/user_settings/personal_access_tokens (par les menus : votre avatar en haut à droite → Edit profile → Access → Personal access tokens), puis :
- Lancez la création d'un jeton — le bouton s'appelle Generate token aujourd'hui, Add new token sur un GitLab plus ancien.
- Si GitLab demande le type de jeton, prenez le type historique (Legacy token). L'autre type, Fine-grained, ne propose pas du tout la permission dont l'Ă©diteur a besoin, et rien ne vous le dirait avant l'Ă©chec.
- Nommez-le
Translation editor, pour le reconnaître plus tard. - Choisissez une date d'expiration dans quelques mois. (Si vous ne mettez rien, GitLab met un an.)
- Dans la liste des permissions (scopes), cochez
api, et rien d'autre. - Validez, puis copiez le jeton immédiatement : GitLab ne l'affiche qu'une seule fois. Si vous quittez ou rechargez la page, il faudra en créer un autre.
Ce jeton est un mot de passe. Ne le collez pas dans un salon Discord, ne l'envoyez pas par e-mail, ne l'écrivez pas dans un fichier. Vous ne le taperez qu'une fois, dans l'éditeur, qui le confie au trousseau de votre système — là où votre navigateur range vos propres mots de passe. Il ne l'écrit jamais dans un fichier et ne le réaffiche jamais.
Si vous pensez que quelqu'un d'autre l'a vu, supprimez-le sur la même page (GitLab dit revoke) et créez-en un nouveau ; dans l'éditeur, le menu en haut à droite → Forget token l'efface du trousseau. Quand il expirera, dans quelques mois, l'éditeur rouvrira de lui-même l'étape qui en refait un : c'est une routine, pas une panne, et rien de ce que vous avez traduit n'est perdu.
4. Installer l'éditeur​
L'Ă©diteur est un seul fichier. Il n'y a rien Ă installer et aucun droit administrateur Ă demander.
Où le récupérer​
Les fichiers sont publiés sur le serveur de Skytale, et la page qui les liste est publique : https://repository.skytale.fr/artifactory/public/fr/skytale/translation-lib-editor/
Elle contient un dossier par version publiée, plus un dossier latest/ dès qu'une version officielle
est sortie. Si latest/ est dans la liste, ouvrez-le : il contient toujours la dernière version
publiée, et c'est l'adresse à garder en favori. Sinon, aucune version officielle n'est encore sortie :
prenez le dernier dossier de la liste (aujourd'hui 0.1.0-SNAPSHOT/), qui contient le mĂŞme Ă©diteur
construit Ă partir du travail en cours. Dans le doute, demandez au mainteneur.
Il y a un fichier par système, tous nommés translationlib-editor-… : c'est la fin du nom qui
vous dit lequel prendre.
| Votre machine | Le nom du fichier se termine par |
|---|---|
| Windows | -windows-amd64.exe |
| Mac avec puce Apple (M1, M2, M3…) | -darwin-arm64 |
| Mac avec puce Intel | -darwin-amd64 |
| Linux | -linux-amd64 |
| Linux sur machine ARM (Raspberry Pi…) | -linux-arm64 |
Sur Linux, en cas d'hésitation, uname -m tranche : x86_64 veut dire amd64, aarch64 veut dire
arm64. Rangez le fichier Ă un endroit que vous retrouverez, le Bureau par exemple.
Votre système va vous faire peur, une fois​
Ce fichier n'est pas signé par un certificat commercial : votre système ne sait donc pas qui l'a fabriqué, et il vous le dira sans nuance. C'est attendu, ce n'est pas un virus, et vous ne verrez ces écrans qu'une fois.
| Système | Ce que vous voyez, et ce qu'il faut cliquer |
|---|---|
| Windows | Une fenêtre bleue : « Windows a protégé votre ordinateur », avec pour seul bouton visible Ne pas exécuter. Le bon bouton est caché : Informations complémentaires (More info), puis Exécuter quand même (Run anyway). |
| macOS | Le Finder refuse d'ouvrir le fichier. Ne double-cliquez pas : clic droit (ou Ctrl-clic) → Ouvrir, puis Ouvrir à nouveau dans la fenêtre qui apparaît. |
| Linux | Rendez le fichier exécutable une fois : clic droit → Propriétés → Permissions → Autoriser l'exécution, ou chmod +x <fichier> dans un terminal. |
Sur macOS, si rien ne se passe, le fichier n'est pas encore exécutable. Ouvrez Terminal
(Applications → Utilitaires), tapez chmod +x avec l'espace final, glissez-déposez le fichier
dans la fenêtre, Entrée ; puis glissez-déposez à nouveau et Entrée pour le lancer. Si cette étape
vous bloque, demandez de l'aide au mainteneur plutĂ´t que d'insister.
Le lancer​
Double-cliquez sur le fichier. Une fenĂŞtre noire s'ouvre et reste ouverte : c'est normal, c'est le programme qui tourne. Laissez-la ouverte pendant tout votre travail et fermez-la quand vous avez fini.
Votre navigateur s'ouvre tout seul sur l'éditeur ; s'il ne s'ouvre pas, ouvrez vous-même http://127.0.0.1:8080. Collez le jeton de la section 3 : l'éditeur le vérifie immédiatement auprès de GitLab et vous dit à quel compte il appartient.
Le guide complet d'utilisation est intégré au logiciel : même menu en haut à droite, entrée Translator's guide…. Il décrit le tableau, le panneau d'édition, les couleurs, l'aperçu, et la liste complète des messages d'erreur. Les sections suivantes disent la même chose ; celui-là a l'avantage d'être sous vos yeux pendant que vous travaillez.
5. Ce que vous traduisez, exactement​
L'éditeur est en anglais. Les noms de colonnes et de boutons sont donc donnés ci-dessous tels qu'ils apparaissent à l'écran.
Un code, une valeur, 25 langues​
Chaque texte du plugin a un code — un identifiant interne comme errors.area.too_small_exception —
et une valeur, la phrase réellement affichée. Le code ne change jamais : c'est lui qui relie
entre elles les 25 versions de la mĂŞme phrase. Vous ne traduisez que les valeurs.
L'anglais est la langue de référence : c'est l'original, il est affiché en permanence et vous ne pouvez pas le modifier.
Votre langue n'apparaît pas dans la liste ? L'éditeur ne peut pas la créer : il ne fait que remplir des fichiers qui existent déjà . Demandez au mainteneur de créer celui de votre langue ; elle apparaîtra à votre prochaine ouverture du projet.
Les variables {0}, {1}, {2}…​
Beaucoup de phrases contiennent des trous que le jeu remplit au moment de l'affichage. Par exemple,
Area {0} resized to {1}x{2}x{3}. devient en jeu « Area Blue Tower resized to 12x8x12. »
- Vous pouvez les dĂ©placer. L'ordre des mots change d'une langue Ă l'autre : rien ne vous oblige Ă
garder
{0}avant{1}. - Vous ne pouvez ni en supprimer ni en inventer. Chaque variable de l'original doit être présente dans votre traduction, exactement une fois. Une variable perdue, c'est une information qui disparaît en jeu, ou un message cassé.
Dans l'éditeur, une variable n'est pas du texte que vous tapez : c'est un bloc que vous insérez
depuis la barre d'outils, que vous déplacez d'un seul tenant et que vous ne pouvez pas couper en deux.
À côté, l'éditeur affiche ce que chaque variable représente (« {0} — le nom de l'aire ») quand
les développeurs l'ont écrit. Quand ils ne l'ont pas fait, elle est marquée not described : dans ce
cas, ne devinez pas, posez la question.
Les codes couleur ne sont pas du texte​
Dans les fichiers, la couleur et le gras s'écrivent avec des codes commençant par § : §c pour
rouge, §7 pour gris, §l pour gras… Ce ne sont pas des mots, ce sont des instructions de mise en
forme, et elles portent du sens (rouge = erreur, gris = description).
Vous n'aurez jamais à taper un code § : vous sélectionnez votre texte et vous cliquez sur une
couleur, comme dans un traitement de texte. Deux choses Ă retenir :
- respectez les couleurs de l'original, sauf raison précise ;
- certains endroits n'acceptent pas la couleur du tout — la console du serveur, un texte dessiné sur
une carte. L'Ă©diteur n'y propose alors aucun bouton de couleur, et un
§qui apparaîtrait littéralement dans l'aperçu est le signe qu'il ne faut pas y toucher.
La place disponible dépend de l'endroit​
Un texte affiché dans le chat a de la place ; un nom d'objet n'en a presque pas. La colonne Surface dit où le texte apparaît, et l'éditeur en déduit la limite.
Il nomme en clair les surfaces qu'il sait dessiner — Chat message, Item name, Item description
(les lignes grises sous un nom d'objet), Action bar, Map text, Server log… Quand le plugin a
inventé une surface qui lui est propre, elle garde le nom qu'il lui a donné (race_sidebar, par
exemple) : c'est le seul qui existe pour elle. Le panneau d'Ă©dition explique chaque surface en une
phrase, et l'aperçu montre votre texte dans le bon cadre.
Un compteur indique la place restante pendant que vous écrivez ; la mention hard limit signifie que le jeu coupe ce qui dépasse. Un texte affiché à deux endroits doit tenir dans le plus petit des deux.
Le tableau : les colonnes​
| Colonne (Ă l'Ă©cran) | Ce qu'elle vous dit |
|---|---|
| Status | Done (fait), Changed (modifié, pas encore enregistré), Not translated, Worth a look (à regarder), Must be fixed (à corriger) — avec une pastille verte, bleue, grise, orange ou rouge |
| Part of the game | Le groupe de fichiers d'où vient le texte (les aires, la course, les succès…) |
| Context | La note des développeurs : où et quand ce texte apparaît. À lire avant de traduire |
| Tags | Les familles de textes déclarées par le plugin, chacune avec une phrase qui dit ce qu'elle regroupe (survolez-la) |
| Surface | Où c'est affiché — donc la place dont vous disposez |
| Who sees it | Qui voit ce texte : Any player, Level creators, Server admins ou Server console. Not stated = personne ne l'a noté |
| Permission | Le droit qu'il faut avoir en jeu pour que ce texte apparaisse ; None needed = tout le monde |
| Reference (en) | L'original anglais — sauf si vous affichez déjà l'anglais parmi vos langues |
| (une colonne par langue choisie) | Votre travail, chacune avec sa propre pastille d'Ă©tat |
Deux colonnes sont masquées par défaut et s'affichent depuis le bouton Columns : Internal name (le code interne) et Part of the plugin (la fonctionnalité concernée). Un ⚠devant un contexte signale une entrée que les développeurs ont marquée comme nécessitant encore une relecture humaine ; la raison est dans l'infobulle et dans le panneau d'édition.
Filtrer, et savoir ce qu'il vous reste​
Chaque colonne visible se filtre, depuis la ligne sous les en-têtes. Une colonne à valeurs fixes propose des cases à cocher et garde une ligne dès que l'une de ses valeurs est cochée ; les colonnes de texte libre — le contexte, l'original, vos traductions — se filtrent sur ce que vous tapez. Une colonne masquée n'a pas de ligne de filtre : affichez-la d'abord avec Columns.
« Qu'est-ce qu'il me reste à faire ? » se répond avec le filtre de la colonne Status, sur la ligne sous son titre. Cochez-en autant que vous voulez :
- Not translated : pas encore de traduction. Une traduction laissée vide compte comme manquante ;
- Changed : modifié et pas encore enregistré, les notes partagées comprises ;
- Must be fixed : quelque chose ne va pas, votre travail ne peut pas partir tant que ce n'est pas corrigé ;
- Worth a look : une suggestion ; vous pouvez envoyer votre travail tel quel ;
- Done : rien Ă faire ici.
Cette colonne et son filtre répondent pour les langues que vous avez cochées comme vôtres sur l'écran Languages. Une langue ouverte seulement pour la lire n'est jamais comptée : vous ne pouvez pas y combler un manque, ce n'est donc pas votre travail.
Clear filters vide toutes les lignes de filtres, celle-ci comprise. Les compteurs done / total de la seconde ligne comptent ces mêmes langues, une ligne chacune que vous modifiez, quels que soient les filtres et le sélecteur.
Le panneau d'édition​
Cliquez sur une cellule de l'une de vos langues — ce sont les seules qu'un clic ouvre. Un panneau s'ouvre à droite, et il contient, dans cet ordre :
- Where this text appears : la note des développeurs, ce que représente chaque variable, la surface et la phrase qui la décrit, qui voit le texte, la permission, et ce que demande chaque tag ;
- Your translation : une zone de texte normale, avec les seuls boutons autorisés à cet endroit — pas de bouton de retour à la ligne veut dire que le texte doit tenir sur une ligne — puis le compteur de caractères et l'aperçu, le vôtre puis l'original, dans leur vrai cadre ;
- les messages : Check en orange est un conseil ; Fix en rouge doit être corrigé, sinon l'envoi du lot sera refusé. Apply conserve votre modification dans les deux cas ;
- Revert this cell, qui apparaît dès que la cellule est modifiée et remet la valeur que le fichier contient encore — affichée juste au-dessus du bouton.
Les colonnes Context et Tags sont partagées par toutes les langues et tous les traducteurs : elles restent en lecture seule tant que vous n'avez pas coché Also edit the notes and the display settings dans la barre d'outils ; un double-clic les ouvre alors dans le tableau.
Vos modifications s'accumulent dans l'éditeur — un compteur en haut dit combien sont en attente — et elles sont toujours là à votre prochaine ouverture de cette branche.
6. Le déroulé d'une session de travail​
Cinq étapes, toujours les mêmes. Les mots techniques sont expliqués au passage ; dans le logiciel, un petit ? à côté de chacun d'eux en redonne le sens sur place.
6.1 Choisir le projet​
L'éditeur affiche les projets auxquels vous avez accès, les plus récents d'abord ; le mainteneur vous dira lequel ouvrir. La première ouverture télécharge une copie complète du projet : sur un gros plugin, comptez quelques minutes, une seule fois. Ensuite, c'est instantané.
6.2 Créer une branche​
Une branche, c'est votre copie de travail, la vĂ´tre seule. Vous y faites ce que vous voulez sans
déranger personne et sans toucher à ce qui tourne sur le serveur. Décrivez en quelques mots ce que
vous allez faire — noms des objets en espagnol — et appuyez sur Create branch.
Le plugin Lasers-Enigma exige un numéro de ticket : un champ Issue, marqué required, apparaît à côté du nom. C'est le mainteneur qui vous le donne, demandez-le avant de commencer. (Sur un projet qui n'en exige pas, ce champ n'apparaît pas du tout.)
Un lot de travail = une branche = une demande de fusion. Un relecteur lit trente lignes avec plaisir et trois cents Ă reculons.
- Reprendre votre travail : la branche est sous Your branches on this computer. Cette liste ne montre que les branches créées pour traduire ; cochez Show every branch of the project pour voir les autres.
- Rejoindre une branche commencée par quelqu'un d'autre : elles sont listées à part, et c'est autorisé — mais mettez-vous d'accord sur qui prend quelles langues, et envoyez votre travail souvent. L'éditeur ne peut envoyer le vôtre que tant que rien de nouveau n'est arrivé sur cette branche ; sinon il s'arrête et c'est au mainteneur de réconcilier les deux versions.
- La branche que tout le monde partage n'est pas un endroit où travailler : rien de ce qui y est enregistré ne peut être relu. L'éditeur y refuse purement et simplement l'enregistrement, et Continue vous renvoie au formulaire tant que vous n'avez pas votre propre branche.
- Renoncer : tout en bas de l'écran des branches, Give up on this work supprime votre copie de la branche — ou, sur la branche partagée, la remet exactement dans l'état du projet. Ce qui a déjà été envoyé reste sur le serveur du projet ; ce qui n'a jamais quitté votre machine est perdu pour tout le monde. Le panneau compte les deux avant de vous demander confirmation.
6.3 Traduire​
Choisissez les langues à voir et celles à modifier — modifier une langue l'affiche automatiquement — puis travaillez dans le tableau (section 5).
6.4 Envoyer pour relecture​
Un seul bouton : Send for review. Il enchaîne trois étapes, qu'il vous montre une par une pendant qu'elles tournent.
| Étape | Ce qu'elle fait |
|---|---|
| Commit | Écrit vos modifications dans votre branche, sur votre machine |
| Push | Envoie votre branche sur GitLab : votre travail quitte votre machine et devient visible par l'Ă©quipe |
| Merge request | Ouvre la demande de fusion : « voici ce que j'ai changé, peut-on l'intégrer ? ». Une page qui montre votre travail ligne par ligne, avec un espace de discussion |
Si l'une des trois ne passe pas, l'éditeur vous dit laquelle et s'arrête là . Rien n'est perdu et rien n'est défait : réappuyez une fois le problème réglé, il reprend où il s'est arrêté au lieu d'enregistrer vos modifications une seconde fois.
Avant d'appuyer, vous pouvez laisser une note sur ce lot, dans la case sous le numéro de ticket. Elle est facultative, elle voyage avec votre envoi et le mainteneur la lit : c'est l'endroit où écrire « je n'ai pas touché aux noms d'objets, il faut trancher sur la formulation ».
Il arrive qu'un enregistrement signale que quelques textes corrigés ont été marqués pour que les serveurs qui font déjà tourner le plugin les reprennent. C'est normal, c'est automatique, et vous n'avez rien à en faire.
Le second bouton : Commit only. Pour le jour oĂą le lot n'est pas fini : il enregistre votre travail dans votre branche et s'arrĂŞte lĂ , rien ne quitte votre machine. Vous reprendrez plus tard et enverrez Ă ce moment-lĂ .
C'est sur cette page que le mainteneur vous répond et que vous posez vos questions — une variable non décrite, un doute sur le ton d'une phrase.
6.5 Prévenir les développeurs​
Une fois la demande de fusion créée, l'éditeur rédige pour vous un court message prêt à coller dans le salon Discord que les développeurs lisent : le lien vers la relecture, le plugin, les langues, le nombre de textes modifiés et le ticket concerné.
Cliquez sur le message pour le sélectionner en entier, ou utilisez Copy the message. C'est cette étape qui fait la différence entre un travail envoyé et un travail vu : sans elle, votre demande de fusion attend que quelqu'un pense à regarder.
7. Quand quelque chose ne va pas​
| Ce que vous voyez | Ce qu'il faut faire |
|---|---|
| La liste des projets est vide | Votre accès n'a pas encore été accordé, ou votre jeton a expiré. Relisez les sections 2 et 3. |
| « Your access has expired » | Un jeton ne vit que quelques mois. L'éditeur rouvre de lui-même l'étape qui en refait un : deux minutes, et rien de ce que vous avez traduit n'est perdu. |
| GitLab refuse votre jeton | Presque toujours l'une de trois causes : un morceau manque (recopiez-le d'un bloc, sans espace autour), il a expiré, ou la case api n'était pas cochée — un jeton sans elle ne peut rien faire. |
| « A branch with that name already exists » | Rien n'a été créé. Changez ce que vous avez tapé — ajoutez la langue, ou la partie du plugin — ou basculez sur la branche que vous aviez déjà commencée. |
| « This copy of the project is not on any branch » | Rien ne peut être écrit ni envoyé depuis là . Nommez une branche, ou basculez sur l'une des vôtres. Rien n'est supprimé sur votre machine. |
| « Your last save is … and will not be in a new branch » | Vous avez enregistré avant de créer votre branche. Créez-la et continuez ; le bouton de ce message rédige au mainteneur la demande de déplacer cet enregistrement. |
| « Someone else changed the same branch after you started » | Votre travail est enregistré et intact ; seul l'envoi a été refusé. Prévenez le mainteneur, qui réconciliera les deux versions. |
| « Someone else has already changed some of the same texts » | Rien n'a été écrit et rien n'est perdu. Envoyez la liste au mainteneur pour qu'il décide quelle version garder. |
| « The copy of the project on this computer still holds changes from an earlier session » | Les branches ne peuvent plus être créées ni changées tant que ce n'est pas réglé. Vos traductions en attente sont saines et ne sont pas en cause : prévenez le mainteneur. |
| « Some texts cannot be saved as they are » | Les textes listés portent un message rouge. Corrigez-les et renvoyez : rien n'a été écrit, ni envoyé, ni proposé. |
| « This repository only has the reference language » | Le fichier de votre langue n'existe pas encore, et seul le mainteneur peut le créer. |
| « GitLab could not be reached » | Vérifiez votre connexion et réessayez dans une minute. Rien n'a été envoyé. |
| Un formulaire de configuration au lieu des traductions | Le dépôt n'a pas encore été préparé pour les traducteurs. Ce n'est pas à vous de le faire : prévenez le mainteneur. |
| Un bandeau Configuration en haut de l'écran | Un réglage du projet est incorrect et seul le mainteneur peut le corriger. Envoyez-lui la ligne telle quelle ; rien de ce qui est à vous n'est perdu. |
| Une carte rouge que vous ne comprenez pas | Copy details, et envoyez ça au mainteneur. Le message nomme toujours le texte concerné. |
| L'éditeur ne démarre plus, ou la page est morte | Vérifiez que la fenêtre noire est toujours ouverte, puis rouvrez http://127.0.0.1:8080. Si vous l'avez fermée, relancez le fichier : rien n'est perdu. |
À qui demander​
- Une question sur une phrase à traduire (le sens d'une variable, le ton attendu, un mot ambigu) → en commentaire sur votre demande de fusion. C'est tracé, et la réponse profite à tout le monde.
- Une question sur l'accès, l'installation, le jeton, un numéro de ticket → au mainteneur, directement, sur Discord.
Une minute de question coûte toujours moins cher qu'une traduction fausse qui vit six mois.
8. Pour aller plus loin​
- Le guide intégré à l'éditeur (menu en haut à droite → Translator's guide…) — l'utilisation détaillée du tableau et du panneau d'édition, sous vos yeux pendant que vous travaillez.
- Translations (installation) — la liste des 25 langues livrées avec le plugin et la façon dont un administrateur de serveur choisit la sienne.
- Translations (code structure) — la face développeur : où vivent les fichiers, comment sont écrites les métadonnées que vous lisez dans la colonne Context.
- Other ways to contribute — les autres façons d'aider le projet.
English​
This half is the translation of the French version above. French is the source: whatever changes up there must be carried down here in the same commit. Same sections, same numbering, same content.
1. In a nutshell​
The Lasers-Enigma plugin's texts — chat messages, item names, menu titles — exist in 25 languages. You are going to translate them in a program built for the job: the translation editor.
You will never have to type a command or open a file by hand, and you cannot break anything: your work is sent as a proposal, which the maintainer reviews before it ever reaches the game.
Three things to get out of the way once: a GitLab account and access to the project (§2), an access token (§3), the editor itself (§4). After that, every session follows the same run: open the project, create a branch, translate, send for review, tell the developers (§6).
2. The GitLab account and access to the project​
GitLab is the website where the project's files live: a bit like a shared Drive, except it also keeps the complete history of every change and of who made it. Your translations are stored there, and the editor sends your work back in your name.
- Create a free account at https://gitlab.com/users/sign_up. Choose a username you are happy to stand behind: it appears next to every one of your changes, and the whole team will see it.
- Confirm the email GitLab sends you.
- Ask the maintainer to add you to the project, with the Developer role — on Discord for instance, giving them your GitLab username. Nobody can guess that you need it.
The Developer role lets you propose changes, not publish them: that is where the safety net is. Wait for their confirmation before going on — until access is granted, the editor will see no project to open.
The editor walks this road with you, one screen at a time, under Setup help… (menu at the top right): it even writes the message to send to the maintainer. This section and the next one are the same road, to be read before you have the program.
3. Your personal access token​
A token is a long secret string, like a password limited to a single use: it lets the editor act on GitLab in your name — download the texts, send your changes back, open the review request.
Go to https://gitlab.com/-/user_settings/personal_access_tokens (through the menus: your avatar, top right → Edit profile → Access → Personal access tokens), then:
- Start creating a token — the button is called Generate token today, Add new token on an older GitLab.
- If GitLab asks which kind of token, choose the legacy one (Legacy token). The other kind, Fine-grained, does not offer the permission the editor needs at all, and nothing would tell you so before it failed.
- Name it
Translation editor, so you recognise it later. - Pick an expiry date a few months out. (Leave it empty and GitLab uses one year.)
- In the permissions list (scopes), tick
api, and nothing else. - Confirm, then copy the token immediately: GitLab shows it once, and once only. If you leave or reload the page, you will have to create another one.
This token is a password. Do not paste it into a Discord channel, do not email it, do not put it in a file. You will type it only once, into the editor, which hands it to your system's keychain — the same place your browser keeps your own passwords. It never writes it to a file and never shows it again.
If you think somebody else has seen it, delete it on that same page (GitLab says revoke) and create a new one; in the editor, the top-right menu → Forget token wipes it from the keychain. When it expires, a few months from now, the editor reopens the step that makes a new one by itself: it is a routine event, not a failure, and nothing you have translated is lost.
4. Install the editor​
The editor is a single file. There is nothing to install and no administrator rights to ask for.
Where to get it​
The files are published on Skytale's server, and the page listing them is public: https://repository.skytale.fr/artifactory/public/fr/skytale/translation-lib-editor/
It holds one folder per published version, plus a latest/ folder as soon as an official version has
been released. If latest/ is in the list, open it: it always holds the newest released version,
and it is the address worth bookmarking. Otherwise no official version has been released yet: take
the last folder in the list (today 0.1.0-SNAPSHOT/), which holds the same editor built from the work
in progress. When in doubt, ask the maintainer.
There is one file per system, all named translationlib-editor-…: it is the end of the name
that tells you which one is yours.
| Your machine | The file name ends with |
|---|---|
| Windows | -windows-amd64.exe |
| Mac with an Apple chip (M1, M2, M3…) | -darwin-arm64 |
| Mac with an Intel chip | -darwin-amd64 |
| Linux | -linux-amd64 |
| Linux on an ARM machine (Raspberry Pi…) | -linux-arm64 |
On Linux, if you are unsure, uname -m settles it: x86_64 means amd64, aarch64 means arm64.
Put the file somewhere you will find again, your Desktop for instance.
Your system will scare you, once​
This file is not signed with a commercial certificate: your system does not know who built it, and it will tell you so bluntly. This is expected, it is not a virus, and you will only see these screens once.
| System | What you see, and what to click |
|---|---|
| Windows | A blue window: "Windows protected your PC", with a single visible button, Don't run. The button you need is hidden: More info, then Run anyway. |
| macOS | Finder refuses to open the file. Do not double-click: right-click (or Ctrl-click) → Open, then Open again in the window that appears. |
| Linux | Make the file executable once: right-click → Properties → Permissions → Allow executing, or chmod +x <file> in a terminal. |
On macOS, if nothing happens, the file is not executable yet. Open Terminal (Applications →
Utilities), type chmod +x with the trailing space, drag and drop the file into the window, press
Enter; then drag and drop it again and press Enter to run it. If this step blocks you, ask the
maintainer for help rather than pushing on.
Running it​
Double-click the file. A black window opens and stays open: that is normal, it is the program running. Leave it open for the whole of your work and close it when you are done.
Your browser opens on the editor by itself; if it does not, open http://127.0.0.1:8080 yourself. Paste the token from section 3: the editor checks it with GitLab straight away and tells you which account it belongs to.
The full user guide ships inside the program: same top-right menu, entry Translator's guide…. It describes the table, the edit panel, the colours, the preview, and the complete list of error messages. The sections below say the same things; that one has the advantage of being in front of you while you work.
5. What exactly you are translating​
The editor is in English. The column and button names below are therefore given exactly as they appear on screen.
One code, one value, 25 languages​
Every text in the plugin has a code — an internal identifier such as
errors.area.too_small_exception — and a value, the sentence actually displayed. The code
never changes: it is what ties the 25 versions of the same sentence together. You only translate
the values.
English is the reference language: it is the original, it is shown permanently, and you cannot modify it.
Your language is not in the list? The editor cannot create it: it only fills in files that already exist. Ask the maintainer to create the one for your language; it will show up the next time you open the project.
The {0}, {1}, {2}… placeholders​
Many sentences contain gaps the game fills in at display time. For example,
Area {0} resized to {1}x{2}x{3}. becomes "Area Blue Tower resized to 12x8x12." in game.
- You may move them. Word order changes from one language to another: nothing forces you to keep
{0}before{1}. - You may neither delete one nor invent one. Every placeholder in the original must be present in your translation, exactly once. A lost placeholder is information that disappears in game, or a broken message.
In the editor a placeholder is not text you type: it is a block you insert from the toolbar, move
in one piece, and cannot cut in half. Next to it, the editor shows what each placeholder stands
for ("{0} — the area name") when the developers wrote it down. When they did not, it is marked
not described: in that case, do not guess — ask.
Colour codes are not text​
In the files, colour and bold are written with codes starting with §: §c for red, §7 for grey,
§l for bold… These are not words, they are formatting instructions, and they carry meaning (red =
error, grey = description).
You will never have to type a § code: you select your text and click a colour, as in a word
processor. Two things to remember:
- respect the colours of the original, unless you have a specific reason not to;
- some places do not accept colour at all — the server console, a text drawn on a map. The editor then
offers no colour button there, and a
§appearing literally in the preview is the sign to leave that text alone.
How much room you have depends on where the text appears​
A text shown in the chat has room; an item name has almost none. The Surface column says where the text appears, and the editor derives the limit from it.
It names in plain words the surfaces it knows how to draw — Chat message, Item name, Item
description (the grey lines under an item name), Action bar, Map text, Server log… When the
plugin has invented a surface of its own, it keeps the name the plugin gave it (race_sidebar, for
example): that is the only one it has. The edit panel explains each surface in one sentence, and the
preview shows your text in the right frame.
A counter tells you how much room is left as you write; hard limit means the game cuts off whatever does not fit. A text shown in two places must fit in the smaller of the two.
The table: the columns​
| Column (on screen) | What it tells you |
|---|---|
| Status | Done, Changed (edited, not saved yet), Not translated, Worth a look, Must be fixed — with a green, blue, grey, amber or red dot |
| Part of the game | The group of files the text comes from (areas, the race, achievements…) |
| Context | The developers' note: where and when this text appears. Read it before translating |
| Tags | The families of texts declared by the plugin, each with a sentence saying what it groups (hover it) |
| Surface | Where it is displayed — so, how much room you have |
| Who sees it | Who sees this text: Any player, Level creators, Server admins or Server console. Not stated = nobody wrote it down |
| Permission | The right a player needs in game for this text to appear; None needed = everybody |
| Reference (en) | The English original — unless you are already displaying English among your languages |
| (one column per chosen language) | Your work, each with its own status dot |
Two columns are hidden by default and are shown from the Columns button: Internal name (the internal code) and Part of the plugin (the feature concerned). A âš in front of a context flags an entry the developers marked as still needing a human; the reason is in the tooltip and in the edit panel.
Filtering, and knowing what is left​
Every visible column can be filtered, from the row under the headers. A column with a fixed set of values offers tick boxes and keeps a row as soon as one of its values is ticked; the free-text ones — the context, the original, your translations — filter on what you type. A hidden column has no filter row: show it first with Columns.
"What is left for me?" is answered by the Status column's own filter, on the row under its title. Tick as many as you want:
- Not translated: no translation yet. One left empty counts as missing;
- Changed: edited and not saved yet, the shared notes included;
- Must be fixed: something is wrong and your work cannot be sent until it is;
- Worth a look: a suggestion; you can send your work as it is;
- Done: nothing to do here.
That column and its filter answer for the languages you ticked as yours on the Languages screen. A language you opened only to read is never counted: you cannot close a gap in it, so it is not your work.
Clear filters empties every filter row, this one included. The done / total counters on the second line count those same languages, one line each, whatever the filters say.
The edit panel​
Click a cell in one of your languages — those are the only cells a click opens. A panel appears on the right, holding, in this order:
- Where this text appears: the developers' note, what each placeholder stands for, the surface and the sentence describing it, who sees the text, the permission, and what each tag asks of you;
- Your translation: a normal text box, with only the buttons allowed in that place — no line-break button means the text has to stay on one line — then the character counter and the preview, yours and then the original, each in its real frame;
- the messages: Check in amber is advice; Fix in red must be corrected, or sending the batch will be refused. Apply keeps your change either way;
- Revert this cell, which appears as soon as the cell is changed and puts back the value the file still holds — shown just above the button.
The Context and Tags columns are shared by every language and every translator: they stay read-only until you tick Also edit the notes and the display settings in the toolbar; a double-click then opens them in the table.
Your changes pile up in the editor — a counter at the top says how many are pending — and they are still there the next time you open that branch.
6. How a working session runs​
Five steps, always the same ones. The technical words are explained as they come; in the program, a small ? beside each of them gives its meaning on the spot.
6.1 Choose the project​
The editor shows the projects you have access to, most recent first; the maintainer will tell you which one to open. The first opening downloads a complete copy of the project: on a large plugin, count a few minutes, once only. After that it is instant.
6.2 Create a branch​
A branch is your working copy, yours alone. You do whatever you like in it without disturbing
anybody and without touching what is running on the server. Describe in a few words what you are about
to do — spanish item names — and press Create branch.
The Lasers-Enigma plugin requires a ticket number: an Issue field, marked required, appears next to the name. The maintainer is the one who gives it to you, so ask before you start. (On a project that does not require one, that field does not appear at all.)
One batch of work = one branch = one merge request. A reviewer reads thirty lines gladly and three hundred reluctantly.
- Picking your work up again: the branch is under Your branches on this computer. That list only shows the branches created for translating; tick Show every branch of the project to see the others.
- Joining a branch somebody else started: those are listed apart, and it is allowed — but agree on who takes which languages, and send your work often. The editor can only send yours up while nothing new has arrived on that branch; otherwise it stops, and it is up to the maintainer to reconcile the two versions.
- The branch everyone shares is not a place to work: nothing saved there can be reviewed. The editor refuses to save on it outright, and Continue sends you back to the form until you have a branch of your own.
- Giving up: at the very bottom of the branch screen, Give up on this work deletes your copy of the branch — or, on the shared branch, puts it back exactly as the project has it. What you had already sent stays on the project's server; what never left your computer is lost for everybody. The panel counts both before it asks you to confirm.
6.3 Translate​
Choose the languages to see and the ones to edit — editing a language shows it automatically — then work in the table (section 5).
6.4 Send for review​
One single button: Send for review. It runs three steps, shown one by one as they go.
| Step | What it does |
|---|---|
| Commit | Writes your changes into your branch, on your machine |
| Push | Sends your branch to GitLab: your work leaves your machine and becomes visible to the team |
| Merge request | Opens the merge request: "here is what I changed, can it go in?". A page showing your work line by line, with a discussion space |
If one of the three does not go through, the editor tells you which one and stops there. Nothing is lost and nothing is undone: press it again once the problem is sorted out and it picks up where it stopped, instead of saving your changes a second time.
Before you press it you can leave a note about this batch, in the box under the ticket number. It is optional, it travels with your submission and the maintainer reads it: it is the place to write "I left the item names alone, someone needs to decide on the wording".
A save sometimes reports that a few corrected texts were marked so that servers already running the plugin pick them up. That is normal, it is automatic, and there is nothing for you to do about it.
The second button: Commit only. For the day the batch is not finished: it records your work in your branch and stops there, nothing leaves your machine. You pick it up later and send it then.
That page is where the maintainer answers you and where you ask your questions — an undescribed placeholder, a doubt about the tone of a sentence.
6.5 Tell the developers​
Once the merge request exists, the editor writes a short message for you, ready to paste into the Discord channel the developers read: the link to the review, the plugin, the languages, how many texts you changed and the ticket concerned.
Click the message to select all of it, or use Copy the message. This step is the difference between work that has been sent and work that has been seen: without it, your merge request waits for somebody to think of looking.
7. When something goes wrong​
| What you see | What to do |
|---|---|
| The project list is empty | Your access has not been granted yet, or your token has expired. Re-read sections 2 and 3. |
| "Your access has expired" | A token only lives a few months. The editor reopens the step that makes a new one by itself: two minutes, and nothing you have translated is lost. |
| GitLab refuses your token | Almost always one of three causes: a piece is missing (copy it in one go, with no spaces around it), it has expired, or the api box was not ticked — a token without it can do nothing. |
| "A branch with that name already exists" | Nothing was created. Change what you typed — add the language, or the part of the plugin — or switch to the branch you had already started. |
| "This copy of the project is not on any branch" | Nothing can be written or sent from there. Name a branch, or switch to one of yours. Nothing on your computer is deleted. |
| "Your last save is … and will not be in a new branch" | You saved before creating your branch. Create it and carry on; the button in that message writes the maintainer the request to move that save across. |
| "Someone else changed the same branch after you started" | Your work is saved and intact; only the upload was refused. Tell the maintainer, who will reconcile the two versions. |
| "Someone else has already changed some of the same texts" | Nothing was written and nothing is lost. Send the list to the maintainer so they can decide which version to keep. |
| "The copy of the project on this computer still holds changes from an earlier session" | Branches can no longer be created or switched until that is sorted out. Your pending translations are safe and are not the cause: tell the maintainer. |
| "Some texts cannot be saved as they are" | The texts it lists carry a red message. Fix them and send again: nothing was written, pushed or proposed. |
| "This repository only has the reference language" | The file for your language does not exist yet, and only the maintainer can create it. |
| "GitLab could not be reached" | Check your connection and try again in a minute. Nothing was sent. |
| A configuration form instead of the translations | The repository has not been prepared for translators yet. This is not yours to do: tell the maintainer. |
| A Configuration banner across the top | A setting of the project is wrong and only the maintainer can fix it. Send them the line as it is; nothing of yours is lost. |
| A red card you do not understand | Copy details, and send that to the maintainer. The message always names the text it is about. |
| The editor will not start any more, or the page is dead | Check that the black window is still open, then reopen http://127.0.0.1:8080. If you closed it, just run the file again: nothing is lost. |
Who to ask​
- A question about a sentence to translate (what a placeholder means, the expected tone, an ambiguous word) → as a comment on your merge request. It is on the record, and the answer benefits everybody.
- A question about access, installation, the token, a ticket number → to the maintainer, directly, on Discord.
A minute spent asking always costs less than a wrong translation that lives for six months.
8. Going further​
- The guide built into the editor (top-right menu → Translator's guide…) — the detailed use of the table and the edit panel, in front of you while you work.
- Translations (installation) — the list of the 25 languages shipped with the plugin and how a server administrator picks theirs.
- Translations (code structure) — the developer side: where the files live, how the metadata you read in the Context column is written.
- Other ways to contribute — the other ways to help the project.