From Hearts of Iron 4 Wiki
Jump to navigation Jump to search

HOI4 uses the modified YAML localization system used by modern Paradox games.


The basic format is as follows:

 <key>: "Text here"

Spaces can be omitted.
Typically you will want to use l_english. The key refers to the script name of the object you are localizing.
The game also contains version branding, allowing you to mark the version of the localisation with a number, which has no effect in-game, as such:

 <key>:<number> "Text here"

Here is an example of a localized equipment:

 infantry_equipment: "Infantry Equipment"
 infantry_equipment_short: "Inf. Eq."
 infantry_equipment_desc: "This is infantry equipment"

You must follow the syntax exact when adding localization, otherwise the parser will break and you will have broken localization.
The .yml format is a simple text file, to save as it simply save as All types and type in the .yml suffix.
Make sure the .yml file is encoded as UTF-8-BOM. This is easy to check and to change in Notepad++ or other similar programs.
The filename must end with _l_<language>.yml, such as modname_l_french.yml or foo_l_english.yml, otherwise the file will not load.

Special characters[edit]

New line[edit]

You may want to force a string to display with a line break. To do this, include the \n character where you want the line break.

 example_key: "This is line 1\nThis is line 2\nThis is line 3."

Formatting characters[edit]

Various characters can be added to a string to alter its presentation ingame.

The following formatting characters are implemented:

Code Effect
§% Converts following value to percent.
§* Converts following value to SI units.
§= Prefixes following value with + if the value is positive or - if it is negative.
§0..9 Controls the number of decimals to display.
§W Colors the text white.
§G Colors the text green.
§R Colors the text red.
§B Colors the text blue.
§Y Colors the text yellow.
§b Colors the text black.
§C Colors the text light blue (cyan).
§g Colors the text light gray.
§T Colors the text white (same as §W).
§H Colors the text yellow (same as §Y).
§O Colors the text orange.
§L Colors the text a dirty grey colour.
§+ Colors the following value green if positive, yellow if zero, red if negative.
§- Colors the following value red if positive, yellow if zero, green if negative.
§! Ends the current formatting rule.

Here is an example of the color formatting:

 example_key: "This is my text, §Bthis text is blue§!, and §Rthis text is red§!"

New text colours can be added by expanding the textcolors = {} array in interface/core.gfx. Color keys cannot have more than one letter (i.e. "BU = {0 255 0}"), and will attempt to overwrite another color key with the same first letter.

Formatting variables[edit]

When formatting variables instead of regular strings, the formatting character are added at the end after a | like so:


The resulting localization depicts the current scope's democratic popularity as a percentage (%), in green (G), rounded to 0 (0)

Text icons[edit]

Icons can be displayed within strings using the £ notation.

 example_key: "£army_experience"

Text icons are added in /Hearts of Iron IV/interface/*.gfx. An example definition of one looks like:

	spriteType = {
		name = "GFX_<text icon>"
		texturefile = "gfx/texticons/<text icon>.dds"
		legacy_lazy_load = no

The <text icon> part, without GFX_, will be used together with £ in localisation.

Nesting and overwriting strings[edit]

Nesting localization allows a localization key to be used within another localization string, enabling strings like "Unlock $nukes$ in the $technology$ screen" where 'nukes' and 'technology' are localization keys. If you want to use dollar signs in localization strings, you need to write "$$", so that a single dollar sign appears in the resulting string.

Sometimes you don't want to create new localisations, but rather overwrite the original ones in the base game. Creating a file in the localisation folder may not result in every string being overwritten, so instead you must create a subfolder in the localisation folder named "replace" (It must be named replace, no other subfolders will be recognized). Inside this subfolder you can put the file with the strings you wish to rewrite. (E.g, if you want to rename the parties of a country, you would create a file named new_parties_l_english.yml and place it inside of the replace folder which is inside of the localisation folder)


In specific contexts, such as events, it is possible to use namespace localization. This operates using the scopes with special functions in an object-oriented manner.

 example_key: "[Root.GetName]"

This would grab the name of the ROOT scope and display it as the string.

It is possible to string scopes together:

 example_key: "[From.Owner.GetName]"

This would grab the name of the OWNER (country) scope of the FROM (province) scope for the current ROOT (country) scope, and display it as the string.

Another example would be getting the capital:

 example_key: "[Root.Capital.GetName]"

You can use country tags:

 example_key: "[HUN.GetRulingParty]"

You can use event targets:

 example_key: "[was_attacked.GetName]"

The list of scopes can be seen in the respective wiki page.


  • GetName
  • GetNameDef
  • GetAdjective
  • GetAdjectiveCap
  • GetLeader
  • GetRulingParty
  • GetRulingIdeology
  • GetRulingIdeologyNoun
  • GetPartySupport
  • GetLastElection
  • GetManpower
  • GetFactionName
  • GetFlag
  • GetNameWithFlag
  • GetCommunistParty
  • GetDemocraticParty
  • GetFascistParty
  • GetNeutralParty
  • GetDateText
  • GetDateString
  • GetDateStringShortMonth
  • GetDateStringNoHour
  • GetDateStringNoHourLong
  • GetYear
  • GetHerselfHimself
  • GetHerHis
  • GetSheHe
  • GetSheHeCap
  • GetRank
  • GetID
  • GetTag
  • GetAgency
  • GetTokenKey
  • GetTokenLocalizedKey

Scripted localisation[edit]

Scripted localisation is similar to creating your own namespaces. It is defined in /Hearts of Iron IV/common/scripted_localisation/*.txt and used in localisation in a similar manner to namespaces. An example of a scripted localisation definition is:

defined_text = {
	name = mod_scripted_loc
	text = {
		trigger = {
			tag = FRA
		localization_key = FRA_localization_key
	text = {
		localization_key = mod_localization_key

This example will show the FRA_localization_key localisation key for France and the mod_localization_key one otherwise as a backup. The first localization key that meets the triggers will be used. In localisation, that example can be used as

some_localisation:0 "[mod_scripted_loc]"
FRA_localization_key:0 "France-exclusive localisation"
mod_localization_key:0 "Generic localisation"