umamusume-localify本地化工具配置指南：从异常排查到性能优化

一、诊断游戏异常：快速定位运行故障

本章解决本地化工具使用中常见的启动失败、显示异常等问题，建立系统的故障排查流程。

检测文件完整性

🔧 验证核心文件部署位置
确认编译生成的 version.dll 与游戏主程序 umamusume.exe 位于同一目录下，缺失此文件会导致游戏无法加载本地化功能。
验证方法：在游戏目录执行 ls | grep version.dll 查看文件是否存在

排查配置文件错误

🔧 检查JSON格式规范性
使用在线JSON验证工具（如JSONLint）校验配置文件语法，重点关注括号匹配和逗号使用。常见错误包括遗漏闭合括号或多余逗号。
验证方法：保存配置文件后启动游戏，若控制台显示 JSON parse error 则需修正格式

解决版本兼容性问题

🔧 确认工具版本匹配
游戏客户端更新后需同步更新本地化工具，访问项目仓库获取最新编译版本。版本不匹配会导致功能失效或游戏崩溃。
验证方法：查看工具目录下 changelog.txt 中的版本记录，与游戏启动界面版本号比对

二、设计优化方案：构建高效配置策略

通过科学配置参数组合，平衡游戏显示效果与系统性能，实现个性化的本地化体验。

配置项优先级矩阵

优先级	配置项	基础值	优化值	影响范围
P0（必配）	replaceFont	false	true	文字显示完整性
P0（必配）	unlockSize	false	true	分辨率适配
P1（推荐）	maxFps	30	60	画面流畅度
P1（推荐）	uiScale	1.0	1.2	界面可读性
P2（可选）	autoFullscreen	false	true	操作便捷性

性能调优核心策略

🔧 实施帧率动态控制
垂直同步（防止画面撕裂技术）默认启用，通过 maxFps 参数设置合理上限：低端设备建议30fps，中端设备60fps，高端设备设为0完全解锁。
验证方法：启用帧率显示软件（如Fraps），观察游戏内实际帧数是否稳定

🔧 启用资源智能加载
配置文件中添加 "lazyLoad": true 启用资源懒加载，减少游戏启动时间和内存占用。该参数对低配设备尤为重要。
验证方法：对比启用前后的游戏启动时间，建议使用秒表计时

三、实施部署流程：从环境准备到功能验证

系统化的部署步骤确保本地化工具正确安装，包含环境检查、编译构建和功能验证三个关键阶段。

环境检查前置步骤

🔧 确认开发环境完整性
安装Visual Studio 2019+（需包含C++开发组件）和Premake5构建工具，执行以下命令验证环境：

premake5 --version && cl.exe

验证方法：命令无报错且显示版本信息即表示环境就绪

获取与构建项目

🔧 克隆源码仓库

git clone https://gitcode.com/gh_mirrors/um/umamusume-localify

🔧 生成项目文件
在项目根目录执行：

premake5 vs2019

验证方法：检查是否生成 umamusume-localify.sln 解决方案文件

🔧 编译核心组件
使用Visual Studio打开解决方案，选择"Release"配置和"x64"平台，执行"生成解决方案"。编译成功后在 bin/Release 目录生成 version.dll。
验证方法：检查输出目录文件大小，正常应在500KB-2MB之间

部署与验证

🔧 配置文件部署
将编译产物 version.dll 复制到游戏根目录，创建 localify_config.json 配置文件。

🔧 基础功能验证
启动游戏后观察：①标题画面是否显示中文 ②设置界面是否出现新增选项 ③控制台是否输出初始化成功信息
验证方法：按F1打开内置控制台，查看是否显示 Localify initialized successfully

四、场景化配置方案：适配不同使用需求

针对不同硬件条件和使用场景，提供经过验证的配置组合方案，最大化本地化工具价值。

标准游戏配置（平衡方案）

{
  "enableConsole": false,
  "enableLogger": true,
  "maxFps": 60,
  "unlockSize": true,
  "uiScale": 1.2,
  "replaceFont": true,
  "autoFullscreen": true,
  "lazyLoad": true,
  "dicts": ["main_dict.json", "event_dict.json"]
}

适用场景：主流配置PC（i5+GTX1050以上），兼顾画质与性能

低配设备优化方案

{
  "enableConsole": false,
  "enableLogger": false,
  "maxFps": 30,
  "unlockSize": false,
  "uiScale": 1.0,
  "replaceFont": true,
  "autoFullscreen": false,
  "lazyLoad": true,
  "reduceEffects": true,
  "dicts": ["main_dict.json"]
}

关键优化点：关闭日志功能、限制帧率、禁用非必要视觉效果，适合笔记本集成显卡或老旧PC

内容创作配置（截图/录制专用）

{
  "enableConsole": false,
  "enableLogger": false,
  "maxFps": 0,
  "unlockSize": true,
  "uiScale": 1.5,
  "replaceFont": true,
  "antiAliasing": true,
  "dicts": ["main_dict.json", "full_dict.json"]
}

特殊设置：解锁帧率限制、提高界面缩放、启用抗锯齿，确保截图清晰度

五、持续优化与维护

定期检查项目更新，通过日志功能持续完善本地化效果。配置 "enableLogger": true 后，未翻译文本会记录到 localify_log.txt，建议每周查看并更新字典文件。当游戏版本更新时，优先验证 unlockSize 和 replaceFont 功能是否正常工作，这两个参数最易受游戏更新影响。