refactor: 重构多语言处理逻辑,统一配置与显示分离

1. 新增LangUtil工具类实现统一的多语言映射与参数替换
2. 移除各配置文件中的硬编码多语言包装类,替换为直接中文文本
3. 更新zh.json补充成就相关多语言词条
4. 重构HighlightSet适配新的多语言调用规范
This commit is contained in:
panw
2026-05-15 15:44:32 +08:00
parent a16fe4bff7
commit 4f8a955506
5 changed files with 368 additions and 226 deletions

View File

@@ -0,0 +1,95 @@
/**
* @file LangUtil.ts
* @description 多语言工具 - 在显示阶段进行多语言转换,配置阶段采用硬编码
*
* === 设计原则 ===
* 1. 配置文件heroSet / SkillSet / HighlightSet 等)中直接使用硬编码中文字符串
* 2. 当需要显示多语言时,通过本工具的函数在运行时将 uuid 映射到对应语言文本
* 3. 多语言 key 采用 "类型前缀_uuid" 的命名规范,自动生成,无需手动维护映射表
*
* === 多语言 key 命名规范 ===
* | 前缀 | 含义 | 示例 key | 对应 zh.json 中的值 |
* |-------------|-------------------|---------------------|----------------------|
* | hero_name | 英雄名称 | hero_name_5001 | 盾战士 |
* | hero_info | 英雄描述 | hero_info_5001 | 近战,魔法盾 坦克 |
* | mon_name | 怪物名称 | mon_name_6001 | 兽人战士 |
* | skill_name | 技能名称 | skill_name_6001 | 攻击 |
* | skill_info | 技能描述 | skill_info_6001 | 对单个目标攻击... |
* | fskill_name | 驻场技能名称 | fskill_name_7001 | 召唤精通 |
* | fskill_info | 驻场技能描述 | fskill_info_7001 | 召唤触发... |
* | scard_name | 特殊卡牌名称 | scard_name_7001 | 战术晋升 |
* | scard_info | 特殊卡牌描述 | scard_info_7001 | 升级场上随机... |
* | hl_name | 亮点成就名称 | hl_name_9001 | 暴击大师 |
* | hl_desc | 亮点成就描述 | hl_desc_9001 | 暴击{0}次 |
*
* === 使用示例 ===
* import { lang, langf } from "../common/LangUtil";
*
* // 英雄
* lang("hero_name", 5001) // → "盾战士"
* langf("skill_info", 6001, 1, 100) // → "对单个目标攻击1次每次造成100%攻击的伤害"
*
* // 驻场技能
* lang("fskill_name", 7001) // → "召唤精通"
* langf("fskill_info", 7001, 1) // → "场上所有友方召唤触发技能触发次数+1"
*
* // 亮点成就(与英雄/技能完全一致的调用方式)
* lang("hl_name", 9001) // → "暴击大师"
* langf("hl_desc", 9001, 20) // → "暴击20次"
*/
import { oops } from "db://oops-framework/core/Oops";
export type LangPrefix =
| "hero_name"
| "hero_info"
| "mon_name"
| "skill_name"
| "skill_info"
| "fskill_name"
| "fskill_info"
| "scard_name"
| "scard_info"
| "hl_name"
| "hl_desc";
function buildKey(prefix: LangPrefix, uuid: number | string): string {
return `${prefix}_${uuid}`;
}
/**
* 按前缀+uuid获取多语言文本
* @param prefix 类型前缀,如 "hero_name"、"skill_info"、"hl_name"
* @param uuid 唯一标识
* @returns 翻译后的文本,找不到则返回 key 本身
*
* @example
* lang("hero_name", 5001) // → "盾战士"
* lang("skill_name", 6002) // → "火球术"
* lang("hl_title", 9011) // → "初级暴击者"
*/
export function lang(prefix: LangPrefix, uuid: number | string): string {
const key = buildKey(prefix, uuid);
return oops.language.getLangByID(key) || key;
}
/**
* 按前缀+uuid获取多语言文本并替换 {0} {1} ... 占位符
* @param prefix 类型前缀
* @param uuid 唯一标识
* @param params 模板参数,按顺序替换 {0} {1} ...
* @returns 翻译并替换参数后的文本
*
* @example
* langf("skill_info", 6001, 1, 100) // → "对单个目标攻击1次每次造成100%攻击的伤害"
* langf("hl_desc", 9001, 20) // → "暴击20次"
*/
export function langf(prefix: LangPrefix, uuid: number | string, ...params: any[]): string {
const key = buildKey(prefix, uuid);
let str = oops.language.getLangByID(key) || key;
if (params && params.length > 0) {
for (let i = 0; i < params.length; i++) {
str = str.replace(`{${i}}`, String(params[i]));
}
}
return str;
}