Conditionner, traduire, régionaliser

Une valeur différente selon l’écran, la machine ou la langue.

Une condition sur une propriété

<text name="titre">
  <fontSize if="crt">0.09</fontSize>
  <fontSize if="!crt">0.05</fontSize>
  <color>FFFFFF</color>
</text>

Un seul composant, deux tailles selon l’écran. La liste des conditions est dans la page Afficher sous condition.

Une condition sur le composant entier

<image name="filtre" if="crt">
  <path>${root}/data/arts/scanlines.png</path>
</image>

Le composant n’existe que si la condition est vraie. La liste complète est dans Afficher sous condition, et Combiner plusieurs conditions explique et, ou et les parenthèses.

ifexists et ifnotexists

Ces deux-là ne testent pas la machine mais la présence d’un fichier :

<image name="jaquette">
  <path ifexists="${game.media.imagepath}">${game.media.imagepath}</path>
  <path ifnotexists="${game.media.imagepath}">${root}/images/pas-dimage.png</path>
</image>

C’est la façon propre de gérer les jeux sans jaquette — sans quoi la case reste vide.

Traduire un texte

Un suffixe de langue sur la propriété suffit :

<text name="bienvenue">
  <text>Bienvenue</text>
  <text.en>Welcome</text.en>
  <text.es>Bienvenido</text.es>
</text>

Recalbox prend la variante qui correspond, et la version sans suffixe si aucune ne correspond.

Ce qu’un suffixe accepte

La région

C’est ce qui permet d’écrire « Genesis » aux États-Unis et « Mega Drive » en Europe. Même mécanisme que la langue, avec un suffixe en majuscules — c’est ce qu’emploie le thème officiel de Recalbox :

<box name="fond"
     color.US="2E447C"
     color.EU="7C2E44"
     color.JP="447C2E" />

Les trois valeurs sont US, EU et JP. Une propriété sans suffixe vaut pour toutes les régions.

⚠️ Il y a toujours une région active. Sur une machine neuve c’est US : ce que vous écrivez sans suffixe est ce que verra la plupart des gens, et .EU ou .JP ne servent qu’à s’en écarter.

La région se change sur la machine, dans les propriétés de l’interface — et Recalbox relit alors le thème en entier, comme pour une option. Le studio propose le même choix, pour voir ce que verra chaque public.

Sur quoi ça marche : sur TOUT

Il n’existe aucune liste de propriétés traduisibles. Le suffixe est examiné sur chaque propriété avant même que le moteur sache de laquelle il s’agit — donc toutes l’acceptent :

<text name="titre" text.fr="Bienvenue" text.es="Bienvenido" />
<image name="logo" path.US="genesis.png" path.EU="megadrive.png" />
<text name="mention" fontSize.de="0.03" />        <!-- l’allemand est plus long -->
<box name="bandeau" color.JP="D62828" />

Les deux écritures le supportent — en attribut (size.fr="…") comme en sous-nœud (<size.fr>…</size.fr>) — et même le nom de la balise (<text.fr name="…">). Il vaut aussi pour le title et le help d’une option.

⚠️ La version localisée gagne définitivement. Dès qu’une variante a été appliquée, la version sans suffixe de la même propriété est refusée, y compris dans un fichier lu plus tard. Une surcouche ne peut donc pas « reprendre la main » sur une propriété déjà localisée : elle doit fournir sa propre variante localisée.

Charger un texte depuis un fichier

text, scrolltext et markdown acceptent path à la place de text : le contenu est alors lu dans le fichier. Pratique pour un long texte de présentation.

<markdown name="apropos">
  <path>${root}/data/textes/apropos.md</path>
</markdown>