Towny元数据与翻译系统完全指南CustomDataField扩展机制与Crowdin多语言实践【免费下载链接】TownyTowny Advanced Minecraft plugin for Bukkit/Spigot.项目地址: https://gitcode.com/gh_mirrors/to/TownyTowny是一款功能强大的 Minecraft 服务器主城插件运行于 Bukkit/Spigot 平台。本文带你快速搞懂 Towny 元数据系统与多语言翻译系统的运作原理如何通过 CustomDataField 扩展机制为城镇、国家、玩家、地块挂载自定义数据以及 Towny 借助 Crowdin 平台完成 40 余种语言翻译的完整实践。一、Towny 元数据系统给游戏对象贴标签1. 元数据是什么你可以把元数据理解为挂在 Towny 对象居民、城镇、国家、地块身上的自定义标签比如这个居民是 VIP、这个地块禁止交易。它让插件开发者和管理员无需修改 Towny 源码就能为对象附加任意键值对信息并且这些信息会自动随存档保存、随服务器重启恢复。元数据系统的核心代码位于Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/2. CustomDataField一切数据字段的抽象基类所有元数据都继承自抽象类 CustomDataField.java相对路径Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/CustomDataField.java它统一管理了每个字段的三要素要素说明key键字段的唯一标识如vip_levelvalue值具体数据类型由子类决定label标签人类可读的显示名有 label 的字段会出现在/town status等状态面板中Towny 内置了 8 种常用数据类型的实现全部位于同一 metadata 目录下IntegerDataField/LongDataField/ByteDataField—— 整数类DecimalDataField—— 小数StringDataField—— 文本BooleanDataField—— 开关LocationDataField—— 世界坐标ListDataField—— 列表可嵌套其他字段3. 扩展机制第三方插件如何注册自己的数据类型这是整个元数据系统最精妙的设计核心由两个类协作完成① MetadataLoader加载调度器见Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/MetadataLoader.java。它是一个单例内部维护一张typeID → 反序列化器的注册表。Towny 自身在初始化时注册好 8 种内置类型同时对外提供开放 APIregisterDeserializer(typeID, deserializer)—— 第三方插件只要把自己的数据类型 ID 和对应的反序列化器注册进来Towny 就能识别并解析这种自定义数据。② RawDataField未解析数据的占位符见Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/RawDataField.java。当存档中出现一种尚未注册解析器的数据类型时比如负责它的插件还没加载Towny 不会报错而是先把它保存为 RawDataField 占位。等第一个游戏 tick、所有插件就绪后MetadataLoader会再跑一轮延迟反序列化把占位数据转换成真正的类型对象并触发LoadedMetadataEvent事件通知各插件。 这种先占位、后转换的两段式设计彻底避免了插件加载顺序导致的元数据丢失问题。4. 数据如何保存——简洁的 JSON 序列化序列化逻辑在Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/DataFieldIO.java中。每个字段被编码为一个 JSON 数组[typeID, key, value, label]例如一条整型元数据可能被存为[IntegerDataField, vip_level, 3, VIP等级]。同时DataFieldIO还内置了旧版格式兼容层老存档中非 JSON 格式的遗留元数据会被自动识别并转换插件升级无需手动迁移。5. 管理员如何管理元数据Towny 在管理命令中提供了完整的元数据操作入口实现在Towny/src/main/java/com/palmergames/bukkit/towny/command/TownyAdminCommand.java中可对居民、城镇、国家、地块四类对象执行添加 / 获取 / 删除元数据操作。所有报错提示如该键的元数据未注册本身也走翻译系统输出见下文。二、Towny 翻译系统让 40 种语言开箱即用 打开Towny/src/main/resources/lang/目录你会看到44 个语言文件从en-US.yml、zh-CN.yml、zh-TW.yml到de-DE.yml、ja-JP.yml、ru-RU.yml……甚至还有恶搞向的lol-US.yml龙语。1. 翻译加载流程三级回退机制核心类是Towny/src/main/java/com/palmergames/bukkit/towny/object/Translation.java其loadTranslationRegistry()方法的加载顺序为内置翻译把打包在插件内的语言文件复制到settings/lang/的 reference 文件夹只读参考并载入内存翻译加载事件触发TranslationLoadEventTowny/src/main/java/com/palmergames/bukkit/towny/event/TranslationLoadEvent.java允许其他插件动态追加翻译条目覆盖文件与全局文件加载可选的 override 覆盖文件实现不改原版文件、按优先级覆盖个别词条生成语言目录的 readme 说明文件并刷新帮助菜单。运行时查找词条时采用三级回退默认语言 → 英语en-US→ 直接返回原始 key 并记录错误日志。这套设计保证了任何语言文件缺失词条时服务器永远不会因翻译问题而崩溃。2. 开发者如何调用——Translator 与 Translatable面向开发者的 API 极简TranslatorTowny/src/main/java/com/palmergames/bukkit/towny/object/Translator.java绑定一个语言环境提供of(key, args...)取纯文本、component(key, args...)取带格式的 Adventure 组件TranslatableTowny/src/main/java/com/palmergames/bukkit/towny/object/Translatable.java链式对象可指定发送者语言后输出组件元数据报错提示正是这样本地化输出的。语言文件中的文本支持颜色码与MiniMessage两套着色语法占位符可用%s也支持%1$s、%2$s这种可重排序编号占位符——这对语序不同的语言如日语、中文至关重要。3. Crowdin 多语言实践协作翻译流水线Towny 的 40 余种语言并非人工手动分发而是依托 Crowdin 翻译协作平台实现持续本地化。项目根目录下的 crowdin.yml相对路径crowdin.yml定义了同步规则files: - source: /Towny/src/main/resources/lang/en-US.yml translation: /Towny/src/main/resources/lang/%locale%.yml其工作流程为以en-US.yml为唯一源文件推送最新词条到 Crowdin全球社区译者按zh-CN、fr-FR、ko-KR等 locale 翻译翻译成果按translation模板回写为对应的yml文件随版本发布。这套源文件唯一 模板化回写的模式配合TranslationLoaderTowny/src/main/java/com/palmergames/bukkit/towny/object/TranslationLoader.java的 reference/override 分层加载使 Towny 在保持词条稳定的同时兼顾了本地化的可维护性与插件生态的扩展性。三、关键路径速查表模块相对路径元数据字段基类Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/CustomDataField.java元数据加载/注册器Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/MetadataLoader.javaJSON 序列化Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/DataFieldIO.java未解析数据占位符Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/RawDataField.java元数据管理命令Towny/src/main/java/com/palmergames/bukkit/towny/command/TownyAdminCommand.java翻译核心Towny/src/main/java/com/palmergames/bukkit/towny/object/Translation.java翻译 APITowny/src/main/java/com/palmergames/bukkit/towny/object/Translator.java翻译加载器Towny/src/main/java/com/palmergames/bukkit/towny/object/TranslationLoader.java语言文件目录Towny/src/main/resources/lang/Crowdin 同步配置crowdin.yml四、总结 Towny 的两套体系各有亮点元数据系统以CustomDataField为抽象基类、MetadataLoader注册表为扩展入口、RawDataField占位 延迟反序列化保证加载健壮性让第三方插件可以安全地挂载任意自定义数据翻译系统44 个语言文件 三级回退 Crowdin 社区协作流水线让 Towny 的多语言体验既稳定又可持续。无论你是想为服务器添加自定义数据的插件开发者还是希望贡献母语翻译的社区玩家Towny 都为你准备好了清晰的扩展点。【免费下载链接】TownyTowny Advanced Minecraft plugin for Bukkit/Spigot.项目地址: https://gitcode.com/gh_mirrors/to/Towny创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/8/22 13:00:04 · 阅读 1.2k Towny元数据与翻译系统完全指南：CustomDataField扩展机制与Crowdin多语言实践
Towny元数据与翻译系统完全指南CustomDataField扩展机制与Crowdin多语言实践【免费下载链接】TownyTowny Advanced Minecraft plugin for Bukkit/Spigot.项目地址: https://gitcode.com/gh_mirrors/to/TownyTowny是一款功能强大的 Minecraft 服务器主城插件运行于 Bukkit/Spigot 平台。本文带你快速搞懂 Towny 元数据系统与多语言翻译系统的运作原理如何通过 CustomDataField 扩展机制为城镇、国家、玩家、地块挂载自定义数据以及 Towny 借助 Crowdin 平台完成 40 余种语言翻译的完整实践。一、Towny 元数据系统给游戏对象贴标签1. 元数据是什么你可以把元数据理解为挂在 Towny 对象居民、城镇、国家、地块身上的自定义标签比如这个居民是 VIP、这个地块禁止交易。它让插件开发者和管理员无需修改 Towny 源码就能为对象附加任意键值对信息并且这些信息会自动随存档保存、随服务器重启恢复。元数据系统的核心代码位于Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/2. CustomDataField一切数据字段的抽象基类所有元数据都继承自抽象类 CustomDataField.java相对路径Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/CustomDataField.java它统一管理了每个字段的三要素要素说明key键字段的唯一标识如vip_levelvalue值具体数据类型由子类决定label标签人类可读的显示名有 label 的字段会出现在/town status等状态面板中Towny 内置了 8 种常用数据类型的实现全部位于同一 metadata 目录下IntegerDataField/LongDataField/ByteDataField—— 整数类DecimalDataField—— 小数StringDataField—— 文本BooleanDataField—— 开关LocationDataField—— 世界坐标ListDataField—— 列表可嵌套其他字段3. 扩展机制第三方插件如何注册自己的数据类型这是整个元数据系统最精妙的设计核心由两个类协作完成① MetadataLoader加载调度器见Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/MetadataLoader.java。它是一个单例内部维护一张typeID → 反序列化器的注册表。Towny 自身在初始化时注册好 8 种内置类型同时对外提供开放 APIregisterDeserializer(typeID, deserializer)—— 第三方插件只要把自己的数据类型 ID 和对应的反序列化器注册进来Towny 就能识别并解析这种自定义数据。② RawDataField未解析数据的占位符见Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/RawDataField.java。当存档中出现一种尚未注册解析器的数据类型时比如负责它的插件还没加载Towny 不会报错而是先把它保存为 RawDataField 占位。等第一个游戏 tick、所有插件就绪后MetadataLoader会再跑一轮延迟反序列化把占位数据转换成真正的类型对象并触发LoadedMetadataEvent事件通知各插件。 这种先占位、后转换的两段式设计彻底避免了插件加载顺序导致的元数据丢失问题。4. 数据如何保存——简洁的 JSON 序列化序列化逻辑在Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/DataFieldIO.java中。每个字段被编码为一个 JSON 数组[typeID, key, value, label]例如一条整型元数据可能被存为[IntegerDataField, vip_level, 3, VIP等级]。同时DataFieldIO还内置了旧版格式兼容层老存档中非 JSON 格式的遗留元数据会被自动识别并转换插件升级无需手动迁移。5. 管理员如何管理元数据Towny 在管理命令中提供了完整的元数据操作入口实现在Towny/src/main/java/com/palmergames/bukkit/towny/command/TownyAdminCommand.java中可对居民、城镇、国家、地块四类对象执行添加 / 获取 / 删除元数据操作。所有报错提示如该键的元数据未注册本身也走翻译系统输出见下文。二、Towny 翻译系统让 40 种语言开箱即用 打开Towny/src/main/resources/lang/目录你会看到44 个语言文件从en-US.yml、zh-CN.yml、zh-TW.yml到de-DE.yml、ja-JP.yml、ru-RU.yml……甚至还有恶搞向的lol-US.yml龙语。1. 翻译加载流程三级回退机制核心类是Towny/src/main/java/com/palmergames/bukkit/towny/object/Translation.java其loadTranslationRegistry()方法的加载顺序为内置翻译把打包在插件内的语言文件复制到settings/lang/的 reference 文件夹只读参考并载入内存翻译加载事件触发TranslationLoadEventTowny/src/main/java/com/palmergames/bukkit/towny/event/TranslationLoadEvent.java允许其他插件动态追加翻译条目覆盖文件与全局文件加载可选的 override 覆盖文件实现不改原版文件、按优先级覆盖个别词条生成语言目录的 readme 说明文件并刷新帮助菜单。运行时查找词条时采用三级回退默认语言 → 英语en-US→ 直接返回原始 key 并记录错误日志。这套设计保证了任何语言文件缺失词条时服务器永远不会因翻译问题而崩溃。2. 开发者如何调用——Translator 与 Translatable面向开发者的 API 极简TranslatorTowny/src/main/java/com/palmergames/bukkit/towny/object/Translator.java绑定一个语言环境提供of(key, args...)取纯文本、component(key, args...)取带格式的 Adventure 组件TranslatableTowny/src/main/java/com/palmergames/bukkit/towny/object/Translatable.java链式对象可指定发送者语言后输出组件元数据报错提示正是这样本地化输出的。语言文件中的文本支持颜色码与MiniMessage两套着色语法占位符可用%s也支持%1$s、%2$s这种可重排序编号占位符——这对语序不同的语言如日语、中文至关重要。3. Crowdin 多语言实践协作翻译流水线Towny 的 40 余种语言并非人工手动分发而是依托 Crowdin 翻译协作平台实现持续本地化。项目根目录下的 crowdin.yml相对路径crowdin.yml定义了同步规则files: - source: /Towny/src/main/resources/lang/en-US.yml translation: /Towny/src/main/resources/lang/%locale%.yml其工作流程为以en-US.yml为唯一源文件推送最新词条到 Crowdin全球社区译者按zh-CN、fr-FR、ko-KR等 locale 翻译翻译成果按translation模板回写为对应的yml文件随版本发布。这套源文件唯一 模板化回写的模式配合TranslationLoaderTowny/src/main/java/com/palmergames/bukkit/towny/object/TranslationLoader.java的 reference/override 分层加载使 Towny 在保持词条稳定的同时兼顾了本地化的可维护性与插件生态的扩展性。三、关键路径速查表模块相对路径元数据字段基类Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/CustomDataField.java元数据加载/注册器Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/MetadataLoader.javaJSON 序列化Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/DataFieldIO.java未解析数据占位符Towny/src/main/java/com/palmergames/bukkit/towny/object/metadata/RawDataField.java元数据管理命令Towny/src/main/java/com/palmergames/bukkit/towny/command/TownyAdminCommand.java翻译核心Towny/src/main/java/com/palmergames/bukkit/towny/object/Translation.java翻译 APITowny/src/main/java/com/palmergames/bukkit/towny/object/Translator.java翻译加载器Towny/src/main/java/com/palmergames/bukkit/towny/object/TranslationLoader.java语言文件目录Towny/src/main/resources/lang/Crowdin 同步配置crowdin.yml四、总结 Towny 的两套体系各有亮点元数据系统以CustomDataField为抽象基类、MetadataLoader注册表为扩展入口、RawDataField占位 延迟反序列化保证加载健壮性让第三方插件可以安全地挂载任意自定义数据翻译系统44 个语言文件 三级回退 Crowdin 社区协作流水线让 Towny 的多语言体验既稳定又可持续。无论你是想为服务器添加自定义数据的插件开发者还是希望贡献母语翻译的社区玩家Towny 都为你准备好了清晰的扩展点。【免费下载链接】TownyTowny Advanced Minecraft plugin for Bukkit/Spigot.项目地址: https://gitcode.com/gh_mirrors/to/Towny创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考