本地化（Localisation）

#文件放在哪、叫什么

游戏里显示的所有文字都来自 localisation\ 下的 .yml 文件。原版按语言分文件夹，简体中文在 localisation\simp_chinese\，文件名都以 _l_simp_chinese.yml 结尾，例如 achievements_l_simp_chinese.yml。模组照此组织：

my_first_mod\
  localisation\
    simp_chinese\
      my_first_mod_l_simp_chinese.yml
    english\
      my_first_mod_l_english.yml

游戏支持的语言键见原版 localisation\languages.yml：l_english、l_simp_chinese、l_japanese、l_korean、l_russian 等。

#编码：必须是 UTF-8 BOM

这是新手最常踩的坑。本地化文件必须以 UTF-8 BOM（文件开头三个字节 EF BB BF）保存。原版每个 .yml 都带 BOM。引擎读取时会检查这三个字节，缺少时在 error.log 里报：

Localization file 'localisation/simp_chinese/xxx_l_simp_chinese.yml' should be in in utf-8-bom encoding

看到这条请立刻改正，不要依赖缺 BOM 的文件“碰巧能用”。VS Code 右下角的编码选择 “UTF-8 with BOM”；记事本另存为时选 “UTF-8 with BOM”。

注意 反过来，脚本 .txt 文件不要带 BOM，原因见加载顺序与覆盖规则。

#文件格式

第一行是语言键加冒号，之后每行一个条目，与原版一样缩进一个空格：

l_simp_chinese:
 # 注释以井号开头
 mymod.1.name: "来自深空的信号"
 mymod.1.desc: "我们的传感器在[Root.Capital.GetName]上空捕捉到了一段规律的信号。\n\n科学家们争论不休。"
 mymod.1.a: "继续监听。"
 mymod.1.b: "§R立刻屏蔽！§!"

• 键与值之间是冒号，值放在双引号里。
• 原版里键后面有时带一个数字（languages.yml 里的 l_english:0 "English"），大多数条目不带，两种都能读。
• \n 表示换行。
• 同一个键在中英文文件里各写一份；只写中文的话，英文玩家会看到键名本身。

#在文本里引用其他内容

#$key$：引用另一个本地化键

 tech_ring_world: "$pc_ringworld_habitable$"
 concept_building: "$buildable_building$"

（均为原版条目。）$...$ 里写另一个键，显示时替换成那个键的文字，适合复用已有译名，保证术语统一。

在提示框类文本里，$...$ 也可能是由代码填入的参数，例如 "$COUNTRY$ wins the game."。静态修正的 custom_tooltip 还支持格式化参数，原版 common/static_modifiers/000_readme.txt 给了例子：

 my_loc_key: "Give $VARIABLE|=+$ shoes and $VARIABLE|=+(3)$ gloves"

其中 % 表示乘 100 加百分号，数字表示保留的小数位，= 表示正数显示加号，+ 表示正绿负红，- 表示正红负绿。

#[...]：本地化命令

方括号里是作用域加取值命令，例如原版 country.50.desc 中的 [Root.Capital.GetName]（当前国家首都的名字）。可用命令列表在控制台 script_docs 导出的 localizations.log 里（见调试）。

#颜色：§

§ 加一个字母开始变色，§! 结束：

 enclave_energy_trade_ended: "没有足够的£energy£ §H能量币§!来维持与商人城邦的资源交易协定。"

颜色字母定义在原版 interface/fonts.gfx 的 textcolors 中，常用的有：

提示 每个 §X 都要有对应的 §! 收尾，否则颜色会一直延续到文本结束。

#图标：£

£图标名£ 在文字里插入一个小图标：

 i_energy: "£energy£§I$energy$§!"

图标名对应 interface/texticons.gfx 里名为 GFX_text_<图标名> 的图形，例如 £energy£ 对应 GFX_text_energy。原版常用的有 £energy£、£minerals£、£food£、£unity£、£physics£、£society£、£engineering£、£pop£、£building£、£district£、£time£、£trigger_yes£、£trigger_no£。

#覆盖原版文本：replace 目录

想修改原版已有的某条文本（比如改一个译名），不要整份复制原版文件。把要改的条目放进路径中含 replace 文件夹的 .yml 里：

my_first_mod\
  localisation\
    simp_chinese\
      replace\
        my_first_mod_replace_l_simp_chinese.yml

l_simp_chinese:
 migrating_forests: "游走森林"

引擎读取本地化时，会先读完所有普通文件，再单独读取路径中含 /replace/ 的文件，并允许它们覆盖已有的键。所以 replace 目录里的条目能稳定压过原版，而不依赖文件名排序。

注意 如果多个模组都在 replace 目录里改了同一个键，谁生效没有官方说明，也没有实测结论。做汉化补丁时尽量只放自己真正要改的键。

#名称语法（进阶）

自 3.6 起，群星有一套处理名称的语法系统（性别、格、词序），主要服务于有屈折变化的语言。原版 localisation\99_README_GRAMMAR.txt 是完整说明；中文本地化一般用不到，但读到 $1$ 这类槽位时可以去那里查。