Reloaded-II 启动器本地化指南:基于 XAML 资源字典的多语言翻译体系
Reloaded-II 启动器本地化指南:基于 XAML 资源字典的多语言翻译体系
本文围绕 Reloaded-II 启动器的本地化(Localization)机制展开,讲解其基于 WPF XAML 资源字典的语言加载原理、翻译文件的存放位置与格式规范,以及从零创建/维护一种语言翻译的完整实操流程。读完本文,你将能够为 Reloaded-II 启动器新增或更新任意语言的界面翻译,并理解其"以 en-GB.xaml 为基准、缺失自动回退英文"的设计逻辑。
本地化现状与覆盖范围
Reloaded-II 启动器(Launcher)完整支持界面本地化:启动器的全部用户界面文本都可以被翻译成另一种语言,并以下拉框切换。需要注意,当前本地化的实现相对原始,只覆盖启动器本身——Mod Loader 加载器与被加载的 Mod 并不参与本地化,游戏内的 Mod 文本自然也不会被翻译。
因此,本地化文件的维护对象是启动器 UI 中的每一段可见文本:页面标题、按钮、对话框消息、错误提示、工具提示等,全部以"键(Key)+ 文本值"的形式集中在语言文件中管理。
工作原理:XAML 资源字典 + 自动填充下拉框
Reloaded-II 的本地化不是传统的 .resx 或资源字符串方案,而是直接复用 WPF 的 ResourceDictionary(资源字典)能力:
- 语言文件即 XAML 资源字典:启动器从
Languages文件夹加载一个 XAML(本质上就是 XML)文件,其中每一条翻译都是<sys:String x:Key="...">形式的资源条目。 - 下拉框自动填充:启动器内的语言下拉框会自动扫描该文件夹,按文件名列出所有可用语言,无需手工维护列表。
- 缺失回退英文(英国):当界面某段文本在当前语言文件中找不到对应 Key 时,会自动回退到默认语言文件 en-GB.xaml 中的英文(Great Britain)文本——这正是
en-GB.xaml必须始终保持完整、且永远被当作基准文件的原因。
从源码结构看,这套机制由 XamlFileSelector.cs 承载:它继承自 ResourceDictionary 并实现 IResourceFileSelector 接口(接口定义见 IResourceFileSelector.cs),以 *.xaml 为过滤条件监听目录,把"文件选择"与"运行时资源字典热加载"合二为一:
Files属性:当前目录下全部可用.xaml文件(ObservableCollection<string>);File属性:当前选中的语言文件,设置后即把Source指向该 XAML 并刷新资源字典;SelectXamlFileByName(fileName):按文件名精确匹配并切换语言;- 内置
FileSystemWatcher:监听目录内文件的创建/删除/变更事件,向Languages文件夹中新增一个.xaml文件后无需重启启动器,下拉框即会自动出现新语言。
语言文件存放位置
语言文件的存放位置取决于你使用的是发布版还是源码版:
| 场景 | 存放目录 |
|---|---|
| 下载/发布的 Release 版本 | 启动器(Launcher)目录下的 Languages 文件夹 |
| 源码编译版本 | source/Reloaded.Mod.Launcher/Assets/Languages |
对于源码版本,Reloaded.Mod.Launcher.csproj 通过 <Content Include="Assets\Languages\**\*.xaml"> 将所有语言文件作为内容随构建输出复制,最终产物中同样表现为启动器目录下的 Assets\Languages(运行时加载路径见下文源码分析)。当前仓库自带的语言文件包括 14 种:
de-DE.xaml(德语)、en-GB.xaml(英语·英国)、es-419.xaml(西班牙语·拉美)、es-ES.xaml(西班牙语·西班牙)fr-FR.xaml(法语)、ja-JP.xaml(日语)、nl-NL.xaml(荷兰语)、pt-BR.xaml(葡萄牙语·巴西)、pt-PT.xaml(葡萄牙语·葡萄牙)ru-RU.xaml(俄语)、zh-CN.xaml(简体中文)、zh-TW.xaml(繁体中文)- 以及两个社区趣味语言:
pirate.xaml(海盗语)、uwu.xaml
翻译文件格式详解
以基准文件 en-GB.xaml 为例,翻译文件是一个标准的 WPF ResourceDictionary,文件头部固定为:
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:sys="clr-namespace:System;assembly=mscorlib"
xml:space="preserve">
文件内的每条翻译都是 sys:String 资源,格式为:
<sys:String x:Key="TitleAddApplication">Add an Application</sys:String>
<sys:String x:Key="MessageBoxButtonOK">OK</sys:String>
<sys:String x:Key="MessageBoxButtonCancel">Cancel</sys:String>
编写翻译文件时必须注意以下规范:
-
x:Key是唯一标识符:界面代码(XAML 绑定或 C# 代码)通过 Key 查找文本。翻译时只修改尖括号内的文本内容,绝不修改 Key,否则界面将找不到对应文本而回退英文。 -
换行转义:文件中不支持直接换行,需要用

(ASCII 换行字符的 XML 实体)表示换行。例如:<sys:String x:Key="AddAppAutoInjectMessage">Note: Auto-inject is provided but not recommended as no guarantee can be made that mods will execute code before the application.
Please instead use regular "Launch Application" from Reloaded or the "DLL Loader" method described in the GitHub documentation.
Please do not submit bugs for mods that do not work using Auto-inject mode.</sys:String>这条消息在界面上会显示为三行。
-
占位符:部分文本包含
{0}、{1}之类的格式化占位符,如InstalledModsDescription的Installed {0} Mod(s)、InstallModPackDownloading的Downloading {0}...,翻译时占位符必须原样保留,否则运行时格式化会出错。 -
XML 特殊字符转义:文本中的
&需写成&(如Advanced Tools & Options),<、>同理需转义。 -
注释约定:文件顶部声明
<!-- This file contains the ... Language Text for Reloaded II -->,正文中以<!-- Page Titles -->、<!-- Update 1.12.0: ... -->等注释按界面模块与版本更新划分段落,方便对照维护。
对照 zh-CN.xaml,同一 Key 的中文译文示例如下:
<sys:String x:Key="TitleAddApplication">添加应用程序</sys:String>
<sys:String x:Key="TitleManageMods">管理 Mods</sys:String>
<sys:String x:Key="LoaderSettingsConfigLanguage">语言</sys:String>
源码级实现:语言从配置到界面渲染的完整链路
要真正理解这套本地化机制,可以沿着源码梳理"语言文件如何被选中并渲染到界面"的完整调用链:
- 默认资源合并:App.xaml 在应用启动时即把
Assets/Languages/en-GB.xaml作为默认合并资源字典加载,保证任何界面在任何语言生效前都有英文兜底。 - 启动时初始化:App.xaml.cs 的
SetupResources()中,启动器用new XamlFileSelector($"{launcherFolder}\\Assets\\Languages")创建语言选择器;若是首次启动(FirstLaunch),还会读取系统区域设置(CurrentUICulture),自动匹配zh-CN.xaml之类的系统语言文件;随后按LoaderConfig.LanguageFile中保存的配置调用SelectXamlFileByName选中语言,并将选择器本身加入Resources.MergedDictionaries实现热切换。 - 配置持久化:LoaderConfig.cs 中
LanguageFile属性(默认值en-GB.xaml)记录了用户选中的语言文件,随启动器配置一起持久化。 - 设置页绑定:SettingsPage.xaml 中的语言下拉框以
LanguageSelector.Files为数据源、LanguageSelector.File为当前选中项,并通过FilePathToFileConverter把完整路径显示为纯文件名。 - 保存选择:SettingsPageViewModel.cs 的
SaveNewLanguageAsync()把当前选择写入LoaderConfig.LanguageFile并序列化到配置文件,重启后语言保持。 - 代码侧取文本:启动器库通过 Resources.cs 以反射方式将 XAML 中的 Key 映射为强类型静态属性(属性名即 Key),供 C# 代码统一调用,与 XAML 侧的
DynamicResource绑定共用同一资源字典。
实操:创建一种新的翻译
创建新语言翻译的流程非常简单,官方推荐步骤如下:
- 复制基准文件:复制
en-GB.xaml(默认语言文件)并重命名为目标语言,例如新建ko-KR.xaml(韩语)。命名建议遵循 BCP 47 语言标记风格(如zh-CN、pt-BR),因为首次启动时系统会自动匹配CurrentUICulture + ".xaml"文件名。 - 放置到语言目录:把新文件放入启动器的
Languages文件夹(发布版)或 source/Reloaded.Mod.Launcher/Assets/Languages(源码版)。若启动器正在运行,得益于FileSystemWatcher,下拉框中会立即出现新语言。 - 逐条翻译:用任意文本编辑器打开文件,将每个
<sys:String>标签内的英文文本替换为目标语言译文。保留x:Key不变,遵循上文提到的换行实体、占位符与 XML 转义规范。 - 切换到新语言验证:在启动器"Mod Loader Settings → Language"下拉框中选择新语言,逐页检查译文是否完整、是否有明显缺漏(缺漏项会显示为英文)。
实操:更新既有翻译与完整性判断
随着 Reloaded-II 持续迭代,每次更新都会在 en-GB.xaml 末尾追加新的文本条目(同时附带 <!-- Update x.y.z: ... --> 注释标注来源版本)。因此维护翻译的流程是:
- 对比缺失条目:将你维护的语言文件与最新版
en-GB.xaml逐条比对,找出缺失的 Key; - 追加到文件末尾:把缺失的条目连同其英文原文的译文追加到你的翻译文件末尾,不要打乱既有顺序;
- 完整性自检:判断一个翻译是否"完整",最直接的方法是检查该语言文件的最后一个文本条目是否与
en-GB.xaml的最后一个文本条目 Key 一致——因为新文本永远追加在基准文件底部,若两者末尾一致,说明已同步到最新版本(en-GB.xaml当前最后一个条目是Update 1.30.0版本的No/Yes键)。
局限性说明
在提交翻译前需知悉以下现状(原文档明确说明,且源码未显示相关支持):
- 本地化仅作用于启动器界面,Mod Loader(加载器运行时)与各个 Mod 的界面/游戏内文本均不参与翻译;
- 当前实现被作者描述为"primitive(原始)",主要体现在:无运行时热重载的字体适配、无自动语言包下载机制、翻译完整性只能靠人工比对文件末尾条目来保证;
- 新增语言后,若启动器是源码编译产物,新文件需随构建一并输出(csproj 的
Content Include已覆盖Assets\Languages\**\*.xaml,置于该目录即可)。
总而言之,Reloaded-II 的本地化是一套轻量而开放的文件驱动方案:任何用户都可以通过复制、翻译一个 XAML 文件为启动器贡献一种新语言,而无需修改任何代码。