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

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

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

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

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

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

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

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

Game Concepts

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

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

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

This is the resulting output of the example string besides this image

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

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

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.

A sample from the CK3 interface, demonstrating the effect of the substitutions. Left uses the original punctuation, right uses the substitutions.

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

Modding

Map	Map • Terrain

Audio

Music • Sound