Reloaded-II 启动器本地化指南:基于 XAML 资源字典的多语言翻译体系

原创2026-10-13 12:10:571,936 阅读
文章标签:游戏开发桌面应用插件系统逆向工程

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(资源字典)能力:

  1. 语言文件即 XAML 资源字典:启动器从 Languages 文件夹加载一个 XAML(本质上就是 XML)文件,其中每一条翻译都是 <sys:String x:Key="..."> 形式的资源条目。
  2. 下拉框自动填充:启动器内的语言下拉框会自动扫描该文件夹,按文件名列出所有可用语言,无需手工维护列表。
  3. 缺失回退英文(英国):当界面某段文本在当前语言文件中找不到对应 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,否则界面将找不到对应文本而回退英文。

  • 换行转义:文件中不支持直接换行,需要用 &#x0a;(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.&#x0a;Please instead use regular "Launch Application" from Reloaded or the "DLL Loader" method described in the GitHub documentation.&#x0a;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 特殊字符转义:文本中的 & 需写成 &amp;(如 Advanced Tools &amp; 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>

源码级实现:语言从配置到界面渲染的完整链路

要真正理解这套本地化机制,可以沿着源码梳理"语言文件如何被选中并渲染到界面"的完整调用链:

  1. 默认资源合并:App.xaml 在应用启动时即把 Assets/Languages/en-GB.xaml 作为默认合并资源字典加载,保证任何界面在任何语言生效前都有英文兜底。
  2. 启动时初始化:App.xaml.cs 的 SetupResources() 中,启动器用 new XamlFileSelector($"{launcherFolder}\\Assets\\Languages") 创建语言选择器;若是首次启动(FirstLaunch),还会读取系统区域设置(CurrentUICulture),自动匹配 zh-CN.xaml 之类的系统语言文件;随后按 LoaderConfig.LanguageFile 中保存的配置调用 SelectXamlFileByName 选中语言,并将选择器本身加入 Resources.MergedDictionaries 实现热切换。
  3. 配置持久化:LoaderConfig.cs 中 LanguageFile 属性(默认值 en-GB.xaml)记录了用户选中的语言文件,随启动器配置一起持久化。
  4. 设置页绑定:SettingsPage.xaml 中的语言下拉框以 LanguageSelector.Files 为数据源、LanguageSelector.File 为当前选中项,并通过 FilePathToFileConverter 把完整路径显示为纯文件名。
  5. 保存选择:SettingsPageViewModel.cs 的 SaveNewLanguageAsync() 把当前选择写入 LoaderConfig.LanguageFile 并序列化到配置文件,重启后语言保持。
  6. 代码侧取文本:启动器库通过 Resources.cs 以反射方式将 XAML 中的 Key 映射为强类型静态属性(属性名即 Key),供 C# 代码统一调用,与 XAML 侧的 DynamicResource 绑定共用同一资源字典。

实操:创建一种新的翻译

创建新语言翻译的流程非常简单,官方推荐步骤如下:

  1. 复制基准文件:复制 en-GB.xaml(默认语言文件)并重命名为目标语言,例如新建 ko-KR.xaml(韩语)。命名建议遵循 BCP 47 语言标记风格(如 zh-CN、pt-BR),因为首次启动时系统会自动匹配 CurrentUICulture + ".xaml" 文件名。
  2. 放置到语言目录:把新文件放入启动器的 Languages 文件夹(发布版)或 source/Reloaded.Mod.Launcher/Assets/Languages(源码版)。若启动器正在运行,得益于 FileSystemWatcher,下拉框中会立即出现新语言。
  3. 逐条翻译:用任意文本编辑器打开文件,将每个 <sys:String> 标签内的英文文本替换为目标语言译文。保留 x:Key 不变,遵循上文提到的换行实体、占位符与 XML 转义规范。
  4. 切换到新语言验证:在启动器"Mod Loader Settings → Language"下拉框中选择新语言,逐页检查译文是否完整、是否有明显缺漏(缺漏项会显示为英文)。

实操:更新既有翻译与完整性判断

随着 Reloaded-II 持续迭代,每次更新都会在 en-GB.xaml 末尾追加新的文本条目(同时附带 <!-- Update x.y.z: ... --> 注释标注来源版本)。因此维护翻译的流程是:

  1. 对比缺失条目:将你维护的语言文件与最新版 en-GB.xaml 逐条比对,找出缺失的 Key;
  2. 追加到文件末尾:把缺失的条目连同其英文原文的译文追加到你的翻译文件末尾,不要打乱既有顺序;
  3. 完整性自检:判断一个翻译是否"完整",最直接的方法是检查该语言文件的最后一个文本条目是否与 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 文件为启动器贡献一种新语言,而无需修改任何代码。

登录后查看全文
Reloaded-II