From 161fc0d0edfb89989c2bc48d6b8b49f629e14161 Mon Sep 17 00:00:00 2001 From: yhy <1763917516@qq.com> Date: Tue, 2 Jun 2026 16:39:36 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E4=BF=AE=E6=AD=A3=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E8=AF=B4=E6=98=8Emd=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 使用手册.md => README.md | 0 使用手册案例.md | 459 --------------------------------------- 2 files changed, 459 deletions(-) rename 使用手册.md => README.md (100%) delete mode 100644 使用手册案例.md diff --git a/使用手册.md b/README.md similarity index 100% rename from 使用手册.md rename to README.md diff --git a/使用手册案例.md b/使用手册案例.md deleted file mode 100644 index 56d2823..0000000 --- a/使用手册案例.md +++ /dev/null @@ -1,459 +0,0 @@ -<<<<<<< HEAD -# 1.LangUtil 是什么？ - -LangUtil 是一个 Minecraft 1.12.2 Bukkit / Spigot 多语言管理插件。 - -它的作用不是替代业务插件，而是给其他插件提供统一的语言 API： - -- 每个插件维护自己的语言文件 -- 玩家可以切换自己的语言 -- 不同玩家可以看到不同语言 -- 修改语言文件后可以不重启服务器直接重载 -- 支持物品名称、物品 lore、普通消息、占位符和颜色代码 - -简单理解： - -```yml -LangUtil = 公共语言管理器 -其他插件 = 自己提供 lang 文件 -玩家 = 自己选择 zh_CN / en_US 等语言 -``` - ------- - -# 2.目录结构 - -## LangUtil 自己的数据 - -玩家语言选择会保存到： - -```yml -plugins/LangUtil/player-language.yml -``` - -格式示例： - -```yml -player-language: - 550e8400-e29b-41d4-a716-446655440000: zh_CN -``` - -## 其他插件的语言文件 - -其他插件必须把语言文件放在自己的插件目录下： - -```yml -plugins/OtherPlugin/lang/zh_CN.yml -plugins/OtherPlugin/lang/en_US.yml -``` - -注意： - -```yml -语言文件不是放在 LangUtil 的 lang 目录 -语言文件是放在调用 register 的插件自己的 lang 目录 -``` - ------- - -# 3.其他插件如何注册？ - -其他插件需要依赖 LangUtil。 - -## plugin.yml - -```yml -depend: - - LangUtil -``` - -## 插件入口 - -```java -import com.io.yaohun.langutil.LangUtil; -import org.bukkit.plugin.java.JavaPlugin; - -public final class OtherPlugin extends JavaPlugin { - @Override - public void onEnable() { - LangUtil.register(this); - } -} -``` - -当执行： - -```java -LangUtil.register(this); -``` - -LangUtil 会读取： - -```yml -plugins/OtherPlugin/lang/*.yml -``` - ------- - -# 4.语言文件怎么写？ - -## zh_CN.yml - -```yml -message: - reload: "&a语言文件已重载" - no-permission: "&c你没有权限使用该命令。" - -item: - flame-sword: - name: "&c烈焰长剑" - lore: - - "&7伤害: &c{damage}" - - "&7品质: &6{quality}" - - "" - - "&e右键释放火焰" -``` - -## en_US.yml - -```yml -message: - reload: "&aLanguage files reloaded" - no-permission: "&cYou do not have permission." - -item: - flame-sword: - name: "&cFlame Sword" - lore: - - "&7Damage: &c{damage}" - - "&7Quality: &6{quality}" - - "" - - "&eRight-click to release fire" -``` - -文件名就是语言 ID： - -```yml -zh_CN.yml → zh_CN -en_US.yml → en_US -``` - ------- - -# 5.玩家命令 - -## 查看可用语言 - -```yml -/lang -``` - -玩家会看到当前已经加载的语言 ID。 - -## 切换语言 - -```yml -/lang zh_CN -/lang en_US -``` - -切换后会按玩家 UUID 保存。 - -玩家退出服务器再进入，仍然保持上次选择。 - -## 重载语言文件 - -```yml -/lang reload -``` - -修改语言文件后，不需要重启服务器，执行该命令即可重新读取所有已注册插件的语言文件。 - -控制台也可以执行： - -```yml -lang reload -``` - ------- - -# 6.权限节点 - -```yml -langutil.use # 允许玩家使用 /lang 查看和切换语言 -langutil.reload # 允许使用 /lang reload -``` - -推荐配置： - -```yml -普通玩家: langutil.use -管理员: langutil.use + langutil.reload -``` - ------- - -# 7.API 调用 - -## 获取普通消息 - -```java -String message = LangUtil.get(player, this, "message.reload"); -``` - -## 发送普通消息 - -```java -LangUtil.send(player, this, "message.reload"); -``` - -## 发送消息并播放音效 - -```java -LangUtil.send(player, this, "message.reload", Sound.LEVEL_UP); -``` - -## 使用占位符 - -```java -Map placeholders = new HashMap(); -placeholders.put("damage", "12"); -placeholders.put("quality", "史诗"); - -String name = LangUtil.get(player, this, "item.flame-sword.name", placeholders); -``` - -语言文件： - -```yml -item: - flame-sword: - name: "&c烈焰长剑" -``` - -结果： - -```yml -烈焰长剑 -``` - ------- - -# 8.物品 name 和 lore 怎么做？ - -物品 name 是字符串，可以用： - -```java -LangUtil.get(player, this, "item.flame-sword.name", placeholders); -``` - -物品 lore 是 List，可以用： - -```java -LangUtil.getList(player, this, "item.flame-sword.lore", placeholders); -``` - -完整示例： - -```java -Map placeholders = new HashMap(); -placeholders.put("damage", "12"); -placeholders.put("quality", "史诗"); - -ItemMeta meta = item.getItemMeta(); -meta.setDisplayName(LangUtil.get(player, this, "item.flame-sword.name", placeholders)); -meta.setLore(LangUtil.getList(player, this, "item.flame-sword.lore", placeholders)); -item.setItemMeta(meta); -``` - ------- - -# 9.推荐封装方式 - -为了让业务代码更短，其他插件可以自己封装一个 `Lang` 工具类。 - -```java -public final class Lang { - private static JavaPlugin plugin; - - private Lang() { - } - - public static void init(JavaPlugin javaPlugin) { - plugin = javaPlugin; - LangUtil.register(javaPlugin); - } - - public static void send(CommandSender sender, String path) { - LangUtil.send(sender, plugin, path); - } - - public static String get(CommandSender sender, String path) { - return LangUtil.get(sender, plugin, path); - } - - public static List getList(CommandSender sender, String path) { - return LangUtil.getList(sender, plugin, path); - } -} -``` - -插件启动时： - -```java -Lang.init(this); -``` - -业务代码： - -```java -Lang.send(player, "message.reload"); -``` - ------- - -# 10.重载机制说明 - -LangUtil 不会每次发送消息都读取本地 YAML。 - -语言文件读取时机： - -```yml -插件启动 register 时 -/lang reload 时 -再次调用 register 时 -``` - -平时调用： - -```java -LangUtil.get(...) -LangUtil.getList(...) -LangUtil.send(...) -``` - -都是从内存缓存读取。 - -这样可以避免每次发消息都读磁盘，降低主线程压力。 - ------- - -# 11.异常与回退规则 - -## 玩家没有选择语言 - -默认使用： - -```yml -zh_CN -``` - -## 玩家选择的语言文件不存在 - -回退： - -```yml -zh_CN -``` - -## zh_CN 也不存在 - -返回 path 原文： - -```java -LangUtil.get(player, this, "message.not-found"); -``` - -返回： - -```yml -message.not-found -``` - -## lore 不存在 - -返回单行 List： - -```yml -- item.xxx.lore -``` - -## YAML 格式错误 - -控制台会输出： - -```yml -插件名 -语言文件名 -错误原因 -``` - -不会因为单个语言文件错误导致服务器关闭。 - ------- - -# 12.实战使用流程 - -## 第一步：安装 LangUtil - -把插件放入服务器： - -```yml -plugins/LangUtil-1.2.0.jar -``` - -启动服务器。 - -## 第二步：业务插件依赖 LangUtil - -```yml -depend: - - LangUtil -``` - -## 第三步：业务插件注册语言文件 - -```java -LangUtil.register(this); -``` - -## 第四步：创建语言文件 - -```yml -plugins/OtherPlugin/lang/zh_CN.yml -plugins/OtherPlugin/lang/en_US.yml -``` - -## 第五步：玩家切换语言 - -```yml -/lang zh_CN -/lang en_US -``` - -## 第六步：业务插件发送消息 - -```java -LangUtil.send(player, this, "message.reload"); -``` - -## 第七步：修改语言后重载 - -```yml -/lang reload -``` - ------- - -# 13.注意事项 - -- 推荐始终使用带 `JavaPlugin plugin` 参数的 API。 -- 不推荐使用 `LangUtil.get(String path)`，因为它无法稳定判断读取哪个插件的语言。 -- 其他插件必须先调用 `LangUtil.register(this)`，否则读取不到自己的语言文件。 -- 语言文件必须放在调用注册方法的插件自己的 `lang` 目录。 -- 物品 lore 必须用 YAML List 格式编写。 -- 修改语言文件后必须执行 `/lang reload` 才会进入缓存。 -======= -# LangUtil - ->>>>>>> 12c7b3f43c6113b170b9e83dedf75650d51b9040