HsMod多语言支持方案：LocalizationManager实现15种语言切换

你是否曾因游戏插件界面语言与系统不符而困扰？HsMod作为基于BepInEx的炉石传说插件，通过LocalizationManager模块实现了15种语言的无缝切换，让全球玩家都能获得本地化体验。本文将详解其多语言架构设计与实现原理，帮助开发者快速掌握多语言插件开发技巧。

语言支持架构概览

HsMod的多语言系统核心由LocalizationManager.cs与Languages目录构成。管理器负责语言检测、文件加载与文本解析，语言包目录则存储15种预编译的JSON语言文件，覆盖从中文到泰语的主要游戏地区。

graph TD
    A[LocalizationManager.cs] -->|检测| B[系统语言]
    A -->|加载| C[Languages/*.json]
    A -->|缓存| D[当前语言JSON对象]
    A -->|回退| E[enUS.json默认语言]
    F[应用界面] -->|调用| A

核心模块文件结构：

• 语言管理核心：HsMod/LocalizationManager.cs
• 语言包目录：HsMod/Languages/
• 默认配置模板：HsMod/Languages/enUS.json

语言检测与加载机制

LocalizationManager通过三级机制确保语言正确加载：

1. 系统语言自动检测

public static string GetCurrentLang()
{
    System.Globalization.CultureInfo currentCulture = System.Globalization.CultureInfo.CurrentCulture;
    string languageCode = currentCulture.Name.Replace("-", "");
    // 日志输出：CurrentCulture: zhCN, Hearthstone zhCN, HsMod zhCN.
    return res;
}

该方法优先获取系统区域设置（如"zh-CN"转为"zhCN"），并与游戏内语言进行一致性校验，确保显示语言与玩家环境匹配。

2. 语言文件加载流程

public static string GetLangFileContext(string lang)
{
    string fileName = $"./Languages/{lang}.json";
    string context = FileManager.ReadEmbeddedFile(fileName);
    if (String.IsNullOrEmpty(context))
    {
        fileName = $"./Languages/enUS.json";  // 默认为英语
        Utils.MyLogger(LogLevel.Warning, $"使用默认语言文件: {fileName}");
    }
    return context;
}

当指定语言文件不存在时，系统会自动回退至enUS.json，保证插件基础功能可用。

3. 15种语言支持清单

HsMod支持的语言完整列表：

语言代码	语言名称	文件路径
zhCN	简体中文	HsMod/Languages/zhCN.json
enUS	美式英语	HsMod/Languages/enUS.json
jaJP	日语	HsMod/Languages/jaJP.json
koKR	韩语	HsMod/Languages/koKR.json
frFR	法语	HsMod/Languages/frFR.json
deDE	德语	HsMod/Languages/deDE.json
esES	西班牙语	HsMod/Languages/esES.json
ruRU	俄语	HsMod/Languages/ruRU.json
ptBR	巴西葡萄牙语	HsMod/Languages/ptBR.json
itIT	意大利语	HsMod/Languages/itIT.json
plPL	波兰语	HsMod/Languages/plPL.json
thTH	泰语	HsMod/Languages/thTH.json
zhTW	繁体中文	HsMod/Languages/zhTW.json
enGB	英式英语	HsMod/Languages/enGB.json
esMX	墨西哥西班牙语	HsMod/Languages/esMX.json

文本检索与缓存优化

为提升性能，LocalizationManager采用双层缓存机制：

内存缓存实现

public static string CacheCurrentLangJson = "";
public static Dictionary<string, string> CacheCurrentLangJsonObj = null;

public static string GetLangValue(string lang_key)
{
    if (CacheCurrentLangJsonObj == null)
    {
        CacheCurrentLangJson = GetLangFileContext(pluginInitLanague.Value);
        CacheCurrentLangJsonObj = JsonConvert.DeserializeObject<Dictionary<string, string>>(CacheCurrentLangJson);
    }
    // 尝试从当前语言缓存获取
    if (CacheCurrentLangJsonObj.TryGetValue(lang_key, out res)) return res;
    // 缓存未命中则尝试默认语言
    return GetEnUSLangValue(lang_key);
}

多语言键值对示例

以简体中文为例，JSON语言包采用"键:值"结构存储界面文本：

{
    "isPluginEnable.name": "HsMod状态",
    "isPluginEnable.label": "全局",
    "isPluginEnable.description": "是否启用插件（修改后建议重启炉石）",
    "pluginLanague.name": "HsMod语言",
    "pluginLanague.description": "插件首选语言（修改后需重启）"
}

开发时只需调用GetLangValue("pluginLanague.name")即可获取对应语言的"插件首选语言"文本。

本地化开发实践指南

添加新语言文件

1. 复制enUS.json为新语言文件（如arSA.json）
2. 翻译所有键值对内容
3. 在LocalizationManager.cs的STRING_TO_LOCALE字典中添加映射：

{
    "arSA",
    Locale.arSA
}

文本键命名规范

• 使用.分隔层级：功能.属性.类型（如keyTimeGearUp.description）
• 统一采用英语小写+下划线命名
• 保持键名与功能逻辑一致

常见问题解决

语言不生效排查步骤

1. 检查日志输出确认加载的语言文件：CurrentCulture: xx, Hearthstone xx, HsMod xx
2. 验证语言文件完整性：HsMod/Languages/zhCN.json
3. 清除缓存：删除BepInEx/config下的语言缓存文件

混合语言显示问题

若界面出现中英文混杂，通常是：

• 语言包缺失对应键值对（检查JSON文件完整性）
• 缓存未更新（重启游戏或调用SimulateDisconnect热重载）

总结与扩展方向

HsMod的多语言架构通过自动检测-智能回退-缓存优化的设计，实现了低开销、高可靠性的本地化方案。未来可扩展方向包括：

• 动态语言切换（无需重启游戏）
• 社区翻译贡献平台
• 地区特定内容适配（如卡牌名称本地化）

完整实现代码可参考：

• 核心逻辑：HsMod/LocalizationManager.cs
• 配置界面：HsMod/PluginConfig.cs
• 语言包模板：HsMod/Languages/

通过这套架构，HsMod不仅满足了全球玩家的本地化需求，更为同类插件提供了可复用的多语言解决方案。