本地化

 此頁面正在由 霜澤圖書館 翻譯中

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

The localisation is stored within the /Hearts of Iron IV/localisation/ folder, in which any sub-folder can be used. Each file is assigned a language with its filename by adding it in the end, with the following languages existing:

• l_english: English, as in /Hearts of Iron IV/localisation/english/filename_l_english.yml
• l_french: French, as in /Hearts of Iron IV/localisation/french/mod_file_l_french.yml
• l_german: German, as in /Hearts of Iron IV/localisation/german/state_names_l_german.yml
• l_spanish: Spanish, as in /Hearts of Iron IV/localisation/spanish/mod_germany_l_spanish.yml
• l_braz_por: Brazilian Portuguese, as in /Hearts of Iron IV/localisation/braz_por/bahrain_l_braz_por.yml
• l_polish: Polish, as in /Hearts of Iron IV/localisation/polish/myfile_l_polish.yml
• l_russian: Russian, as in /Hearts of Iron IV/localisation/russian/siberia_l_russian.yml
• l_japanese: Japanese, as in /Hearts of Iron IV/localisation/japanese/kuril_l_japanese.yml
• l_simp_chinese: Simplified Chinese, as in /Hearts of Iron IV/localisation/simp_chinese/khalkha_l_simp_chinese.yml

The filename has to contain the language's internal name as the file will not be loaded otherwise.
The currently-enabled language is chosen within the user directory's /Hearts of Iron IV/pdx_settings.txt file, however, more languages cannot be added directly other than these listed languages.

Quick checklist

In order for a file to work, it must have the following:

• The file has the .yml extension. By default, Windows hides file extensions, so this must be turned off to change the extension and to easily see it.
• The file's name, minus the extension, has to contain the internal name of the language, e.g. filename_l_english.yml. In this case, l is a lowercase L.
• The file has to be encoded in UTF-8-BOM - the UTF-8 encoding with the EFBBBF byte order mark at the beginning of the file. The game throws an error in the log if this is not met.
• The localisation values must be assigned to a database with the same name as the internal language. Most commonly, this means that the first line of the file must be the language followed by a colon, such as l_english:
• Each of the localisation keys are structured in the format of localisation_key:0 "Localisation value", in particular:
  • The localisation key may only have the English alphabet, underscores, dots, hyphens, and numbers. Anything else such as spaces, letters with diacritics, or non-Latin script will break the rest of the file.
  • The optional version number, 0 in this case, may only consist of numeric digits. Anything else such as hyphens or letters will break the rest of the file.
  • The localisation value must be surrounded by a U+022 quotation mark on both sides and must lie strictly on one line. Failing to meet this will break the rest of the file.

Basics

Localisation is created within any file in the localisation folder: the filename aside from the file extension is irrelevant aside from deciding which language is chosen.
Every localisation file must use the UTF-8-BOM encoding, i.e. the UTF-8 encoding with the byte order mark in the beginning of the file. Exact details depend on the text editor:

• Notepad++: Top bar's "Encoding" menu provides a selection of encodings. UTF-8-BOM is used in this case.
• Sublime Text: Top bar's "File" menu provides the "Save with Encoding" selection. UTF-8 with BOM is used in this case.
• Visual Studio Code: In the bottom bar, there's the "Select Encoding" button titled with the current encoding (Usually "UTF-8" or "UTF-8 with BOM"). To convert, this must be pressed and then "Save with encoding" must be selected with "UTF-8 with BOM".

Each localisation key must be assigned to a language database, marked with a line containing the language name ending with a colon, and nothing else. For example, l_english:. Until the next database entry or the end of file, this will assign every localisation key afterwards to the English language. A single file may contain entries for databases of multiple languages at the same time, however the filename must also contain each of these languages.

Next lines are structured in the format of localisation_key:0 "Localisation value". In here:

• localisation_key is the localisation key that is being localised. This is usually the same as the name of the database entry (e.g. a focus with the name of TAG_focusname will have TAG_focusname as the needed localisation key). Other times, it's possible or required to set in the database entry itself (e.g. title = my_event.1.t within an event). Commonly, appending _desc as TAG_focusname_desc provides the localisation key for the description, such as with characters, focuses, ideas, traits, and so on.

The localisation key cannot have special characters in it, where a special character is defined as taking up more than 1 byte using the UTF-8 encoding. This includes every character other than those in the ASCII character system, so in essence localisation keys shouldn't have anything other than English letters, underscores, dots, and numbers. Localisation keys additionally cannot include spaces in them. Either one will show up within the error log as an error of the sort of Expected colon(:) at line <...>.

• 0 is the version number, used for Paradox's internal translation tracking. This is never read in-game, and it can be omitted entirely with no difference in interpretation. Since this is introduced by Paradox and is invalid in standard YAML formatting, this may break the default syntax highlighting used for YAML in text editors. The version number can only contain numeric characters, anything else such as a hyphen is unexpected.
• Localisation value refers to the text that will show up in-game. This must be on one line total, multiple lines will break the file. Instead, newlines are marked using \n (Note that this is a backslash rather than a regular slash), such as localisation_key: "First line.\nSecond line." A space after the \n should be avoided, as it will appear in-game as offsetting the next lines.

Any issue with localisation, such as special characters or spaces in localisation keys or a missing quote, will break the localisation file starting with the point where the syntax first stopped being followed correctly.

An example of a localisation file's contents is the following:

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

Nearly any printable character is allowed to use within the localisation value, other than certain special characters with special meaning, such as square brackets, or newlines. However, only some select characters are present in the fonts that are used in the game, and the selection of characters differs depending on the font. If the used font doesn't include a representation of a character, the game will replace it with a question mark (?). This affects only the font representation: this may be remedied by switching the used font within the interface or by changing the font to include the letter.

Replacing

Typically, localisation key overlap must be avoided, overlap being the same localisation key being defined several times in the same language's files. This is tracked within user directory's /Hearts of Iron IV/logs/text.log file, which contains a list of overlapping localisation keys if any. The value that'll get chosen does not seem to have a consistent pattern, but seems to prioritise base game files.

However, if the localisation file is contained within a folder with the name of "replace" (such as /Hearts of Iron IV/localisation/english/replace, still must be inside of localisation), it will get priority over the entries that are not. This can be helpful to overwrite only specific localisation keys without porting over the entire file, such as if the file gets frequently updated in base game.

For example, if desiring to change the name of the effect to add political power from the default POLITICS_ADD_POLITICAL_POWER:0 "Political Power: $VAL|=+0$.", it may be undesirable to port over the entire /Hearts of Iron IV/localisation/english/effects_l_english.yml file to the mod, as new effects frequently get added to the game which would mean the file has to be kept in check.
However, instead creating a new localisation file within the /Hearts of Iron IV/localisation/english/replace/ folder and defining the POLITICS_ADD_POLITICAL_POWER localisation key there will result in the value of the key getting changed without needing to copy the entire localisation file, meaning that the mod is now easier to port to future updates.

For example, /Hearts of Iron IV/localisation/english/replace/mod_replace_l_english.yml would contain the following content:

l_english:
 POLITICS_ADD_POLITICAL_POWER: "New mana: $VAL|=+0$."

Special characters

Colouring characters

Various characters can be added to a string to alter its colour in-game. A colouring character formatting begins with a section sign (§) and includes a single letter (byte) afterwards used to identify the colour. The exclamation point is used to mark the end of a colouring rule. The end of a string doesn't necessarily mean that the colouring rule will end, meaning its use is mandatory with every colouring rule to avoid spillover into the next text, even if it should last until the end of the string. On Windows, the Alt+21 alt code can be used to input a section sign.

The following formatting characters are implemented in the base game (The colour provided is the default generic colour and may be different depending on the font):

Code	Effect	Exact colour
§!	Ends the current formatting rule.	None.
§C	Colours the text cyan.	( 35, 206, 255 )
§L	Colours the text a dirty orange-gray (labeled "lilac").	( 195, 176, 145 )
§W	Colours the text white.	( 255, 255, 255 )
§B	Colours the text blue.	( 0, 0, 255 )
§G	Colours the text green.	( 0, 159, 3 )
§R	Colours the text red.	( 255, 50, 50 )
§b	Colours the text black.	( 0, 0, 0 )
§g	Colours the text light gray.	( 176, 176, 176 )
§Y	Colours the text yellow.	( 255, 189, 0 )
§H	Colours the text yellow (same as §Y, labeled "header").	( 255, 189, 0 )
§T	Colours the text white (same as §W, labeled "Title").	( 255, 255, 255 )
§O	Colours the text orange.	( 255, 112, 25 )
§0	Colours the text purple (labeled "Gradient Step 0").	( 203, 0, 203 )
§1	Colours the text lilac (labeled "Gradient Step 1").	( 128, 120, 211 )
§2	Colours the text blue (labeled "Gradient Step 2").	( 81, 112, 243 )
§3	Colours the text gray-blue (labeled "Gradient Step 3").	( 81, 143, 220 )
§4	Colours the text light blue (labeled "Gradient Step 4").	( 90, 190, 231 )
§5	Colours the text dull cyan (labeled "Gradient Step 5").	( 63, 181, 194 )
§6	Colours the text turquoise (labeled "Gradient Step 6").	( 119, 204, 186 )
§7	Colours the text light green (labeled "Gradient Step 7").	( 153, 209, 153 )
§8	Colours the text an orange-yellow (labeled "Gradient Step 8").	( 204, 163, 51 )
§9	Colours the text white-orange (labeled "Gradient Step 9").	( 252, 169, 125 )
§t	Colours the text vivid red (labeled "Gradient Step 10").	( 255, 76, 77 )

Here is an example of the colour formatting:

l_english:
 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 /Hearts of Iron IV/interface/core.gfx. Colour keys cannot have more than one letter (i.e. "BU = {0 255 0}"), and will attempt to overwrite another colour key with the same first letter. It is also possible to make a colouring character represent a different colour from default when a certain font is used within the bitmapfont definition of that font.

Errors

The errors related to the colouring characters can be fairly unintuitive to find, considering that they do not provide the location of the file.
There are three types of the error:

• Could not find coloring for character 'M' – This exact example means that, somewhere, the game found §M within localisation; however, since "M" isn't a valid colour, this is an unexpected result. The exact character is provided, so finding the cause should be elementary. A space is also considered a character, so Could not find coloring for character ' ' means that somewhere in localisation § is present, with a symbol specifying the beginning or end of a colouring rule omitted.
• Could not find coloring for character id '17' – Note that it specifies the character ID. In this case, the printable Unicode character ID is provided. This is typically done where providing the actual character would be confusing (e.g. for the number "1", the game would specify the character id "17" if such a colour doesn't exist. Since "1" is the 18th printed character, it has the id of 17, as the numeration typically starts from 0.)
  

This has a notable exception: the character id '0' may refer to the NULL character rather than a space. In other words, the character id '0' means there is absolutely nothing after the § symbol, i.e. the string ends with §. As such, locating this error would be done by searching for §" This is usually caused by omitting the exclamation mark from the character to end the colour formatting, which would properly be §!.

• If trying to use a character that takes several bytes to write in the UTF-8 encoding, the game will only try to read the last byte of the character rather than the entirety of it. This may result in either of the previous errors, but it makes finding the cause much harder. For example, trying to use §Ā Some text §!, where Ā has the code of U+0100, will result in the game throwing an error of Could not find coloring for character id '0', and trying to use §ō Some text §!, where ō has the code of U+014D, will result in the game throwing an error of Could not find coloring for character 'M' (as the character 'M' has the code of U+004D).

Searching can be done using a text editor with the "Find in Files" functionality. Windows Explorer cannot be used, as it does not search inside of YAML files. For example, this is how the functionality is accessed in the more common editors to use:

• Notepad++ – This is located in the "Search" topbar menu as "Find in Files...". By default, no folder is provided. "Follow current doc." allows the text editor to automatically input the currently-opened document's folder as the place for the search, or it can be entered manually. Alternatively, this menu can be opened from the right-click menu of a folder within the "Folder as Workspace" menu – accessed by a button in the topbar – which'll automatically set the folder location to be that folder.
• Sublime Text – This is located in the "Find" topbar menu as "Find in Files...". In order to add a folder to search, the menu to the right of the "Where:" line can be opened, with either "Add Folder" (to select an individual folder) or "Add Open Folders" (To automatically select all folders opened via Sublime Text) buttons serving to do so.
• Visual Studio Code – Visual Studio Code only supports searching the currently opened folder. A folder is opened either through the "Open Folder..." button in the "File" topbar menu or the "Explorer" menu, accessed through the bar on the left. After this, the functionality can be accessed in the "Edit" menu as "Find in Files". In order to speed up the search, filename filters can be used. For example, localisation/english/*.yml within "files to include" will only search every *.yml file within the <currently opened folder>/localisation/english/ folder, where * stands for any amount (including 0) of any characters within the filename. Similar filters can be used in the previous two text editors, however without allowing folders to be filtered — only the filenames.

Formatting variables

參見：Variables

Variables have a unique way for applying colouring, also allowing extra formatting characters. These are applied after a pipe placed at the end of the variable's name, such as [?my_variable|R] that will turn the colour of the variable my_variable red. If no colouring is applied, it will use the same colour as regular text: the §-colour block, textbox's text_color_mode, or the font's default colour in that order.

The list of formatting characters that are restricted to variables only are the following:

Code	Effect
*	Converts the variable to SI units—appends "K" or "M" and divides the variable appropriately, such as 65 536 becoming 65.53K and 1 500 000 becoming 1.50M. Displays 2 decimals after the dot by default.
^	Same as *.
=	Prefixes the variable with + if the value is positive or - if it is negative.
0..9	Controls the number of decimals to display. Due to the nature of the game's variables, there are no more than 3 decimals that can be shown. Using any digit greater than 3 will instead have the same result as 3.
%	Converts the variable to percentage, multiplying by 100 and appending a %. By default, will show 2 digits after the decimal point, though the second digit will always be 0.
%%	Appends a percentage to the end of the variable without multiplying by 100.
+	Colours the variable green if positive, yellow if zero, red if negative.
-	Colours the variable red if positive, yellow if zero, green if negative.

Any unrecognised symbols will neither change how the variable is localised nor get recognised as an error in-game. For example, it's common practice in the base game to prepend a dot before the digit used to control the amount of displayed digits as [?var|.1]. In case of overlap between mutually-exclusive rules, the last-used one will be prioritised. However, static colouring has a lower priority than dynamic colouring (e.g. [?var|+Y] will be treated as [?var|+]), and using %% will also override %.

Some examples of formatting characters in usage:

l_english:
 loc_key: "Democratic party popularity: [?party_popularity@democracy|%G0]" 
 loc_key_2: "Modifier token's value: [?modifier@my_modifier|.1%%+]"
 pol_power_trigger_tt: "Has more than [?var_name|Y] political power"

Within these examples, the first string depicts the current scope's democratic popularity as a percentage multiplied by 100 (%), in green (G), rounded to a whole number with 0 decimals (0). The second string displays the my_modifier modifier token's value as a 'good' number (+ making it green if positive, red if negative), with a percentage sign appended in the end (%%) and rounded to a number with one decimal (.1). The third string displays the variable in yellow colouring (as is common in the base game's tooltips), leaving it unchanged otherwise.

Country's flags

The following in localisation will display the default, /Hearts of Iron IV/gfx/flags/TAG.tga, flag of a country: @TAG
It's recommended to use the GetFlag namespace when possible instead, however, this can be used on localisation that doesn't support namespaces, such as custom modifier tooltips or the game rules.

Text icons

Icons can be displayed within strings using the £ notation.

l_english:
 example_key: "£army_experience"

Text icons are added as spriteType = { ... } definitions in /Hearts of Iron IV/interface/*.gfx files within an overarching spriteTypes = { ... }. An example definition of one looks like:

	spriteType = {
		name = "GFX_my_text_icon"
		texturefile = "gfx/texticons/filename.dds"
		legacy_lazy_load = no
	}

The text icon's name is equal to the text icon with the GFX_ part in the beginning removed, being £my_text_icon in this case.

If the sprite of the text icon is made out of multiple frames, then the specified frame can be used in localisation as £icon_name|1, this example being the first frame. Note that legacy_lazy_load = no is necessary for multi-framed text icons to work properly.

Nesting strings

The dollar sign special symbol is used for nesting other strings within any given localisation key's value. In particular, there are 3 primary usage cases for it:

• Nesting other localisation keys. For example, some_modifier_tooltip:0 "$modifier_production_speed_infrastructure_factor$: §R-10%§!" will show up in-game as Infrastructure construction speed: -10%, assuming that modifier_production_speed_infrastructure_factor's definition is unchanged from the base game.

This is useful with localisation key values that need to be re-used within others, but can be easily changed during the development of the mod, as to not need to adjust every single localisation value that uses it when changing it. This can also be used to expand compatibility with base game updates or other mods that may potentially change the localisation value but should still be compatible with the mod.

When used within pdx_tooltip of an interface element, this does not work properly, instead showing up with the dollar signs visible. This can be bypassed using scripted localisation, as a scripted localisation entry that points towards a key, the value of which contains nested localisation entry, will work as intended.

• Inputting a dollar sign itself. This is done by doubling the dollar sign in localisation, such as cost_tooltip: "This option costs $$100".
• Nesting a strictly internal variable. This is particularly common within base game's localisation that corresponds to game mechanics rather than database entries, such as confirm_cancel_national_focus_desc:0 "Are you sure you want to cancel the national focus §H$FOCUS_NAME$§!?". In these cases, the specified internal variable only exists within the scope of that localisation key and cannot be used anywhere else.
  

One notable usage of strictly internal variables is in country names, as these offer a variety of internal variables fetching the non-ideology name of the country and the overlord's name in either regular, ADJ, or DEF form, such as COUNTRY_autonomy_collaboration_government:0 "$OVERLORDADJ$ $NONIDEOLOGY$".

Namespaces

Namespaces refer to obtaining certain information from some scope to display in localisation. For example, getting the name of a country, the surname of a character, the ID of a state, and etc.
A namespace is marked with the square brackets on either side as in my_localisation_key: "[GetDateText]". By default, there is no scope assumed. A scope can be added, separated from the namespace with a dot, in order to let the game know from whom to obtain information, such as my_localisation_key: "[QAT.GetRulingParty]", which'll result in the ruling party of the country QAT appearing in localisation. Any dual scope that can be used as a target may be used in localisation. THIS can be used in order to refer to the scope of where it's used, such as effect_tooltip: "[ROOT.GetNameDefCap] declares war on [THIS.GetNameDef]".

Variables and event targets can be used within namespaces as well. For example, this grants the name of the capital state of OMA using the 'capital' variable: my_localisation_key: "[OMA.capital.GetName]". A list of built-in variables that can be used can be seen in the respective wiki page. Another common ones to use include 'owner' and 'controller' for states, such as my_localisation_key: "Owner of South-West England: [123.owner.GetName]".

Characters only exist within the scope of the country where they're recruited, in versions prior to 1.12.8. What this means is that before scoping into the character, one must first scope into the country that they are assigned to, such as current_name_of_fdr:0 "[USA.USA_franklin_delano_roosevelt.GetFullName]". If the character is marked with some other token (such as THIS or ROOT), this is unnecessary, but it is necessary for direct character IDs. Characters also support scoping to the GetLeader localisation function beforehand, such as leader_pronoun: "[ROOT.GetLeader.GetHeShe]" In this case, scoping into the country is still necessary.

Note that namespaces cannot be used everywhere. In the majority of the user interface, such as the names for wars or countries, they will not work properly, instead appearing exactly as in localisation, with the square brackets still visible. A list of locations where namespaces do work is:

Location	Notes
Focuses	Requires dynamic = yes within the focus to work correctly for the title, otherwise it generates a value at the game's start and it remains unchanging until the next reload (either of the savefile or the focus tree). Not required for the description, which always dynamically refreshes localisation.
Ideas and dynamic modifiers	Support for dynamic modifiers was added in 1.13.
Decisions
Events	At times it may be better to use completely different localisation keys within events instead of using scripted localisation.
Custom effect/trigger tooltips	Despite the fact that it works for effects and triggers, custom modifier tooltips do not support scripted localisation.
Boolean flags	The names of the boolean flags, appearing in the tooltip when checked for them with triggers such as has_country_flag = flag_name or has_character_flag = flag_name
Operations
Adjacency rule tooltips	Referring to the tooltip that appears when hovering over a strait that's disabled for this country.
Custom interface elements	The container with the UI element must be attached to a scripted GUI that has a valid context_type within the corresponding /Hearts of Iron IV/common/scripted_guis/*.txt file. May require a game restart for it to apply.

The list may be incomplete, so something not being mentioned does not necessitate that localisation does not work there, but that does make it unlikely. Other localisation functions, not involving square brackets, do still work in this case, however.

Functions

Sometimes, the result of a function may be interpreted as a localisation key itself, but only if the string consists entirely out of that function. For example, log = "[THIS.GetTag]" will result in the non-ideology name being logged instead if one exists, since that localisation key consists only of the country tag. However, log = "loc_key_[ALB.GetTag]" will log loc_key_ALB, even if a localisation key exists with that name.

Country scope

Name	Example	Description
GetName	[GER.GetName]	Gets the name of the country, the name of the state, or the name of the character. For aces, only gets the first name: see GetFullName.
GetTag	[GER.GetTag]	Puts the tag of the country into localisation. Particularly useful for Meta effects.
GetLeader	[POL.GetLeader]	Gets the name of the leader of the country. Can be further scoped into the pronoun-related namespaces, such as [THIS.GetLeader.GetSheHe].
GetManpower	[ENG.GetManpower]	Gets the total population of the country, including civilians.
GetFactionName	[SOV.GetFactionName]	Gets the name of the faction that the country is located in.
GetAgency	[FRA.GetAgency]	Gets the name of the country's intelligence agency.
GetFlag	[GER.GetFlag]	Gets the current flag of the country.
GetNameWithFlag	[ITA.GetNameWithFlag]	Gets the current flag of the country and adds the name afterwards.
GetNameDef	[SPR.GetNameDef]	Gets the DEF name of the country, primarily used to tell if "the" is needed to be put in the beginning.
GetNameDefCap	[POR.GetNameDefCap]	Gets the DEF name of the country, primarily used to tell if "The" is needed to be put in the beginning, capitalising the first letter as well.
GetAdjective	[YUG.GetAdjective]	Gets the adjective for the country, such as 聯合王國.
GetAdjectiveCap	[CAN.GetAdjectiveCap]	Gets the adjective for the country, capitalising the first letter.
GetOldName	[RAJ.GetOldName]	Gets the name of the country without any cosmetic tags applied.
GetOldNameDef	[MAL.GetOldNameDef]	Gets the DEF name of the country, primarily used to tell if "the" is needed to be put in the beginning, without any cosmetic tags applied.
GetOldNameDefCap	[AST.GetOldNameDefCap]	Gets the DEF name of the country, primarily used to tell if "The" is needed to be put in the beginning, without any cosmetic tags applied, capitalising the first letter.
GetOldAdjective	[NZL.GetOldAdjective]	Gets the adjective for the country without any cosmetic tags applied.
GetOldAdjectiveCap	[HAW.GetOldAdjectiveCap]	Gets the adjective for the country without any cosmetic tags applied, capitalising the first letter.
GetNonIdeologyName	[JAP.GetNonIdeologyName]	Gets the non-ideology name of the country, defined with TAG:0 "Country name"
GetNonIdeologyNameDef	[SAU.GetNonIdeologyNameDef]	Gets the non-ideology DEF name of the country, primarily used to tell if "the" is needed to be put in the beginning.
GetNonIdeologyNameDefCap	[SWE.GetNonIdeologyNameDefCap]	Gets the non-ideology DEF name of the country, primarily used to tell if "The" is needed to be put in the beginning, capitalising the first letter.
GetNonIdeologyAdjective	[DEN.GetNonIdeologyAdjective]	Gets the non-ideology adjective for the country.
GetNonIdeologyAdjectiveCap	[NOR.GetNonIdeologyAdjectiveCap]	Gets the non-ideology adjective for the country, capitalising the first letter.
GetPartySupport	[ICE.GetPartySupport]	Gets the percentage of the ruling party, on the scale from 0 to 100. Does not have the % symbol in the end.
GetLastElection	[ROOT.GetLastElection]	Gets the date when the last country's election occurred in the "HH:00, DD Month, YYYY" format, such as "01:00, 1 January, 1936".
GetRulingParty	[HOL.GetRulingParty]	Gets the short name of the party ruling over the country.
GetRulingPartyLong	[BEL.GetRulingPartyLong]	Gets the long name of the party ruling over the country.
GetRulingIdeology	[LUX.GetRulingIdeology]	Gets the name of the country's ideology group, in adjective form.
GetRulingIdeologyNoun	[GER.GetRulingIdeologyNoun]	Gets the name of the country's ideology group, in noun form.
GetCommunistParty	[HUN.GetCommunistParty]	Gets the name of the 共產主義 party.
GetDemocraticParty	[AUS.GetDemocraticParty]	Gets the name of the 民主主義 party.
GetFascistParty	[CZE.GetFascistParty]	Gets the name of the 法西斯主義 party.
GetNeutralParty	[ROM.GetNeutralParty]	Gets the name of the 中立主義 party.
GetCommunistLeader	[BUL.GetCommunistLeader]	Gets the name of the leader of the country's 共產主義 party.
GetDemocraticLeader	[GRE.GetDemocraticLeader]	Gets the name of the leader of the country's 民主主義 party.
GetFascistLeader	[ALB.GetFascistLeader]	Gets the name of the leader of the country's 法西斯主義 party.
GetNeutralLeader	[TUR.GetNeutralLeader]	Gets the name of the leader of the country's 中立主義 party.
GetPowerBalanceName	[ITA.GetPowerBalanceName]	Gets the name of the country's currently-active balance of power.
GetPowerBalanceModDesc	[ITA.GetPowerBalanceModDesc]	Gets the names of the country's currently-active balance of power modifiers and their effects towards the BoP. For the modifiers applied by the active range, see GetActiveRangeModDesc.
GetRightSideName	[ITA.GetRightSideName]	Gets the name of the country's right side in the currently-active balance of power.
GetLeftSideName	[ITA.GetLeftSideName]	Gets the name of the country's left side in the currently-active balance of power.
GetActiveSideName	[ITA.GetActiveSideName]	Gets the name of the side in the country's currently-active balance of power that has more power.
GetTrendingSideName	[ITA.GetTrendingSideName]	Gets the name of the side in the country's currently-active balance of power that the balance is changing towards.
GetActiveRangeName	[ITA.GetActiveRangeName]	Gets the name of the range in the country's currently-active balance of power that is currently active, granting its modifiers.
GetActiveRangeModDesc	[ITA.GetActiveRangeModDesc]	Gets the modifiers applied by the active range in the country's currently-active balance of power. Uses the BOP_RANGE_MODIFIER localisation key.
GetActiveRangeRuleDesc	[ITA.GetActiveRangeRuleDesc]	Gets the game rules modified by the active range in the country's currently-active balance of power. Uses the BOP_RANGE_RULE localisation key.
GetActiveRangeActivationEffect	[ITA.GetActiveRangeActivationEffect]	Gets the tooltip for the effects executed when entering the active range in the country's currently-active balance of power. Uses the BOP_RANGE_ACTIVATION_EFFECT localisation key.
GetActiveRangeDeactivationEffect	[ITA.GetActiveRangeDeactivationEffect]	Gets the tooltip for the effects executed when exiting the active range in the country's currently-active balance of power. Uses the BOP_RANGE_DEACTIVATION_EFFECT localisation key.
GetChangeRateDesc	[ITA.GetChangeRateDesc]	Gets the rate by which the balance of power is changed weekly and/or daily and towards which side. May use BOP_CHANGE_RATE_DAILY or BOP_CHANGE_RATE_WEEKLY localisation keys depending on the current BoP modifiers, prioritising the former if possible.
GetBopTrendTextIcon	[ITA.GetBopTrendTextIcon]	Selects the text icon corresponding towards which side is getting power. May select either GFX_BoP_left_texticon, GFX_BoP_right_texticon, or nothing.

Other scopes

Date variable in this case refers to a variable set to a date value. Using it with the current date can be done by using the global.date variable as [?global.date.GetDateString].

Name	Scope	Example	Description
GetName	State, character, operative, ace	[123.GetName] [POL.POL_character.GetName]	Gets the name of the state or the name of the character. For aces, only gets the first name: see GetFullName.
GetName	MIO	[?ID.GetName][?BEL_cockerill_organization.GetName]	Gets the name of the MIO.
GetDateText	Any	[GetDateText]	Gets the date in the format of "HH:00, DD Month, YYYY", such as "12:00, 1 January, 1936".
GetDate	Any	[GetDate]	Gets the date in the format of YYYY.MM.DD.HH, such as 1936.1.1.12.
GetMonth	Any	[GetMonth]	Gets the current month.
GetYear	Any	[GetYear]	Gets the current year.
GetID	State	[123.GetID]	Gets the ID of the state. Particularly useful for Meta effects.
GetCapitalVictoryPointName	State	[540.GetCapitalVictoryPointName]	Gets the name of the capital victory point (i.e. the province with the largest amount of victory points) of the state.
GetSheHe	Character	[PRU.GetLeader.GetSheHe]	Results in either "she" or "he" depending on the gender of the character, beginning with lowercase letters.
GetSheHeCap	Character	[MEX.MEX_character.GetSheHeCap]	Results in either "She" or "He" depending on the gender of the character, beginning with uppercase letters.
GetHerHim	Character	[BRA.BRA_character.GetHerHim]	Results in either "her" or "him" depending on the gender of the character, beginning with lowercase letters.
GetHerHimCap	Character	[ARG.ARG_character.GetHerHimCap]	Results in either "Her" or "Him" depending on the gender of the character, beginning with uppercase letters.
GetHerHis	Character	[CHI.CHI_character.GetHerHis]	Results in either "her" or "his" depending on the gender of the character, beginning with lowercase letters.
GetHerHisCap	Character	[CHL.CHL_character.GetHerHisCap]	Results in either "Her" or "His" depending on the gender of the character, beginning with uppercase letters.
GetHersHis	Character	[PRC.PRC_character.GetHersHis]	Results in either "hers" or "his" depending on the gender of the character, beginning with lowercase letters.
GetHersHisCap	Character	[YUN.YUN_character.GetHersHisCap]	Results in either "Hers" or "His" depending on the gender of the character, beginning with uppercase letters.
GetHerselfHimself	Character	[GXC.GXC_character.GetHerselfHimself]	Results in either "herself" or "himself" depending on the gender of the character, beginning with lowercase letters.
GetHerselfHimselfCap	Character	[XSM.XSM_character.GetHerselfHimselfCap]	Results in either "Herself" or "Himself" depending on the gender of the character, beginning with uppercase letters.
GetIdeology	Country leader	[?country_leader.GetIdeology]	Gets the ideology group assigned to the country leader, such as 民主主義 or 中立主義.
GetIdeologyGroup	Country leader	[?country_leader.GetIdeologyGroup]	Gets the ideology type assigned to the country leader, such as Liberalism or Centrism. The name is misleading.
GetRank	Unit leader	[MEN.MEN_character.GetRank]	Gets the rank of the unit leader, such as Corps Commander or Field Marshal.
GetCodeName	Operative	[THIS.GetCodeName]	Gets the codename of the operative.
GetCallsign	Operative	[THIS.GetCallsign]	Gets the callsign of the operative.
GetSurname	Ace	[LIB.GetLeader.GetSurname]	Gets the last name of the ace.
GetFullName	Ace	[ECU.ECU_character.GetFullName]	Gets the full name of the ace, with both first and last names.
GetWing	Ace	[THIS.GetWing]	Gets the wing that the ace is assigned to.
GetWingShort	Ace	[THIS.GetWingShort]	Gets the shortened name of the wing that the ace is assigned to.
GetAceType	Ace	[THIS.GetAceType]	Gets the type of the ace.
GetMissionRegion	Ace	[THIS.GetMissionRegion]	Gets the region that the ace is assigned to.
GetTokenKey	Any token variable	[?global.variablename.GetTokenKey]	Gets the token of the variable, such as infantry_equipment, instead of the internal ID. Particularly useful for Meta effects.
GetTokenLocalizedKey	Any token variable	[?GER.variablename.GetTokenLocalizedKey]	Gets the localised name of the variable, such as "Infantry Equipment". Useful for advanced abstraction techniques, as it can be used to approximate arbitrary string interpolation in Meta effects by applying to token variables which reference dummy objects, such as empty ideas, for which arbitrary localisation strings have been defined. Being able to pass around token variables that resolve to localised dummy objects is the closest it is currently possible to get to passing around and manipulating strings directly. This can enable all sorts of useful tricks and techniques, and you can even concatenate two dummy token's localisation values to form a new token string which is then pasted into a token variable in a Meta effect (as long as the resulting token string is in fact a valid existing token, otherwise the result is just an integer 0). In effect, this lets you derive a previously-unknown token variable from another already-known token variable, according to a template provided by another already-known token variable, provided the destination token is some prefixed or suffixed templated variation of the source token.
GetDateString	Date variable	[?global.date.GetDateString]	Gets the date in the format of "HH:00, DD Month, YYYY", such as "12:00, 1 January, 1936".
GetDateStringShortMonth	Date variable	[?global.date.GetDateStringShortMonth]	Gets the date in the format of "HH:00, DD Mon., YYYY", such as "12:00, 1 Jan., 1936".
GetDateStringNoHour	Date variable	[?global.date.GetDateStringNoHour]	Gets the date in the format of YYYY.MM.DD, such as 1936.1.1.
GetDateStringNoHourLong	Date variable	[?global.date.GetDateStringNoHourLong]	Gets the date in the format of "DD Month, YYYY", such as "1 January, 1936".

Scripted localisation

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. However, unlike namespaces, by default the current scope is assumed when using scripted localisation, making scoping optional. 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 consists of these entries:

• name = my_scripted_loc - The name of the scripted localisation used to refer to it within regular localisation.
• text = { ... } - A possible choice for localisation. The game picks the topmost text = { ... } block to serve as the localisation's output. In particular, these are used in the example:
  • trigger = { ... } is the trigger block evaluated for the checked scope, using this scripted localisation if true. Temporary variables set in this trigger block will remain set when displaying the localisation key, allowing math to be done between different variables or using scripted localisation recursively (such as to display every element of an array).
  • localization_key = my_loc_key (Note the American spelling with Z rather than the British spelling with S used elsewhere) assigns the localisation key to be used with this scripted localisation option. This does not support dynamic localisation directly within (e.g. localization_key = "my_loc_key_[?my_var]"), however the contents of localisation keys do support dynamic localisation.

The example above 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

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

Scripted localisation also allows randomisation of the localisation key that would be chosen, using random_list. For example, the following code will give a 60% and a 40% chance respectively for mod_localization_key_1 or mod_localization_key_2 to be chosen when this scripted localisation entry is used:

defined_text = {
    name = mod_scripted_loc
    text = {
        random_list = {
            30 = { localization_key = mod_localization_key_1 }
            20 = { localization_key = mod_localization_key_2 }
        }
    }
}

References

模組製作