编辑“模组本地化”

{{Version|3.1}}
Localisation refers to the actual text presented to the player in events, menus, weaponry, stories, and any other string of text in any window in the game. Localisation files are saved as [[wikipedia:.yml|.yml]] in the localisation/ folder and should be encoded with [[wikipedia:UTF-8-BOM|UTF-8 with BOM]]. The naming convention for .yml files is '''<file>_l_<language>.yml''' where <file> is the name given for this group of localisations, and <language> is the language the localisation is for. Supported languages currently include Portuguese (''braz_por'') English (''english''), French (''french''), German (''german''), Polish (''polish''), Russian (''russian''), Spanish (''spanish''), and simplified Chinese (''simp_chinese'').

Useful commands:
 reload text – reloads localisation table.
 switchlanguage l_english – switches used language and reloads localisation table.

=== Creating Localisation Files ===
* In the root mod folder (not in common), create a folder named "''localisation''" spelled with an s. Note, some other paradox titles may use the Americanized "''localization''" with a z.
* Optionally, create language subfolders within the "''localisation''" folder. This is organizationally helpful but not required.
* Stellaris’s localisation files are encoded as UTF-8-BOM. They '''must be''' encoded in UTF-8-BOM, as even UTF-8 will fail to be parsed by Stellaris, and will not work.
* The easiest way to get the correct encoding is to copy an existing Stellaris .yml file and modify it.
* Alternatively, simply create a standard text file and save it as .yml with UTF-8 with BOM encoding. Various text editors, such as [[wikipedia:Notepad++|Notepad++]] and [[wikipedia:Visual Studio Code|Visual Studio Code]], will allow you to manually save with encoding UTF-8 with BOM
* The file name must end in "''_l_<language>''", otherwise it will not be read.
* The first line of any localisation file must be <code>l_<language>:</code>, otherwise it will not be read.
* Example file name: <code>mod_buildings_l_english.yml</code>

Naming a YML file the same as a vanilla YML file will overwrite vanilla. Doing this is not recommended, unless you are trying to change (almost) all of the entries in the file. Localisation entries can be overwritten individually, by saving them in the "Replace" folder. See [[#Overwriting Vanilla Text|overwrite section]].

Unfortunately there is no mod-friendly fallback language feature, so if localisation keys are missing, these keys are simply displayed as text. Therefore, it is practice to simply duplicate the English files for all other languages (changed with appropriate header).

=== File Encoding ===
* Open the YML file using a text editor. Editors such as [https://www.notepad-plus-plus.org/ Notepad++] and [https://code.visualstudio.com/ Visual Studio Code] are recommended, however, if those aren't available, even standard Notepad will work.
* Convert the file to UTF-8 with BOM
* If using Notepad++, go to menu bar, open the ''Encoding'' menu.
* If using VSC, go to the bottom right corner and click on the encoding (<code>UTF-8</code> by default), then click Save with Encoding. Alternatively, it is possible to modify the settings so YML files created using VSC have ''UTF-8 with BOM'' encoding by default.
* If using Notepad, go to ''Save As…'', then change the encoding and save the file.
** If the options listed are ''UTF-8'' and ''UTF-8 with BOM'' (or similar), use ''UTF-8 with BOM''.
** If the options listed are ''UTF-8 without BOM'' and ''UTF-8'' (or similar), use ''UTF-8''.

=== Localisation Keys ===
 <nowiki>
l_<language>:
 localisation_key_1: "Text String 1"
 localisation_key_2: "Text String 2"</nowiki>
Individual localisation entries are called keys and are placed before the colon. Keys are the actual code that points to the localised text. The text itself itself is called a string. The key is to the left of the colon. The string of text that will display in game is to the right of the colon, listed within two quotation marks (" "). The colon is the separator.

* The number seen in vanilla files right after the colon can be omitted, as it is only useful for Paradox’s internal translation tracking.<ref>https://twitter.com/Martin_Anward/status/1039175213773144066</ref>
* The file must contain <code>l_english:</code> (or equivalent for other languages) before any localization keys.
* Every entry after <code>l_english:</code> (or equivalent) must begin with whitespace (a space or a tab works).
* Each string to be displayed in game is encased in quotation marks. To display quotation marks in game, input a backslash before each quotation mark (for example: <code>text \"name\"</code>)
* Note that the following unicode characters are invalid inside the localisation file and will generate a "?" instead: <code>„ “ ‚ ‘ – ” ’ … —</code>

== Overwriting Vanilla Text ==
To overwrite vanilla localisation keys (or keys from other mods), create a folder named "replace" inside your "localisation" folder. Localisation files in this folder will load after all other localisation files, and overwrite any duplicate keys. In this way it is not necessary to overwrite entire localisation files, as individual key entries will be overwritten by the last loaded file, LIOS (Last in, only served). It is possible to overwrite localisation without a "replace" folder, however this is not a reliable method.

== Bracket Commands ==
Bracket commands (scoped localization statements) are enclosed in square brackets (<code>[ ]</code>), start with a primary scope, end with a text retrieval, and can have one or more secondary scopes in between. The fields are separated by periods (.). Text retrievals can be predefined (as per examples below), can mention [[Variables]] defined in the scope, or can be a scripted_loc (see common/scripted_loc/ files for examples). When writing "''scripted_loc''" entries, it’s important to note that these entries cannot themselves use bracket commands (i.e., a scripted_loc that includes <code>[Root.GetName]</code> will literally print <code>[Root.GetName]</code>).

Note: if you want to use loc commands e.g. <code>log = [This.GetName]</code> in a [[scripted effect]] or [[scripted trigger|trigger]], you have to write it <code>\\[This.GetName]</code> or it will bug out (at the latest the second time you use one in the effect).

In most cases, it is also possible to get the value of variables with <code>'[Scope.my_variable]'</code> and saved dates with <code>'[Scope.my_date_flag]'</code>.<sup>([[patch 3.1|''since 3.1'']])</sup>

Two consecutive opening square brackets <code>'[['</code> will escape it, making a single square bracket show up in text instead, i.e. <code>'[[example]'</code> in loc will display as '[example]' in-game.

There are also several unscoped commands: <code>GetDate, GetMidGameDate, GetLateGameDate, GetYear, LastKilledCountryName</code>.

Following list is only a part of hardcoded scoped localization commands (it also does not include any scripted locs). A more complete list of commands can be found at <code>Stellaris\logs\script_documentation\localizations.log</code>.

==== Primary Scopes ====
{| class="wikitable"
|-
! Command !! Example usage !! Comments
|-
| Root || [Root.GetName] || The event’s root scope
|-
| This || [This.GetName] || The current scope
|-
| From || [From.From.GetName] || The calling event’s root scope. For events further back in the call stack, From can also be used as a secondary scope
|-
| Prev || [Prev.From.GetName] || The previous scope. It is not obvious to me what Prev.From points to, but some project descriptions use it
|-
| <event target tag> || [mytarget.GetName] || [[Event target]] tags are used without preceding them with <code>event_target:</code> in localisation
|-
! colspan=3 style="font-size:small"| Diplomatic Promotions
|-
| Actor || [Actor.GetAllianceName] || Used in diplomatic response messages. The faction initiating an action
|-
| Recipient || [Recipient.GetName] || Used in diplomatic response messages. The faction targeted by the action
|-
| Third_party || [Third_party.GetName] || Used in diplomatic response messages. A third party involved in the action
|}

==== Secondary Scopes ====
{| class="wikitable"
|-
! Command !! Example usage !! Comments
|-
! colspan=3 style="font-size:small"| Country Promotions: Capital Ruler Heir Species Federation
|-
| Capital || [Root.Capital.GetName] || The capital of the current country or sector

|-
| Leader|| [Root.Leader.GetName] || The leader of the current scope (<small>fleet, country, federation, pop faction, first contact, espionage operation, spy network, sector</small>)
|-
! colspan=3 style="font-size:small"| War Promotions
|-
| MainAttacker || [This.MainAttacker.GetAllianceName] || The main attacker of the current scope (must be used in a war scope), used in war name formats
|-
| MainDefender || [This.MainDefender.GetSpeciesName] || The main defender of the current scope (must be a war scope), used in war name formats
|-
! colspan=3 style="font-size:small"| Planet Promotions: Owner System MoonOf Sector
|-
| Owner || [Root.Owner.GetName] || The current scope’s owner
|-
| System || [Root.System.GetName] || The system where the primary scope is located
|-
| Planet || [Root.Planet.GetName] || The planet where the current scope is located (<small>pop, army, archaeological site, deposit, megastructure</small>)
|}

=== Text Retrieval ===
{| class="wikitable"
|-
! Command !! Example usage !! Comments
|-
| GetAdj || [Root.GetAdj] || The adjective associated with the current scope
|-
| GetAdjective || [Root.GetAdjective] || The adjective associated with the current scope
|-
| GetAllianceName || [This.MainAttacker.GetAllianceName] || The name of the alliance the current scope belongs to
|-
| GetControllerName|| [Root.GetControllerName] || Name of the current controller (known to work on planets)
|-
| GetClassName || [Root.GetClassName] || Name of the current planet class
|-
| GetFleetName || [Root.GetFleetName] || The name of the fleet associated with the current scope
|-
| GetHeirName || [Root.GetHeirName] || The name of the current heir
|-
| GetHeirTitle || [Root.GetHeirTitle] || The title of the current heir
|-
| GetHomeWorldName || [Root.GetHomeWorldName] || The name of the home world of the current scope
|-
| GetLeaderName || [Root.GetLeaderName] || The name of the leader associated with the current scope
|-
| GetName || [Root.GetName] || The name associated with the current scope
|-
| GetFirstName || [Root.GetFirstName] || The name first associated with the current scoped leader
|-
| GetSecondName || [Root.GetSecondName] || The second name associated with the current scoped leader
|-
| GetAge || [Root.GetAge] || The age of the scoped leader
|-
| GetNamePlural || [Root.GetNamePlural] || The plural name associated with the current scope (must be a species)
|-
| GetNebula || [Root.GetNebula] || (unknown)
|-
| GetOwnerName || [Root.GetOwnerName] || Name of the current owner
|-
| GetPersonalityName || [Root.GetPersonalityName] || Get the name of the current AI personality
|-
| GetPlanetMoon || [Root.GetPlanetMoon] || "planet" or "moon" depending on whether the current scope is a planet or moon
|-
| GetPlanetMoonCap || [Root.GetPlanetMoonCap] || "Planet" or "Moon" depending on whether the current scope is a planet or moon
|-
| GetPopFactionName || [Root.GetPopFactionName] || The name of the currently scoped pop’s faction
|-
| GetRandomSpeciesSound || [Root.GetRandomSpeciesSound] || A sound chosen randomly from a list of sounds associated with current scope’s species
|-
| GetRegnalName || [Root.GetRegnalName] || The regnal name of the current scope
|-
| GetRulerName || [Root.GetRulerName] || The name of the ruler associated with the current scope
|-
| GetRulerTitle || [Root.GetRulerTitle] || The title of the ruler associated with the current scope
|-
| GetSpeciesAdj || [Root.GetSpeciesAdj] || The adjective for the species of the current scope
|-
| GetSpeciesClass || [Root.GetSpeciesClass] || The class to which the species of the current scope belongs
|-
| GetSpeciesClassPlural || [Root.GetSpeciesClassPlural] || The plural of the current scope’s species’ clas
|-
| GetSpeciesMouthName || [Root.GetSpeciesMouthName] || The word for the current scope’s species’ mouth
|-
| GetSpeciesName || [Root.GetSpeciesName] || The name of the current scope’s species
|-
| GetSpeciesNameCompliment || [From.GetSpeciesNameCompliment] || A compliment using the current scope’s species
|-
| GetSpeciesNameInsult || [From.From.GetSpeciesNameInsult] || An insult using the current scope’s species
|-
| GetSpeciesNamePlural || [This.GetSpeciesNamePlural] || The plural of current scope’s species’ name
|-
| GetSpeciesNamePluralCompliment || [Root.SpeciesNamePluralCompliment] || A compliment using the plural of the current scope’s species’ name
|-
| GetSpeciesNamePluralInsult || [From.SpeciesNamePluralInsult] || An insult using the plural of the current scope’s species’ name
|-
| GetSpeciesHandName || [From.GetSpeciesHandName] || The word for the current scope’s species’ hand
|-
| GetSpeciesMouthName || [From.GetSpeciesMouthName] || The word for the current scope’s species’ mouth
|-
| GetSpeciesOrganName || [From.GetSpeciesOrganName] || The word for the current scope’s species’ internal organ
|-
| GetSpeciesSpawnName || [Root.GetSpeciesSpawnName || The word for the children of the current scope’s species
|-
| GetSpeciesSpawnNamePlural || [Root.GetSpeciesSpawnNamePlural || The plural word for the children of the current scope’s species
|-
| GetStarName || [Root.Capital.GetStarName] || The name of the star where the current scope is located
|-
| GetHerHim || [admiral.GetHerHim] || Prints 'her' or 'him' based on the character’s gender.
|-
| GetSheHe || [abducted_leader.GetSheHe] || Prints 'she' or 'he' based on the character’s gender.
|-
| GetSheHeCap || [abducted_leader.GetSheHeCap] || Prints 'She' or 'He' based on the character’s gender.
|-
| GetHomeWorldName || [Root.GetHomeWorldName] || The home world name of the selected country
|-
| GetHerHis || [admiral.GetHerHis] || Prints 'her' or 'his’ based on the character’s gender.
|-
| GetHerHisCap || [admiral.GetHerHisCap] || Prints 'Her' or 'His’ based on the character’s gender.
|-
| LastKilledCountryName || [LastKilledCountryName] || Prints the name of the last killed country.
|}

; Added localization commands with [[Patch 3.1]].
 GetSpeciesFossilName
 GetSpeciesFossilNamePlural
 GetSpeciesRemnantName
 GetSpeciesRemnantNamePlural
 Species
 GetFossilName
 GetFossilNamePlural
 GetRemnantName
 GetRemnantNamePlural

== Color Codes ==
[[File:Color codes in-game.png|thumb|Color codes in-game]]
Color codes start with <code>§</code> (Windows users Keypad shortcut: ALT+0167), which is followed by a single character specifying the color to be used until another color code is detected, or the end of the string: <code>§!</code>.  Within a '''<code>$</code>''' command, the color for a displayed variable (not string definition, s. below ''[[#$ Codes|$ Codes]]'') may also be specified by preceding the closing '''<code>$</code>''' with '''<code>{{!}}</code>''' and the color code character: <code>$AGE|Y$</code>

It is also possible to change the text color in game by adding a DC1 UTF-8 character to a color code letter. Please note that doing so may unintentionally color subsequent text if the color is not changed to default at the end.
<code>§RR§Sa§Hi§Yn§Gb§Bo§Mw§!</code> <!-- Editor's note: You cannot get dc1 that easily, can't use &#17; &#x11; just to preview it --> will be displayed as:<span style="color:#D2483B">R</span><span style="color:#B07921">a</span><span style="color:#D69123">i</span><span style="color:#D2D62C">n</span><span style="color:#23BF20">b</span><span style="color:#2B8ED9">o</span><span style="color:#8B2DCB">w</span>

{| class="wikitable sortable"
! Code !! Color !! Vanilla Use
|-
| W || <b style="color:#DCDCDC">White</b> || Diplomatic Attitudes
|-
| T || <b style="color:#D9D9D9">Light grey</b> || Standard color of all text
|-
| L || <b style="color:#9E8F75">Brown</b> || Lore, back story, role playing elements
|-
| P || <b style="color:#BF5E5E">Light red</b> || Highlighting of Aggressive text in descriptions and event text
|-
| R || <b style="color:#D2483B">Red</b> || Negative modifiers
|-
| S || <b style="color:#B07921">Dark orange</b> || Subtle highlighted text
|-
| H || <b style="color:#D69123">Orange</b> || Highlighted text
|-
| Y || <b style="color:#D2D62C">Yellow</b> || Sub-optimal or Neutral modifiers
|-
| G || <b style="color:#23BF20">Green</b> || Positive modifiers
|-
| E || <b style="color:#73D9B0">Teal</b> || Large chunks of text
|-
| B || <b style="color:#2B8ED9">Blue</b> || Event effects that affect pops
|-
| M || <b style="color:#8B2DCB">Purple</b> || Rare technologies
|-
| ! || Default || Return to color before last color change
|}

== $ Codes ==
'''$''' is used to delimit strings (or variables) defined elsewhere to be expanded in the current string, or system statistics in GUI elements.

== Number Formatting ==
The | character can also be used to format numbers. <code>$VALUE|*x$</code> will format <code>VALUE</code> to <code>x</code> decimal places.
<pre>
# EXAMPLE = 100
"$EXAMPLE|*0$" # 100
"$EXAMPLE|*1$" # 100.0
</pre>

== £ Codes ==
£ codes are used for the names of various system stats, including energy, minerals, influence, and the three research categories (engineering, physics and society.) More exist than those listed here, such as <code>£ship_stats_hitpoints\armor\shield£</code>, <code>£fleet_template_size£</code>, and <code>£trigger_yes\no£</code> among others. Search the '£' character using something like Notepad++'s Find in Files feature to find something specific. Remember that £ codes must surround the tag you're inserting, i.e. <code>'''£'''energy'''£'''</code>. (Windows users without the pound symbol on their keyboards can use <code>Alt + 0163</code>.)

It also supports the multiple frames (if the source sprite has them), i.e.: <code>£leader_skill|3£</code> will render an icon of chosen skill level.

{| class="wikitable sortable"
|-
! Code !! Picture
|-
| £energy£ || [[File:Energy Credits.png|40px]]
|-
| £minerals£ || [[File:Minerals.png|40px]]
|-
| £food£ || [[File:Food.png|40px]]
|-
| £influence£ || [[File:Influence.png|40px]]
|-
| £stability£ || [[File:Stability.png|40px]]
|-
| £unity£ || [[File:Unity.png|40px]]
|-
| £alloys£ || [[File:Alloys.png|40px]]
|-
| £trade_value£ || [[File:Trade value.png|40px]]
|-
| £physics£ || [[File:Physics Research.png|40px]]
|-
| £society£ || [[File:Society Research.png|40px]]
|-
| £engineering£ || [[File:Engineering Research.png|40px]]
|-
| £pops£ || [[File:Pop.png|40px]]
|-
| £happiness£ || [[File:Happiness.png|40px]]
|-
| £opinion£ || [[File:Opinion.png|40px]]
|-
| £empire£ || [[File:Empire Modifier.png|40px]]
|-
| £military_ship£ || [[File:Military Ship (icon).png|40px]]
|-
| £military_power£ || [[File:offensive_value.png|40px]]
|-
| £blocker£ || [[File:Tile Blocker.png|40px]]
|-
| £time£ || [[File:Time.png|40px]]
|-
| £planetsize£ || [[File:Planet Size.png|40px]]
|}

== £ Custom Icons ==
You can create custom text icons to appear in game exactly like those above, by saving an icon in ''<root>/gfx/interface/icons/text_icons''. Standard text icons are 16x16 pixel .dds files. In order to reference your icon in text, you will need to define it in the same way you define [[event pictures]]. Save a text file as .gfx in ''<root>/interface/'' Define any custom modifiers as shown below:
<pre>
spriteTypes = {
   spriteType = {
        name = "GFX_text_worker_produces_mult"
        texturefile = "gfx/interface/icons/text_icons/mod_planet_jobs_worker_produces_mult.dds"
    }</pre>
You can link multiple icons by making separate <code>spriteType =</code> blocks. All of these should be within one larger <code>spriteTypes =</code> (with an s) block.

The name must be prefixed <code>GFX_text_</code>. However, to reference this custom icon in localisation, use <code>£worker_produces_mult£</code> (without the prefix) and it will appear alongside in game text.

== Slash-Based Codes ==
The two slash-based codes available are <code>\n</code> and <code>\t</code>.<br>
<code>\n</code> is the equivalent of pressing the Enter key and starting a new line, unless it is inside one of the above codes.<br>
<code>\t</code> places a tab.<br><br>
Backslashes can also be used to treat special characters as text characters, for example <code>\"</code> will make the string contain a quotation mark, instead of closing it off.

== Style Guide ==
Vanilla events, modifiers and all other type of localization follows punctuation and capitalization guidelines. The following table highlights some of the rules employed in the vanilla English localization, allowing custom content to blend in more seamlessly. The table is by no means comprehensive, but instead should serve as a quick cheat-sheet for the most common type of strings.
The number given for Character Limit is not a hard limit. Depending on the location, exceeding the limit might cause the text to be cut off, completely break the UI, or just look ugly and out of place.

{| class="wikitable"
|-
! Location !! Capitalization !! Punctuation !! Character Limit !! Example
|-
| Event Names || Title Case || None || 50 || "Exotic Woodwind"
|-
| Event Descriptions || Sentence case || Standard || 2000 || "Music has taken many forms among the beings we have encountered since leaving [Root.GetHomeWorldName], and the methods and preferences continue to baffle us. Sometimes alien […] Whatever this instrument is, it’s unlike any of our own."
|-
| Event Options || Sentence case || Terminal punctuation || 70 || "An excellent time to learn more about their culture.", "Let us be careful and study this instrument.", "The colony is part of our future. It stays."
|-
| Names for Traits/Modifiers/Buildings/Ethics/etc. || Title Case || None || 30 || "Building Cost", "Massive Crater", "Very Strong"
|-
| Description for Traits/Modifiers/Buildings/Ethics/etc. || Sentence case || Standard || 200 || "The impact site of the meteorite which brought Lithoids to this planet.", "Members of this species possess a strength that almost defies the laws of physics."
|-
| UI Buttons || Sentence case / Title Case || None || Depends on UI || "Withdraw"
|-
| UI Alerts || Title Case || None || Depends on UI || "Relic Activation Available"
|}

== References ==
<references />

{{ModdingNavbox}}
[[Category:模组制作]]