Localization Format Strings
Localization Format Strings
If a string needs to update in real-time during gameplay, such as when displaying player names or working with a timer, format strings can be used as placeholders within localized translations.
Constructing Format Strings
Format strings consist of a parameter and an optional format specifier which controls how the parameter value is output/formatted.
| {NumJewels | : | int} |
 |
|
|
| Parameter | Optional format specifier |
Parameters can be either named or numbered. All parameters for a single entry must use the same style and can’t be a mix of named and numbered.
Using Format Specifiers
As stated above, an optional format specifier can be included in the format string. The following table lists each specifier and its intended purpose.
| Specifier | Type | Description | Example Output |
|---|---|---|---|
| translate | string | Attempts to translate the argument before concatenating (in the same context). This will only look for a literal Source match — it does not support recursive matching. | |
| int | number | Integer with optional negative sign; no thousand separators. | 1234 |
| fixed | number | Two decimals with decimal indicator, optional negative sign, and no thousand separators. | 1234.50 |
| num | number | Two decimals with decimal indicator, optional negative sign, and thousand separators. | 1,234.50 1 234,50 |
| HEX | number | Integer converted to hex; negative is converted to 64-bit two's complement. | 3FF |
| hex | number | Same as HEX, but lowercase. | 3ff |
| datetime | number | UTC timestamp as a number to universal user-readable format. | 2017-10-10 13:38:10 |
| iso8601 | number | UTC timestamp as a number to ISO-8601 format UTC time. | 2017-10-12T22:02:38Z |
| shorttime | number | UTC timestamp to local "hour:minute" format. | 1:45 PM 13:45 |
| shortdatetime | number | UTC timestamp to general date+time pattern with short time. | 10/10/2017 1:45 PM |
| shortdate | number | UTC timestamp to short date pattern. | 10/10/2017 2017-10-10 |
Non‑Localized Substitution
If a format specifier is not included, the parameter value will be displayed exactly as given. This is useful for direct substitution of strings that will not change between languages, for example proper names, titles, etc.
| C | D | E | F |
| Source | Example | es | |
| Hello {Player_Name}! | Hola {Player_Name}! | ||
| My name is {NPC_Name}. | Me llamo {NPC_Name}. | ||
| Example Input | English Output | Spanish Output |
|---|---|---|
| Hello new_storm! | Hello new_storm! | Hola new_storm! |
| My name is Diva Dragonslayer. | My name is Diva Dragonslayer. | Me llamo Diva Dragonslayer. |
Localized Substitution
When a string needs to be directly translated for different locales, the translate format specifier will look for an exact parameter match and substitute a translation, assuming it exists in the localization portal.
| C | D | E | F |
| Source | Example | es | |
| I am from {Country_Name:translate}. | Soy de {Country_Name:translate}. | ||
| Brazil | Brasil | ||
| London | Londres | ||
| Germany | Alemania | ||
| Example Input | English Output | Spanish Output |
|---|---|---|
| I am from Brazil. | I am from Brazil. | Soy de Brasil. |
| I am from London. | I am from London. | Soy de Londres. |
| I am from Germany. | I am from Germany. | Soy de Alemania. |
Number Substitution
To output a variable number value in a particular format, use specifiers like int, fixed, or num.
| C | D | E | F |
| Source | Example | es | |
| {race_time:fixed} seconds | {race_time:fixed} segundos | ||
| ${1:num} cash and {2:int} jewels | ${1:num} dinero y {2:int} joyas | ||
| Example Input | English Output | Spanish Output |
|---|---|---|
| 75.202844 seconds | 75.20 seconds | 75,20 segundos |
| $2500.5 cash and 99.8 jewels | $2,500.50 cash and 100 jewels | $2.500,50 dinero y 100 joyas |
Sample Implementation
Consider the practical example of displaying a variable amount of jewels across multiple languages. To implement this in a game:
- Download the .csv spreadsheet from the localization portal as outlined
articles/localization portal additional features#localizing-with-csv-files|here. - Insert a Source string with a named format string, along with translations for supported languages like es (Spanish) and pt (Portuguese).
| C | D | E | F | G |
| Source | Example | es | pt | |
| {NumJewels} jewels | {NumJewels} joyas | {NumJewels} jóias | ||
- Add a GUI object to your game, for example a
TextLabelwith aTextLabel/Text|Textproperty of 100 jewels.
- Upload the spreadsheet and playtest the game as outlined
articles/localization portal additional features#upload-csv-file|here. The translations should appear on the in-game GUI instance, including the variable 100.
