From Europa Universalis 4 Wiki
Jump to navigation Jump to search

Localisation files link values in the eu4 files to actual 'texts' or 'strings', any value can be placed in any file, however it is better to keep similar key: value pairs in the same file

EU4 uses a different localisation system compared to previous Paradox games. It uses a format similar to YAML. It will look something like this:

 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"
Template-info.png Note the extra space at the beginning of each line except the first, which is needed since each row is a subnode to the node called “l_english”.

The number after the colon is a version number.

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 you will receive Missing Localisation! instead of your intended text-string. 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.

Template-info.png Localisation-files use UTF-8-BOM only, while the game's other text-files (.txt) should be encoded in ANSI and never with BOM.

While the encodings listed above, UTF-8-BOM and ANSI, both allow for a wide range of characters, only characters that are contained within the CP-1252 set of characters will display correctly in-game.

Also note that there must not be any space before the : that separates key and value. If so, the game will fail to parse all the lines that will follow the broken one.


key: "value" → Working case. ✔

key : "value" → Non-working case. ✘

In order to localize a string with quotes within it, these must first be escaped, like so:

 STRING_WITH_QUOTES: "This string contains \"quotes\", therefore it's awesome!"

(NB: this appears to not actually be the case, see for example flavor_bur.21.t in /Europa Universalis IV/localisation/flavor_events_l_english. It appears no two localisation files can have the same file name.)

If you are creating a new localisation file for your mod, 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.).

New formatting standard

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
% conversion of value to percent
* conversion of value to SI units
= Prepend '+' if the value is positive and '-' for negative
0..9 Number of decimals
W,B,G,R,b,g,Y,M,T,O,l 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
+ Colors values green if positive, yellow if zero, red if negative
- Colors values red if positive, yellow if zero, green if negative

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.


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


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.


We can use an additional scope:


We can use multiple 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
Monarch country character Ruler
Consort country character Consort
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)
TradeCompany country country(?) Trade company subject
Dip_Advisor country character Diplomatic advisor
Adm_Advisor country character Administrative advisor
Mil_Advisor country character Military advisor


Command Scope Description Example
GetAreaName province Area of a province [This.GetAreaName]
GetContinentName province Continent of a province [Root.Capital.GetContinentName]
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.
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]


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
$ARMY_REFORMER$ Advisor's name
$ARMY_ORGANISER$ Advisor's name
$ARTIST$ Advisor's name
$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
$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
$DIPLOMAT$ Advisor's name
$DYNASTY$ country Displays root country's ruler's dynasty Tudor
$EMPERORNAME$ Holy Roman Emperor?
$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_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
$MASTER_OF_MINT$ Advisor's name
$MONARCH$ country Displays root country's ruler's name Henry VIII
$MONARCHTITLE$ country Displays root country's ruler's title King
$NAVY_REFORMER$ Advisor's name
$NATURAL_SCIENTIST$ Advisor's name
$NAVIGATOR$ Advisor's name
$NCARDINALS$ integer number of cardinals
$OVERLORD$ country name subject nation's liege lord
$PERYEAR$ Yearly Separatism decrease
$PROVINCECAPITAL$ province Displays root province's capital city Paris
$PROVINCECULTURE$ province Displays root province's culture
$QUARTERMASTER$ Advisor's name
$RECRUITMASTER$ Advisor's name
$SPYMASTER$ Advisor's name
$STATESMAN$ Advisor's name
$THEOLOGIAN$ Advisor's name
$TRADER$ Advisor's name
$TREASURER$ Advisor's name
$UNTIL$ Year Separatism ends
$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.


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£ Yes
No Indicator £no£ No
Monarch power Administrative Power £adm£ Administrative power.png
Diplomatic Power £dip£ Diplomatic power.png
Military Power £mil£ Military power.png
Ducats ¤ Gold Icon.png
Manpower £icon_manpower£ Manpower.png
Sailors £icon_sailors£ Sailors.png
Ships Heavy Ships £big_ship_icon_small£ Heavy ship.png
Light Ships £light_ship_icon_small£ Light ship.png
Galleys £galley_icon_small£ Galley.png
Transports £transport_icon_small£ Transport.png
Land Units Infantry £infantry_icon_small£ Infantry.png
Cavalry £cavalry_icon_small£ Cavalry.png
Artillery £artillery_icon_small£ Artillery.png

Importing/exporting text to translate it

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


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:


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


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:

Modding localisation files.jpg

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.

Documentation EffectsTriggersModifiersScopesVariablesLocalisationCustomizable localizationRun files
Scripting Scripted functionAdvisorsAgesBookmarksBuildingsCasus belliColonial regionsCountriesCultureDecisionsDefinesDiplomatic actionsDisastersEstatesEventsFactionsGovernmentGreat projectsHistoryIdea groupsInstitutionsMercenariesMissionsModifiersNation designerHoly Roman EmpirePoliciesReligionRebel typesSubject typesTechnologyTrade companiesTrade goodsUnits
Map MapNation designerRandom New WorldTrade nodes
Graphics 3D ModelsInterfaceGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumJoroDox mod making toolMod structureTroubleshootingThe ValidatorRun files
Guides Adding a provinceSave-game editing