meta data for this page
  •  

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
developer:language [2025/07/17 15:22] – 移除 - 外部编辑 (Unknown date) 127.0.0.1developer:language [2025/07/17 15:22] (当前版本) – ↷ 页面developer:mod:language被移动至developer:language bibiboxs
行 1: 行 1:
 +<markdown>
 +# 游戏多语言适配
 +《沙盘引擎》内游戏语言主要是**引擎原生语言**和**模组语言**配置。
  
 +游戏启动后会有两个语言同时被加载，优先加载**“引擎原生语言”**，加载模组后再进行覆盖加载**“模组语言”**（模组自定义的语言文件）。
 +
 +> ==通常情况下，纯净模组是几乎没有任何默认语言配置的，这里主要是**模组开发者**根据自身作品进行**增删查改**，尤其是和文本交互较多的游戏，可能**模组语言**配置内容会更多。==
 +>
 +> **引擎原生语言**指的是哪怕不加载任何模组（或只加载纯净模组），引擎内一些必定会出现的文本的默认语言配置*（如一些警告、错误提示等，或者是通用的配置内容，比如游戏设置菜单）*。
 +>
 +> **原生语言配置文件**一般是由《沙盘引擎》官方在构建版本时默认提供的，且通常情况下不需要修改。
 +
 +
 +
 +## 语言配置机制
 +
 +《沙盘引擎》在加载初期默认会优先加载**引擎原生语言**，然后在正确加载模组后进行模组目录下的**模组语言**文件加载。
 +
 +**语言文件实际上是一个大型的字典（Table表），开发者需要根据“语言Item标识符”来获取某个词语的不同语言版本，同时在脚本中使用相关API（`GetLanguageText()`）获取翻译的文本结果。**
 +
 +```javascript
 +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导出部分）](https://fairygui.com/docs/editor/i18n)**。
 +
 +> 需要注意，制作一款游戏远不止仅需要修改UI部分的翻译，因为有些游戏内的文本并不属于原生UI内容（而是需要通过代码动态修改），这种类型的UI文本就需要用到**引擎翻译文件**（可通过代码获取一段翻译后的文本），当然也可以选择两种方式共同使用。
 +
 +无论是引擎翻译还是FairyGUI翻译都是相对容易使用的，如果想支持某个新语言，你只需要**先完成一份【默认语言】翻译，随后复制【默认语言】的翻译文件，修改语言名称+翻译对应文本即可**。
 +
 +*如果开发者并不打算支持多语言，也可以不考虑翻译相关的内容，直接用UI编辑器、字符串等方式固定编写。==（如果后期突然想支持多语言，但前期没有留出任何接口，这样工作量可能是很大的）==*
 +
 +| 类型                   | 文件              | 说明                                                         |
 +| ---------------------- | ----------------- | ------------------------------------------------------------ |
 +| 引擎翻译文件           | `Language/*.json` | 更多针对于游戏内及部分UI事件动态文本翻译（通过代码获取翻译结果）<br />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等用法使用即可
 +
 +[note2]
 +
 +注意：此方式将会在内部自动合并json文本，因此应该维护一套自身的翻译Key组合（类似命名空间），避免与其他同名Key冲突替换。
 +
 +[/note]
 +
 +
 +
 +## 原生语言替换
 +
 +> 《沙盘引擎》原生语言和模组语言**共用一个字典序列**，并且最后加载模组语言字典，因此，模组语言配置中如果有**与原生字典路径完全重复的标识**，将会**优先进行读取**，可以使用此机制来替换部分想要修饰的原生语言的内容。==
 +
 +**例如：**引擎原生语言文本有一份`"Native.Welcome"`的翻译项（假设），如果有意在模组内替换这段文本，只需要在**模组语言配置文件（json）**添加一份**完全相同路径**的文本标识即可。
 +
 +```json
 +//Native Language.json
 +{
 +    "ABC": "Some...",
 +    "Native": {
 +        "Welcome": "Welcome SE!"
 +    }
 +}
 +```
 +
 +```json
 +//Mod Language.json (Replace)
 +{
 +    "XXX": "MyModText",
 +    "Native": {
 +        "Welcome": "Welcome to Mod (by SandtableEngine)"
 +    }
 +}
 +```
 +
 +
 +
 +
 +
 +
 +
 +
 +</markdown>