Localization
Localization refers to the text presented to the player in events, menus, decisions, UI, and any other string of text in any window in the game. Localisation files are saved with .yml
extension in the localization/
folder and should be encoded as UTF-8 with BOM. The filenames should look like <name>_l_<language>.yml where <name> is the name you choose for this group of localisations, and <language> is the language the localisation is for. If the '_l_<language>' postfix is missing the game will just ignore the file!
Every file must start with a line l_<language>:
at the top, where <language> matches the language in the filename.
The localization entries look like this:
murder_successful_roll_tt:0 "[target.GetShortUINameNoTooltip] is killed!" murder_become_discovered_roll_tt:0 "#N My involvement is discovered#!"
The number after the : is optional and it does nothing for modders. Paradox uses those numbers for its own translation teams. The " quotes around each entry are mandatory.
The part between [ ] is code that looks up something in the game (in this case a character's name) and puts it in the text. The #N
and #!
control how the text is displayed; in this case as something "negative" (bad for the player). See the sections below for more details on those.
The full list of available formatting styles can be found in gui/preload/textformatting.gui
. That's also where you can add your own styles for your mod.
Formatting[edit | edit source]
Localization strings can contain formatting directives. Text formatting should begin with a #
character and end with #!
:
#<formatting code> <text> #! Example: #P +15%#!
See "Special Characters" below for more details.
Re-use other entries[edit | edit source]
Insert other localization keys: $<other key>$
Example:
special_contract_march_short:0 "March" unlock_march_contract:0 "Unlocks the #high $special_contract_march_short$#! [feudal_contract|E]"
This is useful both to avoid duplication, and to make sure that entries stay in sync with each other; for example if you ever change the description of special_contract_march_short
, the unlock_march_contract
message will automatically change with it.
The same $ notation is used to refer to special values supplied by the game engine. For example:
tooltip_feudal_elector_anti_vote_ruler_lunatic:1 "I do not trust the judgment of a [GetTrait('lunatic_1').GetName( candidate.Self )] ruler: $VALUE|=+0$"
Here $VALUE$
is a number supplied by the game, and the |=+0
part controls how that number is shown (see "Rounding numbers" below for details). Special values like this can only be used in localization entries that are shown in specific contexts; in this case, on the elective title voting screen.
Commands[edit | edit source]
Commands are used in instances where localisation must be dynamic and change based on certain conditions. Invoking a command will print out a specific string of text.
Commands need to be scoped, usually within a character. Example:
[ROOT.Char.GetLadyLord] [ROOT.Char.GetNamePossessiveRegnal] [ROOT.Char.GetFirstNameNicknamed]
Gender[edit | edit source]
These commands will show text that vary based on the gender of the character in scope.
Command |
---|
GetHerHim |
GetHerHis |
GetHerHisMy |
GetHersHis |
GetHerselfHimself |
GetLadyLord |
GetSheHe |
GetDaughterSon |
GetDaughterSonPossessive |
Character names[edit | edit source]
These commands will show some variation of the name of the character. This is not a complete list.
Command |
---|
GetFirstName |
GetFirstNameBase |
GetFirstNameNicknamed |
GetFirstNameNicknamedNoTooltip |
GetFirstNameNicknamedNoTooltipRegnal |
GetFirstNameNicknamedOrMe |
GetFirstNameNicknamedOrMeNoTooltip |
GetFirstNameNicknamedOrMeNoTooltipRegnal |
GetFirstNameNicknamedOrMeRegnal |
GetFirstNameNicknamedPossessive |
GetFirstNameNicknamedPossessiveNoTooltip |
GetFirstNameNicknamedPossessiveNoTooltipRegnal |
GetFirstNameNicknamedPossessiveOrMy |
GetFirstNameNicknamedPossessiveOrMyNoTooltip |
GetFirstNameNicknamedPossessiveOrMyNoTooltipRegnal |
GetFirstNameNicknamedPossessiveOrMyRegnal |
GetFirstNameNicknamedPossessiveRegnal |
GetFirstNameNicknamedRegnal |
GetFirstNameNoTooltip |
GetFirstNameNoTooltipRegnal |
GetFirstNameOrMe |
GetFirstNameOrMeNoTooltip |
GetFirstNameOrMeNoTooltipRegnal |
GetFirstNameOrMeRegnal |
GetFirstNamePossessive |
GetFirstNamePossessiveNoTooltip |
GetFirstNamePossessiveNoTooltipRegnal |
GetFirstNamePossessiveOrMy |
GetFirstNamePossessiveOrMyNoTooltip |
GetFirstNamePossessiveOrMyNoTooltipRegnal |
GetFirstNamePossessiveOrMyRegnal |
GetFirstNamePossessiveRegnal |
GetFirstNameRegnal |
GetTitledFirstName |
GetFullName |
GetFullNameNicknamed |
GetFullNameNicknamedNoTooltip |
GetFullNameNicknamedNoTooltipRegnal |
GetFullNameNicknamedOrMe |
GetFullNameNicknamedOrMeNoTooltip |
GetFullNameNicknamedOrMeNoTooltipRegnal |
GetFullNameNicknamedOrMeRegnal |
GetFullNameNicknamedPossessive |
GetFullNameNicknamedPossessiveNoTooltip |
GetFullNameNicknamedPossessiveNoTooltipRegnal |
GetFullNameNicknamedPossessiveOrMy |
GetFullNameNicknamedPossessiveOrMyNoTooltip |
GetFullNameNicknamedPossessiveOrMyNoTooltipRegnal |
GetFullNameNicknamedPossessiveOrMyRegnal |
GetFullNameNicknamedPossessiveRegnal |
GetFullNameNicknamedRegnal |
GetFullNameNoTooltip |
GetFullNameNoTooltipRegnal |
GetFullNameOrMe |
GetFullNameOrMeNoTooltip |
GetFullNameOrMeNoTooltipRegnal |
GetFullNameOrMeRegnal |
GetFullNamePossessive |
GetFullNamePossessiveNoTooltip |
GetFullNamePossessiveNoTooltipRegnal |
GetFullNamePossessiveOrMy |
GetFullNamePossessiveOrMyNoTooltip |
GetFullNamePossessiveOrMyNoTooltipRegnal |
GetFullNamePossessiveOrMyRegnal |
GetFullNamePossessiveRegnal |
GetFullNameRegnal |
GetName |
GetNameNicknamed |
GetNameNicknamedNoTooltip |
GetNameNicknamedNoTooltipRegnal |
GetNameNicknamedOrMe |
GetNameNicknamedOrMeNoTooltip |
GetNameNicknamedOrMeNoTooltipRegnal |
GetNameNicknamedOrMeRegnal |
GetNameNicknamedPossessive |
GetNameNicknamedPossessiveNoTooltip |
GetNameNicknamedPossessiveNoTooltipRegnal |
GetNameNicknamedPossessiveOrMy |
GetNameNicknamedPossessiveOrMyNoTooltip |
GetNameNicknamedPossessiveOrMyNoTooltipRegnal |
GetNameNicknamedPossessiveOrMyRegnal |
GetNameNicknamedPossessiveRegnal |
GetNameNicknamedRegnal |
GetNameNoTooltip |
GetNameNoTooltipRegnal |
GetNameOrMe |
GetNameOrMeNoTooltip |
GetNameOrMeNoTooltipRegnal |
GetNameOrMeRegnal |
GetNamePossessive |
GetNamePossessiveNoTooltip |
GetNamePossessiveNoTooltipRegnal |
GetNamePossessiveOrMy |
GetNamePossessiveOrMyNoTooltip |
GetNamePossessiveOrMyNoTooltipRegnal |
GetNamePossessiveOrMyRegnal |
GetNamePossessiveRegnal |
GetNameRegnal |
Command Arguments[edit | edit source]
Command Arguments are used to modify dynamic localization commands. They always go at the end of a command.
Argument | Description | Example | Without Argument | With Argument |
---|---|---|---|---|
|U |
Capitalizes command output | Tea is ready, my [ROOT.Char.GetLadyLord|U]. |
Tea is ready, my lady. | Tea is ready, my Lady. |
|L |
Transforms to command output to lowercase | Tea is ready. [ROOT.Char.GetSheHe|L] said. |
Tea is ready. He said. | Tea is ready. he said. |
Special Characters[edit | edit source]
Some sets of characters perform special functions.
Command | Description | Example |
---|---|---|
\n | Line break. Works only in certain cases. | |
#P | Formats text "positive" | #P A very good thing has happened#!OR [GetFullName|P] |
#N | Formats text "negative" | #N A rather bad thing has happened#!OR [GetFullName|N] |
#help | Text is shown using a help style | #help If you do not give either Gold or Soldiers to the war effort, your [head_of_faith|E] will condemn you and you will lose [piety|E].#! |
#I | Text is displayed in an informational style | #I Click to view your [GetPlayer.GetCouncillorPosition( 'councillor_court_chaplain' ).GetPositionName]#! |
#warning | Text is displayed as a warning | #warning Only your younger children lacks [guardians|E]#! |
#T | Text is displayed as a title | #T Randomize Dynasty Name#! |
#E | Text is displayed as a game concept | #E Randomize#! |
#X | Text is displayed as a warning in italic format | #X Choosing a New Appearance will discard ALL previous changes!#! |
#S | Formats text bold and italic | #S Occupying Counties:#! |
#V | Formats text white | #V This text is white #!OR [GetFullName|V] |
#EMP | Text is emphasized | #EMP Emphasis here #! |
#weak | Text has a lighter color | #weak footnote or aside #! |
#bold | Text is displayed in bold | You have #bold NOT #! done this |
#italic | Text is displayed in italics | You #italic will #! do this |
#indent_newline:N | (N being a number)
How many spaces to put after line breaks |
#indent_newline:2 |
The full list of available formatting styles can be found in gui/preload/textformatting.gui
. That's also where you can add your own styles for your mod.
You can also combine formatting codes with a ;
(semicolon), like #high;bold
to get both. However, if you find yourself doing that it may be better to define a new style.
Linking[edit | edit source]
Game Concepts[edit | edit source]
Localization strings can link to game concepts as follows:
[concept_key|E] # So for example [faith|E]
By default the concept starts with first letter in upper case, you can set the first letter in lower case as follows :
[concept_key|El] # So for example "The word [faith|El] is now starting by a lower case letter"
The expression linking to the game concept can be customized as follows :
[Concept('concept_key','Customized expression')|E] # So for example "The game concept link [Concept('faith','religion')|E] is now written as religion."
Traits[edit | edit source]
Similarly, you can link to a trait with:
[GetTrait('trait_name').GetName(GetNullCharacter)]
This will cause the trait to have a tooltip which shows the trait information. You can also pass an actual character into the GetName
function, so that any conditional descriptions display properly. For example, the localization text for adding a trait passes in the character who will receive the trait:
# note that the [trait|E] links to the game concept of a trait, as described above, while the [TRAIT.GetName( Character.Self )|LV] links to the actual trait which will be gained # from localization/english/effects_l_english.yml ADD_MY_TRAIT:2 "You gain the [trait|E] [TRAIT.GetName( CHARACTER.Self )|LV]"
Note that the |LV
, which will cause the trait to be written as lowercase and in a white font (see the above sections on Command Arguments and Special Characters, respectively), appears to be idiomatic in the vanilla game files.
Rounding numbers[edit | edit source]
If a numeric value has a decimal portion, it can be rounded by using the desired number of decimal places, such as:
# Round to 2 decimals [some_value|2] # Remove all decimals: [some_value|0]
Note that the value is always rounded down.
Icons[edit | edit source]
Icons can be displayed in loc keys by using @icon_name!
to render them.
Careful! @warning_icon!, you are going to drop all your @gold_icon! gold if you keep running like that! @piety_icon_islam! Allah will judge you for that!
Icon Addresses | ||||||||
---|---|---|---|---|---|---|---|---|
Generic Icons | Military Icons | Faith Icons | Terrain Icons | |||||
warning_icon | skill_martial_icon | unspent_strong_hook_icon | friend_icon | soldier_icon | heavy_cavalry_icon | pikemen_icon | catholic_icon | plains |
gold_icon | skill_stewardship_icon | crime_icon | best_friend_icon | bombard_icon | heavy_infantry_icon | skirmishers_icon | orthodox_icon | forest |
prestige_icon | skill_intrigue_icon | intimidated_icon | rival_icon | bondi_icon | horse_archers_icon | trebuchet_icon | custom_faith_1_icon (10) | mountains |
time_icon | skill_learning_icon | terrified_icon | nemesis_icon | bowmen_icon | jomsviking_pirates_icon | varangian_veterans_icon | virtue_icon | |
cross_icon | skill_prowess_icon | weak_hook_icon | lover_icon | camel_riders_icon | light_cavalry_icon | vigmen_icon | sin_icon | |
stress_icon | stress_gain_icon | pending_court_events | soulmate_icon | crossbowmen_icon | mangonel_icon | war_elephants_icon | fervor_icon | |
dread_icon | stress_critical_icon | realm_capital_icon | danish_huskarls_icon | onager_icon | advantage_icon | |||
exposed_icon | stress_loss_icon | alliance_icon | countered_icon | supply_icon | gathering_icon | |||
portrait_punishment_icon | death_icon | prestige_level_0_icon (5) | fort_icon | garrison_icon | army_quality_icon_1 (5) | |||
skill_diplomacy_icon | scheme_icon | dynasty_prestige_icon (5) | knight_icon | embarked_icon | no_siege_weapon_icon |
Usage of special characters & Line breaks[edit | edit source]
If you wish to input characters such as " in a string, utilize \ before every usage:
Hello, I am \"totally\" not going to stab you! Hello, I am #weak\"totally\" not# going to stab you!
If you want to break line, you can use \n:
This is line one, which will show up above,\nWhile this is line two, coming right at you from below.
Avoid adding spaces before or after the line break to preserve the text's alignment.
When adding multiple paragraphs, keep in mind that you can assign multiple keys to the same desc, which is particularly useful if you want to customize just one paragraph. For example, you can have a localization file with:
paragraph_separator:0 "\n\n" first_paragraph:0 "Generic intro text" maybe_second_paragraph:0 "Conditional text" alternative_second_paragraph:0 "Alternative text" final_paragraph:0 "Generic outro text"
Then, you can define an event like this:
event_name.100 = { desc = { desc = first_paragraph desc = paragraph_separator first_valid = { triggered_desc = { limit = { some_trigger = yes } desc = maybe_second_paragraph } triggered_desc = { limit = { some_trigger = no } desc = alternative_second_paragraph } } desc = paragraph_separator desc = final_paragraph } }
This will be much easier to maintain than keeping 2 different entries in sync, and will be easier to read in the localization file.
Chinese punctuation[edit | edit source]
A common issue with Chinese text in earlier versions of the game is that lines were broken apart in the the wrong places, such as in the middle of words. This is caused by the game engine not recognising the Chinese ideographic punctuation marks as punctuation, so it treated lines of Chinese text as single words and inserted breaks wherever it wanted.
Sadly an engine fix was impossible, so to ensure proper line breaking in Chinese text, you need to use a half-width versions of the punctiation, followed by a space. Using the right character substitutions, the visual change should be minimal and the line breaks do end up in the proper places.
Original | Codepoint | Substitution | Codepoint | Note |
---|---|---|---|---|
。 |
U+3002 Ideographic Full Stop | 。 |
U+FF61 Halfwidth Ideographic Full Stop (and space) | |
, |
U+FF0C Fullwidth Comma | , |
U+002C Comma (and space) | Since there is no Chinese-style halfwidth comma, a Latin one may be an acceptable substitute. |
, |
U+FF0C Fullwidth Comma | 、 |
U+FF64 Halfwidth Ideographic Comma (and space) | This can also be used for the comma, but note the visual difference. |
- |
U+002D Hyphen-Minus | ‑ |
U+2011 Non-Breaking Hyphen | This is a wholly optional substitution to prevent a hyphen from being detected as a word boundary; use this to lessen the chance of line breaks there. |
References[edit | edit source]
Documentation | Effects • Triggers • Modifiers • Scopes • Variables • Data types • Localization • Customizable localization |
Scripting | AI • Bookmarks • Characters • Commands • Council • Culture • Decisions • Dynasties • Events • Governments • History • Holdings • Lifestyles • Regiments • Religions • Story cycles • Titles • Traits |
Map | Map • Terrain |
Graphics | 3D models • Exporters • Interface • Coat of arms • Graphical assets • Fonts • Particles • Shaders • Unit models |
Audio | Music • Sound |
Other | Console commands • Checksum • Mod structure • Modding tools • Troubleshooting |