Conditioning, translating, regionalizing

A different value depending on the screen, the machine or the language.

A condition on a property

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

One component, two sizes depending on the screen. The list of conditions is on the Conditional display page.

A condition on the whole component

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

The component only exists if the condition is true. The full list is in Conditional display, and Combining several conditions explains and, or and parentheses.

ifexists and ifnotexists

These two do not test the machine but the presence of a file:

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

It is the clean way to handle games without box art — otherwise the slot stays empty.

Translating a text

A language suffix on the property is enough:

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

Recalbox takes the matching variant, and the suffix-free version if none matches.

What a suffix accepts

The region

This is what lets you write “Genesis” in the United States and “Mega Drive” in Europe. Same mechanism as the language, with an uppercase suffix — it is what Recalbox's official theme uses:

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

The three values are US, EU and JP. A property without a suffix applies to all regions.

⚠️ There is always an active region. On a fresh machine it is US: what you write without a suffix is what most people will see, and .EU or .JP only serve to depart from it.

The region is changed on the machine, in the interface settings — and Recalbox then re-reads the whole theme, as for an option. The studio offers the same choice, to see what each audience will see.

What it works on: EVERYTHING

There is no list of translatable properties. The suffix is examined on every property before the engine even knows which one it is — so all of them accept it:

<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" />        <!-- German runs longer -->
<box name="bandeau" color.JP="D62828" />

Both spellings support it — as an attribute (size.fr="…") as well as a sub-node (<size.fr>…</size.fr>) — and even the tag name (<text.fr name="…">). It also applies to an option's title and help.

⚠️ The localized version wins for good. Once a variant has been applied, the suffix-free version of the same property is refused, including in a file read later. An overlay can therefore not “take back” a property already localized: it must provide its own localized variant.

Loading a text from a file

text, scrolltext and markdown accept path instead of text: the content is then read from the file. Handy for a long presentation text.

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