MCLang [1.17x - 1.21x, 26.1][API]

MCLang

Github Status

SpigotMC Status

bStats Status

Lightweight API to load and use official Minecraft language pack translations.

*Tested Minecraft versions: 1.17, 1.18, 1.19, 1.20, 1.21*, 26.1
*Folia 1.19.4+ support (version 1.1.3 add)

Features

• Easy-to-use language pack management for Bukkit plugins
• Language packs for different Minecraft versions can be downloaded from [GitHub](https://github.com/0obriano0/MCLang/tree/main/Local%20Language%20Pack)
• Automatically downloads language packs from the official Minecraft resources if not present
• Hot-reload language files without server restart
• API for developers to integrate custom messages

Docs https://0obriano0.github.io/MCLang/

Web API & Frontend Portal (version 1.2.0 add)
MCLang includes a built-in modern Web API and an interactive frontend portal, making it easy to query translations programmatically or test them directly via your browser.

Enable and configure in plugins/MCLang/config.yml:

web:
  enabled: true  # Master switch
  ssl:
    enabled: false
    keystorePath: "keystore.jks"
    keystorePassword: "password"
  api:
    host: 127.0.0.1
    port: 8765
    cors: true
    maxEntriesPerRequest: 300
    requireKey: false       # Set to true to require a Bearer token
    key: "YOUR_SECRET_KEY"  # The token clients must provide
  frontend:
    enabled: true
    host: 127.0.0.1
    port: 8766
    cors: true
    staticDir: web          # Automatically extracted on startup

Accessing the Services

• Interactive Web Portal: http://127.0.0.1:8766/ (or https:// if SSL is enabled)
  • Features a modern, multi-language (i18n) test playground.
  • Dynamically extracts HTML/CSS/JS/JSON frontend files to plugins/MCLang/web/ on server start.
• Backend API Base URL: http://127.0.0.1:8765
  • (Access is denied with 401 Unauthorized if requireKey is enabled and no token is passed)

Available API Endpoints

• GET /api/languages: Returns a list of all currently loaded language codes and their versions.
• GET /api/languages/{lang}: Get keys/values for a specific language.
  • Supported query parameters: version, prefix, limit, offset.
• GET /api/translate: Query a single translation string.
  • Usage: ?lang=zh_tw&key=item.minecraft.diamond_sword
• POST /api/translate: Query a single translation string via POST.
  • Usage: send JSON payload {"lang":"zh_tw","key":"item.minecraft.diamond_sword"}

Note: You can easily test all these API endpoints directly via the interactive web portal without writing any code!

Gradle

repositories {
   mavenCentral()
   maven { url 'https://repo1.maven.org/maven2/' }
}
dependencies {
   compileOnly 'org.tsob:MCLang-API:1.1.3'
}

Maven

<repositories>
   <repository>
       <id>maven</id>
       <url>https://repo1.maven.org/maven2/</url>
   </repository>
</repositories>

<dependency>
  <groupId>org.tsob</groupId>
  <artifactId>MCLang-API</artifactId>
  <version>1.1.3</version>
  <scope>provided</scope>
</dependency>

Full Example: https://github.com/0obriano0/MCLang-example

Example

import org.tsob.MCLang.API.MCLang;
import org.bukkit.Material;
import org.bukkit.entity.EntityType;
import org.bukkit.inventory.ItemStack;

public class ExamplePlugin extends JavaPlugin {
  @Override
  public void onEnable() {
 
    MCLang lang = new MCLang("en");

    // Get translation for an ItemStack
    ItemStack item = new ItemStack(Material.DIAMOND_SWORD);
    String itemTranslation = lang.getItemTranslate(item);

    // Directly read the translation from the language pack.
    String translation = getString("item.minecraft.diamond_sword");

    // Get translation for an item name
    String itemTranslationByName = lang.getItemTranslate("DIAMOND_SWORD");

    // Get translation for an EntityType
    String entityTranslation = lang.getEntityTranslate (EntityType.CREEPER);

    // Get translation by entity instance (version 1.1.0 add)
    Entity entity = ...; // your Entity instance
    String entityTranslationFromEntity = lang.getEntityTranslate(entity);

    // Get translation for an entity name
    String entityTranslationByName = lang.getEntityTranslate("CREEPER");

    // Get translation for an enchantment (version 1.0.8 add)
    String enchantmentTranslationByName = lang.getEnchantmentTranslate(Enchantment.SILK_TOUCH);

    // Get translation for an enchantment name (version 1.0.8 add)
    String enchantmentTranslationByName = lang.getEnchantmentTranslate("SILK_TOUCH");
}

View updates and changelog here.

TODO

• Improve API documentation
• Add more usage examples