meta data for this page

📚 游戏多语言适配

《沙盘引擎》内游戏语言主要是引擎原生语言和模组语言配置。

游戏启动后会有两个语言同时被加载，优先加载“引擎原生语言”，加载模组后再进行覆盖加载“模组语言”（模组自定义的语言文件）。

通常情况下，纯净模组是几乎没有任何默认语言配置的，这里主要是模组开发者根据自身作品进行增删查改，尤其是和文本交互较多的游戏，可能模组语言配置内容会更多。

引擎原生语言指的是哪怕不加载任何模组（或只加载纯净模组），引擎内一些必定会出现的文本的默认语言配置（如一些警告、错误提示等，或者是通用的配置内容，比如游戏设置菜单）。

原生语言配置文件一般是由《沙盘引擎》官方在构建版本时默认提供的，且通常情况下不需要修改。

📒 语言配置机制

《沙盘引擎》在加载初期默认会优先加载引擎原生语言，然后在正确加载模组后进行模组目录下的模组语言文件加载。

语言文件实际上是一个大型的字典（Table表），开发者需要根据“语言Item标识符”来获取某个词语的不同语言版本，同时在脚本中使用相关API（GetLanguageText()）获取翻译的文本结果。 

let newText = GetLanguageText("KeyRoot.Key.ItemName");

如果出现【当前游戏语言】配置文件没有找到指定标识的文本类似的问题，代码并不会进行报错，而是返回原始key字符串（KeyRoot.Key.ItemName）。

有关详细的语言文件及配置机制，建议至少打开任意【沙盘引擎语言文件】参考一次，可能会理解更多配置原理。

📒 解释：引擎原生语言

引擎原生语言指《沙盘引擎》默认自带的语言配置（例如加载界面、报错信息、地图编辑器等）（路径.\Language）。

如果存在当前用户语言配置，将会自动设置并显示为当前用户的语言界面，因此引擎通用的UI文本并不需要开发者进行额外适配。

反之亦然，自定义模组不属于原生通用的语言范畴，因此就需要模组开发者在模组语言自行配置需要用到的语言翻译。

📒 解释：模组语言

模组语言指除了《沙盘引擎》原生框架外的模组自定义语言配置（路径LocalMod\Language）。

例如：开发者可能正在开发一款赛车游戏模组，这在很多方面可能有新的名词词汇，所以为了能让其他语言玩家可以正常体验，开发者就需要根据情况加入新的语言配置。

举例：赛车游戏中拥有载具等级（初级、普通、高级等），以及游戏里面的相关词汇（载具商店、改装、比赛等），这就需要开发者在模组语言配置文件根据需要新增语言项目键值，并自行根据逻辑在脚本中控制使用。

📒 语言加载及逻辑

经过前文介绍，我们已经了解引擎原生语言和模组语言的分工区别，在实际语言加载环节，语言文件有着一些优先级与逻辑冲突解决。

默认情况下，模组语言文件优先级最高，其次是引擎原生语言。

在引擎及游戏模组运行加载时，会优先参考【玩家用户系统语言】，并检查引擎及模组语言目录是否存在对应的语言，如果存在则尝试使用目标文件，否则将使用默认语言（English）。

📒 标准语言标识

根据《沙盘引擎》近期版本的官方自带原生语言，以下语言是版本自带且建议模组开发者也应该优先考虑的语言（除非确定几乎不会有某种语言的玩家）。

语言文件必须严格按照标准语言标识文件命名。

标准语言标识说明
Afrikaans南非荷兰语
Arabic阿拉伯语
Basque巴斯克语
Belarusian白俄罗斯语
Bulgarian保加利亚语
Catalan加泰罗尼亚语
Czech捷克语
Danish丹麦语
Dutch荷兰语
English英语
Estonian爱沙尼亚语
Faroese法罗语
Finnish芬兰语
French法语
German德语
Greek希腊语
Hebrew希伯来语
Icelandic冰岛语
Indonesian印尼语
Italian意大利语
Japanese日语
Korean韩语
Latvian拉脱维亚语
Lithuanian立陶宛语
Norwegian挪威语
Polish波兰语
Portuguese葡萄牙语
Romanian罗马尼亚语
Russian俄语
SerboCroatian塞尔维亚-克罗地亚语
Slovak斯洛伐克语
Slovenian斯洛维尼亚语
Spanish西班牙语
Swedish瑞典语
Thai泰语
Turkish土耳其语
Ukrainian乌克兰语
Vietnamese越南语
ChineseSimplified简体中文
ChineseTraditional繁体中文
Hungarian匈牙利语
Unknown未知

📒 多语言翻译文件

《沙盘引擎》每种游戏语言同时包含引擎翻译文件（json）、FairyGUI翻译文件（xml）。

开发者通常在使用FairyGUI制作UI内容时，对于UI文本通常会选择直接在编辑器进行文本修改，这样虽然简化了部分UI翻译的流程，但是不可避免的要使用到FairyGUI提供的的多语言翻译方案（只需参考XML导出部分）。

需要注意，制作一款游戏远不止仅需要修改UI部分的翻译，因为有些游戏内的文本并不属于原生UI内容（而是需要通过代码动态修改），这种类型的UI文本就需要用到引擎翻译文件（可通过代码获取一段翻译后的文本），当然也可以选择两种方式共同使用。

无论是引擎翻译还是FairyGUI翻译都是相对容易使用的，如果想支持某个新语言，你只需要先完成一份【默认语言】翻译，随后复制【默认语言】的翻译文件，修改语言名称+翻译对应文本即可。

如果开发者并不打算支持多语言，也可以不考虑翻译相关的内容，直接用UI编辑器、字符串等方式固定编写。（如果后期突然想支持多语言，但前期没有留出任何接口，这样工作量可能是很大的）

类型 文件 说明
引擎翻译文件 Language/*.json 更多针对于游戏内及部分UI事件动态文本翻译（通过代码获取翻译结果）
FairyGUI本身的翻译不足以完全进行多语言控制和动态修改，两者可以共同使用
UI翻译文件（FairyGUI） Language/*.xml 只针对FairyGUI编辑器内存在的组件文本翻译，可由UI编辑器导出生成

📘 翻译文件注意事项

翻译语言文件需要确保存放目录、文件名、文件名后缀正确，文件名必须使用【标准语言标识】（例如English | ChineseSimplified），具体的【语言名称（例如：English -> English | ChineseSimplified -> 简体中文）】应该在语言json内部填写（以供引擎识别语言名称）。

如果语言需要用到FairyGUI导出的xml翻译文件，只需要在对应语言的.json同级目录，将.xml文件导出到同级目录，并将文件名修改为与.json同名即可（例如：english.json | english.xml）。

语言文件无论是json还是xml，均可以单独或共同存在，只需要按照上述规范正确导出和放置即可。

📘 子翻译文件

在部分特殊情况下，可能存在模组插件、第三方扩展等额外的翻译情况。

例如：模组插件本身可能有自身需要的翻译文本（json），很显然不能强制用户手动更新\合并json，此情况只需利用【子翻译文件】机制即可。

当模组被加载时，会自动识别模组目录内所有/Language/{CurrentLanguage}.json格式的文件，并尝试作为翻译文件进行加载（即使没有被使用）。

因此，例如Plugin插件需要编写自己的翻译文本，只需要执行以下步骤：

  1. 例如自身插件为MyPlugin，在插件目录新建文件夹Language，并建立子文件English.json（根据语言名称调整）
  2. 按照本文内容正常编写English.json语言文件
  3. 加载此模组时，如果用户语言相同（English），则会自动叠加（合并）载入Plugin/MyPlugin/Language/English.json
  4. 按照正常语言API等用法使用即可

注意：此方式将会在内部自动合并json文本，因此应该维护一套自身的翻译Key组合（类似命名空间），避免与其他同名Key冲突替换。

📒 原生语言替换

《沙盘引擎》原生语言和模组语言共用一个字典序列，并且最后加载模组语言字典，因此，模组语言配置中如果有与原生字典路径完全重复的标识，将会优先进行读取，可以使用此机制来替换部分想要修饰的原生语言的内容。==

例如：引擎原生语言文本有一份"Native.Welcome"的翻译项（假设），如果有意在模组内替换这段文本，只需要在模组语言配置文件（json）添加一份完全相同路径的文本标识即可。 

//Native Language.json
{
    "ABC": "Some...",
    "Native": {
        "Welcome": "Welcome SE!"
    }
}
//Mod Language.json (Replace)
{
    "XXX": "MyModText",
    "Native": {
        "Welcome": "Welcome to Mod (by SandtableEngine)"
    }
}