Localisation

Localisation files link the in-code names for things in the eu4 files to actual text, using different text depending on which language eu4 is set to use.

Format

EU4 uses a format similar to YAML. It looks something like this:

l_english:
 MENU_MESSAGES_DISABLE_ALL:0 "Disable all"
 FILTER:0 "Filter"
 TO_ME:0 "To me"
 FROM_ME:0 "From me"
 INTERESTING:0 "Interesting"
 OTHERS:0 "Others"
 hre_province_restored:0 "Territory restored to the Empire"
 DECAY:0 "Decay"

The following rules apply to all localisation files:

• Localisation files can be placed in both the "localisation" and "localization" folder.
• To replace existing localisations from vanilla or other mods, place your edited localisations into "localisation/replace".
• The filename must end with _l_english.yml, for example mymod_l_english.yml. When localising for languages other than English, replace english with that language (french, etc.).
• The file must be encoded as UTF-8 with a byte order mark (UTF-8-BOM). If a localisation file is encoded as a single-byte encoding such as ISO 8859-1, the game will fail to read the file and display the localisation key. To ensure the correct encoding, copy a vanilla localization file or use an advanced editor like Notepad++ to set it using the Convert to … option within the encoding menu. The game's other text files (.txt) should be encoded in CP-1252/ANSI and never with BOM.
• The first line of the file must be l_english: (replace "english" with other languages as before).
• As in other files, # outside of quotes denotes a line comment - everything after it in that line is not read by eu4 as long as it doesn't contain a double quote ("). You can use # inside quotes, in your text.
• Empty lines are ignored (including whitespace and comments).
• All other lines must have the following format:

1. Exactly one space
2. A localisation key which may only contain the following characters: A-Z, a-z, 0-9, '_', '.', '-'. This localisation key is used by the game to find where the text is supposed to be used. In some cases (e.g. event titles, descriptions, option names) the key is specified in the other game files, in other cases it is derived from the code object name (e.g. a decision called test_decision will automatically use test_decision_title for the localisation of its title and test_decision_desc for the description).
3. A colon (:)
4. Optional: A number. Has no meaning, is used by eu4 devs to remember the 'version' of this text.
5. Exactly one space
6. A double quote (")
7. The localisation text. It can use almost any UTF8 character, but only characters that are contained within the font that the UI element uses can be displayed properly. For vanilla fonts, that's the CP-1252/ANSI set of characters. Newlines must be written as \n and backslashes must be written as \\. Double quotes within the text work fine (old game versions require them to be written as \"). Having a backslash followed by anything else will break the localisation.
8. A double quote (")

• Deviation from this format can break the localisation file and cause all following lines to be ignored.
• Any localisation key can be placed in any file, same goes for replacing localisations, however it is generally best to keep similar key: value pairs in the same file (and using the same filenames that you are replacing) to make it easy to find them later on.

Text formatting

The localization system also has support for formatting text in the localization strings instead of the C++ code. In order to format a variable, type '§' followed by the wanted formatting rules and then end the expression with '§!'.

The following formatting rules are implemented:

Code	Effect	Usage	Example
W,B,G,R,b,g,Y, M,T,O,l,J,P	Colours the text      W = White      B = Blue      G = Green      R = Red      b = Black      g = Grey      Y = Yellow      M = Marine      T = Teal      O = Orange      l = Lime      J = Jade      P = Purple	§<COLOR_CODE>Coloured Text§!	"This is regular text, §Rand this text is red§!" would appear as This is regular text, and this text is red.
The following entries can be combined to produce the desired results
%	conversion of value to percent	$VAL|%$!	0.5 -> 50%
*	conversion of value to SI units	$VAL|*$!	1000 -> 1K 1000000 -> 1M
=	Prepend '+' if the value is positive and '-' for negative	$VAL|=$!	10 -> +10 -10 -> -10
0..9	Number of decimals	$VAL|<1..9>$!	$VAL|3$! 10 -> 10.000 10.12345 -> 10.123
+	Colors values green if positive, yellow if zero, red if negative	$VAL|+$!	10 -> 10 0 -> 0 -10 -> -10
-	Colors values red if positive, yellow if zero, green if negative	$VAL|-$!	10 -> 10 0 -> 0 -10 -> -10

As an example, if we want to convert a fixed point value to percent with one decimal, color it green if it is positive, we can now write it as $VAL|%2+$!. If we want to color a value yellow with 3 decimals and add a '+' sign if the value is positive, we could write it as §=Y3$VAL$§! etc.

Variables

We can display localisation dynamic information (like the religion of a province) in a couple of ways.

Namespaces

This is the cleaner, newer, flexible way of calling data to display in localisation. It uses a system similar to scope from event modding, though keep in mind it uses a unique set, outlined below. It will be familiar to anybody who has done object-oriented programming.

Some examples - notice how the game is directed from an event's Root/From and through the scopes until we find the information we need.

[Root.GetAdjective]

We can use an additional scope:

[FRA.Monarch.GetTitle]

We can use multiple scopes:

[From.From.From.Owner.Monarch.GetHerHim]

Scopes

Operator	From Scope	To Scope	Description
Capital	country	province	capital province
ColonialParent	country	country	Overlord of a Colonial nation
Culture	country & province	culture	Culture of a country
Dynasty	character	dynasty	royal house of a ruler
From			FROM province or country
Heir	country	character	Heir
Location
Monarch	country	character	Ruler
Consort	country	character	Consort
Overlord	country	country	Subject's overlord
Owner	province	country	Owner of a province
Religion	country & province	religion	Religion
Root			ROOT province or country
TAG		country	We can just directly scope to a country (e.g. FRA)
This
TradeCompany	country	country(?)	Trade company subject
Dip_Advisor	country	character	Diplomatic advisor
Adm_Advisor	country	character	Administrative advisor
Mil_Advisor	country	character	Military advisor
event_target_name			Scopes to the called event target (name must be all lower case)

Commands

Command	Scope	Description	Example
GetAreaName	province	Area of a province	[This.GetAreaName]
GetRegionName	province	Region of a province	[This.GetRegionName]
GetContinentName	province	Continent of a province	[Root.Capital.GetContinentName]
GetSuperRegionName	province	Superregion name of a province	[Root.Capital.GetSuperRegionName]
GetAdjective	country	country adjective, e.g. Spanish
GetAdm	character	Administration ability.
GetCapitalName	province	Gets a province's city name (e.g. Paris)	[From.Capital.GetCapitalName]
GetDate	none	doesn't need a scope, returns current date in yyyy.mm.dd format	[GetDate]
GetDip	character	Diplomatic ability
GetFlagshipName	country	Country's Flagship Name	[Root.GetFlagshipName]
GetGroupName	culture	culture group e.g. British
	religion	religion group e.g. Christian
GetHerHim	character	"her"/"him"
GetHerHimCap	character	"Her"/"Him" capitalised
GetHerHis	character	"her"/"his"
GetHerHisCap	character	"Her"/"His" capitalised
GetHerselfHimself	character	"herself"/"himself"
GetHerselfHimselfCap	character	"Herself"/"Himself" capitalised
GetSheHe	character	"he/"she"
GetSheHeCap	character	"He/"She" capitalised
GetSisterBrother	character	"sister/"brother"
GetMil	character	Military ability.
GetMonth	none	doesn't need a scope, returns current month	[GetMonth]
GetName	all	Gets main name for almost any object; England, Catholicism, Henry VIII, Tudors...
GetValue	all	Prints the value of an object, be it a string or integer.
GetTag	country	returns the TAG of the scoped country (can be used with @ to display the flag)	@[Root.GetTag]
GetTitle	character	e.g. King, President
GetTradeGoodsName	province	names Trade goods produced in province
GetWomanMan	character	"man/woman"
GetYear	none	doesn't need a scope, returns current year	[GetYear]
GovernmentName	country	Gets a country's government name (e.g. Kingdom)	[Root.GovernmentName]
GetXEDip	country	French language only : Permet d'accorder féminin ou masculin	excellent[Root.GetXEDip]
GetErEreDip	country	French language only : Permet d'accorder le mot 'conseiller'	conseill[Root.GetErEreDip]

@TAG

@TAG (e.g @HAB) results in the flag of that tag, this can be used with @[Root.GetTag] and similar localisation scoping.

Keys

There are a number of scalar identifiers that appear in the game's existing localisation files. These aren't very flexible or pretty, but we can use them if they have the correct scope.

Some of these probably don't work with events, missions etc. because they need to be given other data through the game's code.

Key	Scope	Description	Example Value
$ADM$
$ARMY_REFORMER$		Advisor's name
$ARMY_ORGANISER$		Advisor's name
$ARTIST$		Advisor's name
$BASE$
$CAPITAL$	country	Displays root country's capital province	Île-de-France
$CAPITAL_CITY$	country	Displays root country's capital city	Paris
$COLONIAL_GOVERNOR$		Advisor's name
$COMMANDANT$		Advisor's name
$CONTINENT$
$CONTROLLERNAME$	province	Displays root province's controller (winner of siege)	England
$COUNTRY$	country	Displays root country's name	France
$COUNTRY_ADJ$	country	Displays root country's adjective	French
$COUNTRY_RELIGION$	country	Displays root country's religion	Catholic
$CULTGROUP$		Culture group. Unsure if it can be used in events
$CULTURE$	country	Displays root country's primary_culture	Francien
$DATE$
$DIPLOMAT$		Advisor's name
$DYNASTY$	country	Displays root country's ruler's dynasty	Tudor
$EFFECTS$
$EMPERORNAME$		Holy Roman Emperor?
$FORTIFICATION_EXPERT$
$FROM$
$FROMCOUNTRY$
$FROM_COUNTRY$
$GRAND_CAPTAIN$		Advisor's name
$HEIR$			Henry Tudor
$HEIR_ADJ$		heir possessive adjective	his/her
$HEIR_CAP_ADJ$		capitalised heir possessive adjective	His/Her
$HEIR_DYNASTY
$HEIR_O_PRONOUN$		heir object pronoun	him/her
$HEIR_CAP_O_PRONOUN$		capitalised heir object pronoun	Him/Her
$HEIR_S_PRONOUN$		heir subject pronoun	he/she
$HEIR_CAP_S_PRONOUN$		capitalised heir subject pronoun	He/She
$INQUISITOR$		Advisor's name
$KEY$
$LIKELYREBELS$	province
$LOCATION$
$LOYALNAMES$
$MASTER_OF_MINT$		Advisor's name
$MESSENGER$
$MONARCH$	country	Displays root country's ruler's name	Henry VIII
$MONARCHTITLE$	country	Displays root country's ruler's title	King
$NAME$
$NAVY_REFORMER$		Advisor's name
$NATION$
$NATURAL_SCIENTIST$		Advisor's name
$NAVIGATOR$		Advisor's name
$NCARDINALS$		integer number of cardinals
$NUM$
$OVERLORD$	country	name subject nation's liege lord
$OWNERNAME$
$PERYEAR$		Yearly Separatism decrease
$PLAYER$
$PRICE$
$PROV$
$PROVINCE$
$PROVINCECAPITAL$	province	Displays root province's capital city	Paris
$PROVINCENAME$
$PROVINCECULTURE$	province	Displays root province's culture
$QUARTERMASTER$		Advisor's name
$RANDOM_OLD_MONARCH$
$REBELNAME$
$RELIGION$
$RECRUITMASTER$		Advisor's name
$RULER_ADJ$$
$SPYMASTER$		Advisor's name
$STATESMAN$		Advisor's name
$THEOLOGIAN$		Advisor's name
$TRADER$		Advisor's name
$TREASURER$		Advisor's name
$TYPE$
$UNIT$
$UNTIL$		Year Separatism ends
$VAL$
$WHO$
$YEAR$	country	Displays the current year	1444

Replace localisation keys

To replace vanilla localisation, create a folder inside the localisation folder named replace. In this folder place your localisation files containing the vanilla localisation keys you want to replace. You can also mod localisation in the same way as anything else. Localisation is ignored in calculating the checksum.

Cultural province names

If "Use dynamic province names" is turned on, province names change from their values in the localisation folder based on the culture of the current owner. These names are listed under common/province_names, which can have one file per tag, culture, or culture group. Each file contains a list, each entry being a province number, an equals sign, and 1-2 quoted names. One quoted name will replace the province name, two quoted names (enclosed in braces) will use the first one as province name and second one as province capital name. For example, from british.txt:

873 = "Astoria"
893 = { "New Orleans" "New Orleans" }
894 = "Ecore Fabre"
896 = "Grand River"
897 = { "Little Rock" "Little Rock" }
899 = { "Ozarks" "Springfield" }
908 = { "Minnesota" "St. Paul" }
910 = "Red Lake"
911 = { "Upper Peninsula" "Escanaba" }

The most specific name available will be used. For example, province 282, normally called Yedisan and owned by Crimea in 1444, is called Hocabey if owned by a Turkish country; if it's owned by the Ottomans, however, it's called Özü, even if they're Turkish.

Icons

Graphical icons are usually inserted by surrounding a text key with the pound symbol (£), but there are some exceptions (the ducats icon, for example).

The text key refers to a spriteType name defined somewhere in a .gfx file.

You should be able to any spriteType, but take care that the image you intend to use is appropriately-sized for inline text usage.

Default icons can be found in interface/texticons.gfx

Common Icons
Category	Description	Key	Icon
General	Yes Indicator	£yes£
	No Indicator	£no£
Monarch power	Administrative Power	£adm£
	Diplomatic Power	£dip£
	Military Power	£mil£
Resources
	Ducats	¤
	Manpower	£icon_manpower£
	Sailors	£icon_sailors£
Ships	Heavy Ships	£big_ship_icon_small£
	Light Ships	£light_ship_icon_small£
	Galleys	£galley_icon_small£
	Transports	£transport_icon_small£
Land Units	Infantry	£infantry_icon_small£
	Cavalry	£cavalry_icon_small£
	Artillery	£artillery_icon_small£

Importing/exporting text to translate it

To export, create a shortcut of the game exe. Right click and choose properties, and enter

-export_loc

last in target. This will create a folder in your game folder called "customizable_localization". These files can now be opened and translated. Put your translation in the language column that applies. If yours are not there, you can rename one of the others.

If you're using Steam, instead of creating a shortcut, right click on EU4 in Steam and choose properties. On the General tab, click "Set Launch Options..." and enter the above. Remember to remove it afterwards, since the game doesn't actually start with this option.

To import, create a folder next to the recently created and name it localization_translated. Put your files there. They must be named l_language (name of the language) in the start of the file name and import with this line:

-import_loc

You will then get a bunch of files in your documents folder, in a new folder named

localization_import

These files need to be copied and pasted into the localization folder in the game. When you have done both export and import, the structure will look something like this:

All in all, if you are translating for example our English text to another language, you won't need to care that much about the formatting, just mimic what we wrote. If you are adding text for your mod, you may want to give the first two headlines some extra attention.

Modding

Audio

Music • Sound