From Europa Universalis 4 Wiki
Jump to navigation Jump to search

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[edit | edit source]

EU4 uses a format similar to YAML. It looks 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"

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[edit | edit source]

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
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
0.5 -> 50%
* conversion of value to SI units
1000 -> 1K
1000000 -> 1M
= Prepend '+' if the value is positive and '-' for negative
10 -> +10
-10 -> -10
0..9 Number of decimals
10 -> 10.000
10.12345 -> 10.123
+ Colors values green if positive, yellow if zero, red if negative
10 -> 10
0 -> 0
-10 -> -10
- Colors values red if positive, yellow if zero, green if negative
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[edit | edit source]

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

Namespaces[edit | edit source]

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:


Scopes[edit | edit source]

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
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)
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[edit | edit source]

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[edit | edit source]

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

Keys[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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 filesList of event pictures
Scripting Scripted functionAdvisorsAgesBookmarksBuildingsCasus belliColonial regionsCountriesCultureDecisionsDefinesDiplomatic actionsDisastersEmpire of ChinaEstatesEventsFactionsGovernmentGovernment MechanicsGreat projectsHistoryHoly Roman EmpireIdea groupsInstitutionsMercenariesMissionsModifiersNation designerOn ActionsParliamentPeace treatiesPoliciesRebel typesReligionSubject typesTechnologyTrade companiesTrade goodsUnits
Map MapMap Modding Quick ReferenceNation designerRandom New WorldTrade nodes
Graphics 3D ModelsInterfaceGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumJoroDox mod making toolMod structureTroubleshootingThe ValidatorRun files
Guides Adding a provinceMap Modding Quick ReferenceSave-game editingScripting Tutorial