Traduire un mod

1. Ajouter le catalogue #

Prérequis : un projet Kotlin/Native configuré et un modèle, un service ou une fenêtre d’outil existants. Ce guide traduit leurs textes visibles sans changer leurs identifiants, leurs réglages ou leurs règles.

Créez assets/translations.json. Le plugin copie le catalogue dans le paquet et le SDK le valide au chargement. Chaque mod possède ses textes : une même clé peut avoir une traduction différente dans deux mods.

{
  "fallback": "en",
  "languages": {
    "en": {
      "maintenance": "Maintenance mode",
      "maintenance.help": "Enable the maintenance mode of this signal.",
      "repeat": "Repeat",
      "count.one": "{count} signal",
      "count.many": "{count} signals"
    },
    "fr": {
      "maintenance": "Mode maintenance",
      "maintenance.help": "Activer le mode maintenance de ce signal.",
      "repeat": "Répéter",
      "count.one": "{count} signal",
      "count.many": "{count} signaux"
    }
  }
}

fallback choisit la langue de repli ; en est utilisé si ce champ est omis. Cette langue doit exister et contenir toutes les clés. Les autres langues peuvent être incomplètes : une clé absente reprend le texte de repli.

Vous choisissez les clés : mod.name, window.clock et title sont des exemples, pas des noms réservés. Une clé n’a d’effet que lorsqu’un appel tr("clé") la transmet à un texte visible. Ajouter mod.name au JSON ne renomme donc pas automatiquement le mod ; ajouter window.clock ne crée ni fenêtre ni raccourci.

2. Traduire les contrôles #

Importez nimby.tr ou nimby.*. Utilisez tr dans les titres, libellés, aides et messages. Les identifiants de modèles, réglages, actions, fenêtres et services restent des chaînes fixes.

package wiki.translations

import nimby.*

// Identifiers stay stable; only the displayed text is translated.
val maintenance = Checkbox(
    "maintenance", tr("maintenance"), tr("maintenance.help")
)

fun summary(count: Int): String =
    tr(if (count == 1) "count.one" else "count.many", "count" to count)

fun createTranslatedTool(): ToolMod = toolMod("my-translated-tool", "My tool") {
    service("message.v1") { request ->
        showPanel(request, summary(3), listOf(
            ToolButton(request.originAction, tr("repeat"))
        ))
    }
}

L’extrait définit une case réutilisable et un outil de démonstration. Ajoutez la case à votre modèle et exposez message.v1 par une action optionnelle pour afficher le panneau. Le JSON seul ne crée aucun contrôle.

Dans Options → NRF Hub, le nom du groupe vient du titre déclaré par toolMod ou signalMod. Avec toolMod(modInfo), il s’agit de modInfo.title, généré depuis name dans mod.json. metadata(name = tr("mod.name")) traduit le nom dans les listes et fiches du jeu ; il ne remplace pas ce titre de groupe. Le title transmis à window nomme à la fois la fenêtre et sa ligne dans Raccourcis.

Pour un groupe BB Timechange, utilisez par exemple tr("window.clock") avec « Date et heure » pour le titre de la fenêtre. La ligne reste courte, sans répéter « BB Timechange — Date et heure ». Gardez son identifiant "clock" inchangé dans les deux langues et lors des mises à jour : changer le libellé ne doit pas créer une nouvelle préférence de raccourci.

3. Paramètres et pluriels #

tr("count.many", "count" to 3) remplace {count} par 3. Les valeurs passent par toString : formatez nombres et dates avant de les fournir si nécessaire. Une même clé conserve les mêmes paramètres dans toutes les langues. {{ et }} affichent des accolades littérales.

Le SDK ne choisit pas automatiquement un pluriel. Déclarez une clé par formulation et choisissez-la en Kotlin, comme summary dans l’extrait. Le paramètre reste du texte, sans seconde résolution de traduction.

Langue active et repli #

Les contrôles suivent la langue du jeu, indépendamment de Windows ou du Hub. Les codes usuels eng et fra correspondent à en et fr. Casse et séparateurs sont normalisés : FR_ca devient fr-ca.

• Langue exacte, par exemple fr-ca.
• Puis langue principale, par exemple fr.
• Puis fallback du mod pour cette clé.
• Référence toujours absente ou invalide : [clé] rend le problème visible.

Une langue indisponible utilise le repli. Le changement de langue actualise les textes sans réinitialiser les réglages. Dans une fenêtre ouverte, il ne remplace pas la saisie en cours ; une nouvelle publication showWindow remplace en revanche le formulaire par les valeurs de votre outil.

Vérifier les deux langues #

Utilisez du JSON UTF-8 strict : aucune clé en double, virgule finale ou commentaire. verifyNativeMod contrôle aussi le catalogue du paquet sans ouvrir le jeu. Un catalogue invalide empêche le chargement du mod avec une erreur dans le journal.

• Compiler, vérifier le paquet puis l’activer dans une partie de test.
• Ouvrir les panneaux en français et en anglais ; vérifier textes longs, aides et pluriels.
• Tester une langue non traduite pour vérifier le repli.
• Après un changement du JSON, reconstruire et recharger le mod. Changer de langue ne relit pas le fichier.