编辑“模组本地化”

{{Version|3.1}}
本地化是指在游戏内窗口实际呈现给玩家的文本，如事件、菜单、武器、故事等。本地化文件以.yml的格式保存在localisation/folder路径底下，且以[[wikipedia:UTF-8-BOM|UTF-8-BOM]]的格式编码。[[wikipedia:.yml|.yml]]文件的命名惯例是'''<文件名>_l_<语言名>.yml'''，其中<文件名>为这组本地化的名字，而<语言名>为本地化的目标语言。目前支持的语言有葡萄牙语（braz_por），英语（english），法语（french），德语（german），波兰语（polish），俄语（russian），西班牙语（spanish），以及简体中文（simp_chinese）。

实用指令：
 reload text – 重新加载本地化目录。
 switchlanguage l_english – 切换语言并重新加载本地化目录。

=== 创建本地化文件 ===
* 在模组的根文件夹（注意不在common里）创建一个名为“localisation”的文件夹。注意，在某些别的paradox游戏里用的可能是美式拼写、带有z的“localization”。
* （可选）在“localisation”文件夹中创建对应语言的子文件夹。这有助于管理，但不是必需的。
* 群星的本地化文件是用UTF-8-BOM编码的。UTF-8-BOM是'''唯一可用'''的编码方式，就算用UTF-8编码也会导致群星无法解析从而不能使用。
* 正确编码的最简单做法是复制一个现成的群星.yml文件，再直接对其进行编辑。
* 作为替代，你也可以创建一个标准的空白文本文档，再以UTF-8-BOM编码保存它。类似[[wikipedia:Notepad++|Notepad++]]和[[wikipedia:Visual Studio Code|Visual Studio Code]]这样的文本编辑器能让你手动将文件保存为UTF-8-BOM编码格式。
* 文件名必须以''“_l_<语言名>”''结尾，否则无法被读取。
* 任何本地化文件的第一行都必须是<code>l_<language>:</code>，否则无法被读取。
* 范例文件名：<code>mod_buildings_l_english.yml</code>

将YML文件命名为与一个原版YML文件相同会导致原版被覆盖。这么做并不推荐， 除非你打算改写文件内（几乎）所有的条目。本地化条目可以通过保存到“Replace”文件夹以单独进行覆盖，详见[[#Overwriting Vanilla Text|覆盖原版文本]]。

遗憾的是，游戏并没有适配模组的语言回滚功能。这意味着当本地化键值缺失时，键值会直接以文本形式呈现。因此，对应的做法是先直接把英语文件复制到其他所有语言里（改成合适的标题）。

=== 文件编码 ===
* 使用一个文本编辑器打开YML文件。推荐使用类似[https://www.notepad-plus-plus.org/ Notepad++]和[https://code.visualstudio.com/ Visual Studio Code] 这样的编辑器，如果上述软件不可用的话，普通的记事本也行。
* 将文件转码成UTF-8-BOM的格式。
* 使用Notepad++时，前往菜单栏，打开''编码'' 界面。
* 使用Visual Studio Code时，前往右下角并点击编码（默认为<code>UTF-8</code>），再点击保存编码。作为替代，也可以通过改变设置来让VSC默认以''UTF-8-BOM'' 格式生成YML文件。 
* 使用记事本时，前往''另存为...''，改变编码并保存文件。
** 如果列出来的选项中同时有UTF-8 和UTF-8 with BOM（或相似的名称），选用UTF-8-BOM。
** 如果列出来的选项中同时有UTF-8 和UTF-8 without BOM（或相似的名称），选用UTF-8。【译注：即一定要带BOM】

=== 本地化键值 ===
 
 l_<语言名>:
  localisation_key_1: "文本1"
  localisation_key_2: "文本2"
每个单独的本地化条目被称为“键值”，位于冒号的左侧，是指向本地化文本的实际代码。而游戏内显示的文本则位于冒号的右侧，包夹在双引号（""）里。冒号是分隔符。

* 原版文件中紧接在冒号后面的数字可以被忽略，那是Paradox内部用于跟踪翻译用的。<ref>https://twitter.com/Martin_Anward/status/1039175213773144066</ref>
* 在出现任何本地化键值之前，文件必须先包含<code>l_english:</code> （或其他语言的相等形式）。
*<code>l_english:</code>（或相等）之后的所有条目必须以空格开始（空格或tab都行）。
* 所有要在游戏内显示的文本都被双引号所包裹。想在游戏内显示双引号的话，请在双引号前面加上反斜杠（例如：<code>text \"name\"</code>）。
* 注意以下这些unicode字符在本地化文件中是不可用的，会生成一个“?”：<code>„ “ ‚ ‘ – ” ’ … —</code>

== 覆盖原版文本 ==
想要覆盖原版本地化键值（或其他模组的键值）时，在你的“localisation”文件夹底下创建一个名为“replace”的文件夹。该文件夹中的本地化文件的读取比其他所有本地化文件都晚，能覆盖掉任何重复的键值。这样做可以避免覆盖所有本地化文件，每个键值条目会单独被最后加载的文件所覆盖。不通过“replace”文件夹来覆盖本地化是可行的，但并不可靠。

== 方括号指令 ==
方括号指令（范围本地化声明） 用方括号（<code>[ ]</code>）包裹，以一个主对象范围为开头，一段检索用文本为结尾。中间可以包含一个或数个次对象范围。目标之间用小数点号（.）分隔。文本检索可以提前定义（参考下方的例子），可以引用对象范围中声明的变量，也可以是段scripted_loc【即带脚本的语言文件】（参考common/scripted_loc底下的文件）。在写“''scripted_loc''”条目时，要注意这些条目本身不能用方括号指令（例如：一段带有<code>[Root.GetName]</code>的scripted_loc会直接原封不动地显示<code>[Root.GetName]</code>）。

注意：如果你想在[[scripted effect|脚本效果]]或[[scripted trigger|触发器]]中使用例如 <code>log = [This.GetName]</code> 这样的本地化指令，你得把它写成<code>\\[This.GetName]</code>，不然就会出错（至少会在效果中第二次使用时出现）。

大多数情况下可以通过<code>'[Scope.my_variable]'</code>来获取变量的赋值，以及通过<code>'[Scope.my_date_flag]'</code>来获取保存的日期。<sup>([[patch 3.1|''从3.1起'']])</sup>

两个连续的左方括号 <code>'[['</code> 会跳过指令，使一个单独的方括号呈现在文本里。例如文件中的<code>'[[范例]'</code> 会在游戏中显示为'[范例]'。

有几条指令是无范围的：<code>GetDate, GetMidGameDate, GetLateGameDate, GetYear, LastKilledCountryName</code>。

下方表格只记录了一部分的硬编码范围本地化指令（也没有涉及任何脚本语言文件）。一份更详尽的代码名单可以在<code>Stellaris\logs\script_documentation\localizations.log</code>里找到。

==== 主作用域 ====
{| class="wikitable"
|-
! 指令 !! 使用范例 !! 注释
|-
| Root || [Root.GetName] || 事件的根对象范围
|-
| This || [This.GetName] || 当前对象范围
|-
| From || [From.From.GetName] || 调用事件的对象范围。对于调用栈中更早位置的事件，From也可以充当次对象范围
|-
| Prev || [Prev.From.GetName] || 上一个目标。我不清楚Prev.From指向的是什么，不过有些项目的描述中有用到。
|-
| <event target tag> || [mytarget.GetName] || [[Event target|事件目标（Event target）]]标签要在本地化文件中声明<code>event_target:</code>后才能使用。
|-
! colspan=3 style="font-size:small"| 外交活动
|-
| Actor || [Actor.GetAllianceName] || 用于外交回应消息，发起行动的一方
|-
| Recipient || [Recipient.GetName] || 用于外交回应消息，作为行动目标的一方
|-
| Third_party || [Third_party.GetName] || 用于外交回应消息，行动中牵涉到的第三方
|}

==== 次作用域 ====
{| class="wikitable"
|-
! 指令 !! 使用范例 !! 注释
|-
! colspan=3 style="font-size:small"| 国家活动：首都/统治者/继承人/物种/联邦
|-
| Capital || [Root.Capital.GetName] || 当前国家或星区的首都

|-
| Leader|| [Root.Leader.GetName] || 当前对象范围的领导人（<small>舰队、国家、联邦、人口派系、第一次接触、情报行动、间谍网、星区</small>）
|-
! colspan=3 style="font-size:small"| 战争活动
|-
| MainAttacker || [This.MainAttacker.GetAllianceName] || 当前对象范围的主进攻者（对象范围必须是战争），在战争名称样式中使用。
|-
| MainDefender || [This.MainDefender.GetSpeciesName] || 当前对象范围的主防御者（对象范围必须是战争），在战争名称样式中使用。
|-
! colspan=3 style="font-size:small"| 星球活动：拥有者/所在星系/卫星/星区
|-
| Owner || [Root.Owner.GetName] || 当前对象范围的拥有者
|-
| System || [Root.System.GetName] || 主对象范围所在的星系
|-
| Planet || [Root.Planet.GetName] || 当前对象范围所处的星球（<small>人口、陆军、考古遗址、资源点、巨构建筑</small>）
|}

=== 文本检索 ===
{| class="wikitable"
|-
! 指令 !! 使用范例 !! 注释
|-
| GetAdj || [Root.GetAdj] || 当前对象范围所关联的形容词
|-
| GetAdjective || [Root.GetAdjective] || 当前对象范围所关联的形容词
|-
| GetAllianceName || [This.MainAttacker.GetAllianceName] || 当前对象范围所属的军事同盟的名称
|-
| GetControllerName|| [Root.GetControllerName] || 当前控制者的名称（已知能对星球生效）
|-
| GetClassName || [Root.GetClassName] || 当前星球种类的名称
|-
| GetFleetName || [Root.GetFleetName] || 与当前对象范围关联的舰队名称
|-
| GetHeirName || [Root.GetHeirName] || 当前继承人的名字
|-
| GetHeirTitle || [Root.GetHeirTitle] || 当前继承人的头衔
|-
| GetHomeWorldName || [Root.GetHomeWorldName] || 当前对象范围的母星名称
|-
| GetLeaderName || [Root.GetLeaderName] || 与当前对象范围关联的领袖名称
|-
| GetName || [Root.GetName] || 与当前对象范围关联的名称
|-
| GetFirstName || [Root.GetFirstName] || 与当前对象领袖关联的第一个名称
|-
| GetSecondName || [Root.GetSecondName] || 与当前对象领袖关联的第二个名称
|-
| GetAge || [Root.GetAge] || 对象领袖的年龄
|-
| GetNamePlural || [Root.GetNamePlural] || 与当前对象范围关联的复数称谓（必须是一个物种）
|-
| GetNebula || [Root.GetNebula] || （未知）
|-
| GetOwnerName || [Root.GetOwnerName] || 当前所有者的名称
|-
| GetPersonalityName || [Root.GetPersonalityName] || 当前AI性格的名称
|-
| GetPlanetMoon || [Root.GetPlanetMoon] || 返回“星球”或者“卫星”，取决于当前对象范围是哪一种
|-
| GetPlanetMoonCap || [Root.GetPlanetMoonCap] || 返回“星球”或者“卫星”，取决于当前对象范围是哪一种【与上条区别在于英文首字母大写】
|-
| GetPopFactionName || [Root.GetPopFactionName] || 当前对象的人口派系的名称
|-
| GetRandomSpeciesSound || [Root.GetRandomSpeciesSound] || 从当前对象物种相关联的声音列表里随机选一个进行播放
|-
| GetRegnalName || [Root.GetRegnalName] || 当前对象范围的尊称
|-
| GetRulerName || [Root.GetRulerName] || 当前对象范围关联的统治者名称
|-
| GetRulerTitle || [Root.GetRulerTitle] || 当前对象范围关联的统治者头衔
|-
| GetSpeciesAdj || [Root.GetSpeciesAdj] || 当前对象范围的物种的形容词形式
|-
| GetSpeciesClass || [Root.GetSpeciesClass] || 当前对象范围的物种所属类别
|-
| GetSpeciesClassPlural || [Root.GetSpeciesClassPlural] || 当前对象范围的物种所属类别的复数形式
|-
| GetSpeciesMouthName || [Root.GetSpeciesMouthName] || 当前对象范围的物种所属类别的嘴巴的名称
|-
| GetSpeciesName || [Root.GetSpeciesName] || 当前对象范围的物种名称
|-
| GetSpeciesNameCompliment || [From.GetSpeciesNameCompliment] || 用当前对象物种的名字发出一条赞美
|-
| GetSpeciesNameInsult || [From.From.GetSpeciesNameInsult] || 用当前对象物种的名字发出一条侮辱
|-
| GetSpeciesNamePlural || [This.GetSpeciesNamePlural] || 当前对象物种名称的复数形式
|-
| GetSpeciesNamePluralCompliment || [Root.SpeciesNamePluralCompliment] || 用当前对象物种的复数称谓发出一条赞美
|-
| GetSpeciesNamePluralInsult || [From.SpeciesNamePluralInsult] || 用当前对象物种的复数称谓发出一条侮辱
|-
| GetSpeciesHandName || [From.GetSpeciesHandName] || 描述当前对象物种的手的词
|-
| GetSpeciesMouthName || [From.GetSpeciesMouthName] || 描述当前对象物种的嘴的词
|-
| GetSpeciesOrganName || [From.GetSpeciesOrganName] || 描述当前对象物种的内部器官的词
|-
| GetSpeciesSpawnName || [Root.GetSpeciesSpawnName || 描述当前对象物种的小孩的词
|-
| GetSpeciesSpawnNamePlural || [Root.GetSpeciesSpawnNamePlural || 当前对象物种的小孩的复数称谓
|-
| GetStarName || [Root.Capital.GetStarName] || 当前对象范围所在的恒星的名字
|-
| GetHerHim || [admiral.GetHerHim] || 按角色的性别输出“他”或“她”
|-
| GetSheHe || [abducted_leader.GetSheHe] || 按角色的性别输出“他”或“她”
|-
| GetSheHeCap || [abducted_leader.GetSheHeCap] || 按角色的性别输出“他”或“她”【与上条区别在于英文首字母大写】
|-
| GetHomeWorldName || [Root.GetHomeWorldName] || 选中国家的母星名称
|-
| GetHerHis || [admiral.GetHerHis] || 按角色的性别输出“他的”或“她的”
|-
| GetHerHisCap || [admiral.GetHerHisCap] || 按角色的性别输出“他的”或“她的”【与上条区别在于英文首字母大写】
|-
| LastKilledCountryName || [LastKilledCountryName] || 输出上一个所灭亡的国家名称
|}

; 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:模组制作]]