Localization

From CK3 Wiki
Jump to navigation Jump to search

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]

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[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.

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