Language Utils - 多语言工具

Language Utils 是一个用于获取 Minecraft 原版物品、实体、附魔及其等级本地化名称的 API。它解决了插件开发者难以获取游戏内标准翻译的问题，支持多种语言和多个服务端版本。

💡状态与资源

• GitHub 仓库 (MIT 许可证): https://github.com/MascusJeoraly/LanguageUtils
• 示例插件: https://github.com/MascusJeoraly/LangUtilsExample
• Maven 仓库: https://raw.github.com/MascusJeoraly/LanguageUtils/mvn-repo/
• 最新构建: https://drone.io/github.com/MeowInnovation/LanguageUtils/files

版本说明

• 主要版本适用于 Spigot/Bukkit 1.12。
• 对于旧版本，请使用对应的链接：
• 1.7.10: [此链接](this)
• 1.8.9: [此链接](this)
• 1.9.4: [此链接](this)
• 1.10.x: [此链接](this)
• 1.11.x: [此链接](this)
• 1.7.10 版本现可在 Cauldron/KCauldron 服务端上使用，[点此下载](here)。
• 此 API 仅支持原版物品和实体（对于非原版物品，将返回其材质名称）。

🔧安装

对于服主

• 将插件文件放入服务器的 plugins/ 文件夹即可。
• 本插件自身没有功能，加载所有语言文件可能需要 100-250 毫秒。
• 如需自定义语言条目，请阅读 plugins/LangUtils/lang/ 内的 README.txt。

对于开发者

将 API 添加到你的构建路径中。

使用 Gradle

在 `build.gradle` 中添加

repositories {
    maven {
        url 'https://raw.github.com/MascusJeoraly/LanguageUtils/mvn-repo/'
    }
}
dependencies {
    compile group: 'com.meowj', name: 'LangUtils', version: '1.9' // 请检查最新版本
}

使用 Maven

在 `pom.xml` 中添加

<repositories>
    <repository>
        <id>lang-utils-repo</id>
        <url>https://raw.github.com/MascusJeoraly/LanguageUtils/mvn-repo/</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.meowj</groupId>
        <artifactId>LangUtils</artifactId>
        <!--请检查最新版本 -->
        <version>1.9</version>
    </dependency>
</dependencies>

🎮使用方法

物品 (Items)

• 获取物品的显示名称（包括自定义名称）：

    LanguageHelper.getItemDisplayName(itemStack, locale);
    LanguageHelper.getItemDisplayName(itemStack, player);

例如，获取物品的英文名：

    LanguageHelper.getItemDisplayName(itemStack, "en_us");

• 获取物品的本地化名称：

    LanguageHelper.getItemName(itemStack, locale);
    LanguageHelper.getItemName(itemStack, player);

• 获取物品的未本地化名称：

    LanguageHelper.getItemUnlocalizedName(itemStack);

实体 (Entities)

• 获取实体的未本地化名称：

    LanguageHelper.getEntityUnlocalizedName(entity);
    LanguageHelper.getEntityUnlocalizedName(entityType);

• 获取实体的本地化名称：

    LanguageHelper.getEntityName(entity, locale);
    LanguageHelper.getEntityName(entity, player);
    LanguageHelper.getEntityName(entityType, locale);
    LanguageHelper.getEntityName(entityType, player);

• 获取实体的显示名称（包括自定义名称）：

    LanguageHelper.getEntityDisplayName(entity, locale);
    LanguageHelper.getEntityDisplayName(entity, player);

*注：如果只需要英文名，可以直接使用 `entity.getName();`。*

附魔 (Enchantments)

• 获取附魔的未本地化名称：

    LanguageHelper.getEnchantmentUnlocalizedName(enchantment);

• 获取附魔的名称：

    LanguageHelper.getEnchantmentName(enchantment, player);
    LanguageHelper.getEnchantmentName(enchantment, locale);

• 获取附魔的完整名称（包含等级）：

    LanguageHelper.getEnchantmentDisplayName(enchantment, level, player);
    LanguageHelper.getEnchantmentDisplayName(enchantment, level, locale);
    LanguageHelper.getEnchantmentDisplayName(entry, level, player);
    LanguageHelper.getEnchantmentDisplayName(entry, level, locale);

*其中 `entry` 是 `Map.Entry<Enchantment, Integer>` 类型。*

附魔等级 (Enchantment Levels)

• 获取附魔等级的未本地化名称：

    LanguageHelper.getEnchantmentLevelUnlocalizedName(level);

• 获取附魔等级的名称：

    LanguageHelper.getEnchantmentLevelName(level, player);
    LanguageHelper.getEnchantmentLevelName(level, locale);

杂项 (Misc)

• 翻译一个未本地化名称：

    LanguageHelper.translateToLocal(unlocalizedName, locale);

• 获取玩家使用的语言：

    LocaleHelper.getPlayerLanguage(player);

• 添加/替换语言条目：

    LanguageRegistry.INSTANCE.registerEntry(lang, unlocalizedName, localizedName);

*更多细节请参考[示例插件](this demo plugin)。*

✨构建

本项目使用 Gradle 管理源代码。如需自行构建，请运行：

gradle build

或者（如果未安装 Gradle）

gradlew build

⭐配置

配置文件示例

# 当请求的语言中不存在某个名称时，将回退到此语言获取名称。默认回退语言是英语。
FallbackLanguage=en_us

# 如需启用某种语言的加载，请将其添加到以下列表中
LoadLanguage=[en_us, zh_cn, zh_tw]
# 或使用YAML列表格式
LoadLanguage:
  - en_us
  - zh_cn
  - zh_tw

# 如需加载所有语言，在列表中添加 "all"：
LoadLanguage:
  - all

❓已知问题

• 目前使用 HashMap 和 Enum 来组织语言和物品数据，获取一个物品名称可能需要 50-1000 微秒（有时可能更长）。
• 如果你有更高效的加载或查询方法，请告知作者。
• 暂不支持模组物品（在 1.8 和 1.9 版本中似乎没有必要）。