Text XML syntax

Text XML syntax

This page explains what features we have available when using text ingame. It should be noted that some is heavily modded, so this doesn't automatically apply to all mods, through some does.

All text used ingame is stored in Assets/XML/Text. We no longer read vanilla text xml files. The files are encoded in itf-8. If a text editor offers utf-8 with and without BOM, then pick no BOM.

Each line consist of a Tag, English and possibly other lines.

Example:

<TEXT>
	<Tag>TXT_KEY_EUROPE_SCREEN_DOCKS</Tag>
	<English>Docks</English>
	<French>Docks</French>
	<German>Docks</German>
	<Italian>Moli</Italian>
	<Spanish>Muelles</Spanish>
	<Russian>Доки</Russian>
</TEXT>

Tag is the key, which the game uses to look up the string in question. When reading, the game will only load the line matching the language the player has selected. If the language isn't present, then English will be used. This way as long as Tag and English are present, the game will work (unlike vanilla, which crashes if languages are missing).

Order doesn't matter, but it is more human readable to obey the standard order given by vanilla.

Control of which languages to use ingame is set in Assets/XML/Interface/Languages.xml.

Game engine supports codepage 1250 to 1258, which can roughly be summed up as all European languages as well as Arabic and Hebrew. However each codepage requires setting up a GameFont and at the time of writing, we only have that for codepage 1251 and codepage 1252.

Arguments

Code is entered in code like this:

// C++
gDLL->getText("TXT_KEY_EVENT_TRIGGER_ERROR", arg1.c_str(), arg2.c_str(), arg3.c_str())

# python
localText.getText("TXT_KEY_POPULATION", ())
localText.getText("TXT_KEY_EXAMPLE", (2, 4))

In other words arguments can optionally be added. They can be accessed by using a printf like syntax.

Keyword	Meaning	note
%d	int value
%D	int value	same as %d?
%f	show GameFont icon	needs an int argument
%F	show GameFont icon	needs an int argument
%s	string
%%	%	displaying % in text

TODO: figure out if there is any difference between lowercase and uppercase

After the keyword there has to be the index of the argument setting it and optionally a string to tell translators what it is. Note that the arguments are 1 indexed, so there is no %d0.

Examples: %d1 %s2_leader_name

EXE bug warning

Due to experience we know that each string is only inserted once. If we use %s1 twice, the second one isn't replaced with the argument. The only known workaround is using %s1 and %s2 and then give the same argument twice.

Genders and plural

Each line has two ways of being entered.

<English>Docks</English>
<English>
	<Text>Docks</Text>
	<Gender>Male</Gender>
	<Plural>0</Plural>
</English>

There is the short form of just a line and a long one where it gains two attributes. Default Gender is "N" and default Plural is "false".

More complex setups exist in vanilla. (TODO: figure out precisely how those are used)

<German>
	<Text>Aztekenreich:Aztekenreich:Aztekenreich</Text>
	<Gender>Neuter:Neuter:Neuter</Gender>
	<Plural>0:0:0</Plural>
</German>
<French>
	<Text>Travailleur:Travailleuse:Travailleurs:Travailleuses</Text>
	<Gender>Male:Female:Male:Female</Gender>
	<Plural>0:0:1:1</Plural>
</French>
<Italian>
	<Text>Industrioso:Industriosa</Text>
	<Gender>Male:Female</Gender>
	<Plural>0</Plural>
</Italian>

Keyword :

A string can be split up by using : to separate multiple parts.

<English>farmer:farmers</English>

In this case it becomes singular:plural. Which one to use depends on the first argument. 3 : can be used, in which case it becomes singular male, singular female, plural male, plural female.

NUM keyword is used to set parts of a line depending on an argument. Example:

<English>Growing (%d1 [NUM1:Turn:Turns])</English>

Square bracket keywords

It's possible to add keywords or even primitive code inside [].

Keyword	meaning	example
[SPACE]
[[NEWLINE]
[ICON_BULLET]	bullet char
ICON_PRODUCTION
color control	Ability to change text color	[COLOR_HIGHLIGHT_TEXT]some text[COLOR_REVERT]
LINK	clickable link to a pedia page	[LINK=YIELD_FOOD]food[/LINK]

TODO: make a list of all color keywords.