Translations

On this page: How to add and use language files

tip

Before learning about LanguageManager, you should learn about AdventureAPI. You don't need to add AdventureAPI as dependency!

Adding translations support

With KTools you can create language files with translations. Firstly, you need to create new folder in resources called lang. In that folder, create new file with your langauge code i. e. en.yml. In that file, you can easly add translations.

resources/lang/en.yml

example: "Example translated message"
example2:
 - "First line of message"
 - "Second line of message"
exapleGroup:
    example3: "Example 3 message is in example group!"

note

Server's staff can crate own langauge file in plugins/PLUGIN_NAME/lang folder

tip

Langauge files support some APIs

MiniMessage

You can add color cordes and placeholders from MiniMessage

resources/lang/en.yml

example4: "<red>That message is red. Hello <something>!"

PlaceholderAPI

You can also add placeholders from PlaceholderAPI

resources/lang/en.yml

example5: "Your ping: %player_ping%"

Next, you need to add variable in config - with that, server staff can set own language.

resources/config.yml

lang: "en"

After that, you can comeback to your code, save config and prepare langauge file.

MyPlugin#onEnable()

saveDefaultConfig();
ToolsInitializer initializer = new ToolsInitializer(this)
        .prepareLanguage(getConfig().getString("lang"), "en");

note

If your default language is other than en, remember to replace it in config and in initializer

Using translations

To use translations, you need to get LanguageManager from ToolsObjectWrapper using ToolsObjectWrapper#getLanguageManager().

Example usages of LanguageManager

LanguageManager languageManager = wrapper.getLanguageManager();

/*
Sending Messages To Player via Components
*/
Player player = ...;
Audience audience = adventure.player(player);

// Sending single line
audience.sendMessage(languageManager.getSingleComponent(LanguageLevel.PLUGIN, "example"));
// Group of message doesn't matter
audience.sendMessage(languageManager.getSingleComponent(LanguageLevel.PLUGIN, "example3"));
// Adding placeholders (from MiniMessage)
audience.sendMessage(languageManager.getSingleComponent(LanguageLevel.PLUGIN, "example4", Placeholder.unparsed("something", "World")));
// Adding placeholders (from PlaceholderAPI)
audience.sendMessage(languageManager.getSingleComponent(LanguageLevel.PLUGIN, "example5", player));
// You can also combine placeholders (MiniMessage + PlaceholderAPI)
audience.sendMessage(languageManager.getSingleComponent(LanguageLevel.PLUGIN, "example4", player, Placeholder.unparsed("something", "World")));
// Sending multiple lines. You can also use it when you aren't sure if message contains one line or multiple lines
languageManager.getComponent(LanguageLevel.PLUGIN, "example2").forEach(audience::sendMessage);

/*
Creating Items
*/

ItemStack item = new ItemStack(Material.DIAMOND);
ItemMeta meta = item.getItemMeta();

// Getting single line
meta.setDisplayName(languageManager.getSingleString(LanguageLevel.PLUGIN, "example1"));
// Getting multiple lines
meta.setLore(languageManager.getString(LanguageLevel.PLUGIN, "example2"));

item.setItemMeta(meta);

Converting MiniMessage or Components to String

With LanguageManager you can also convert MiniMessage or Component to String (Using LegacyComponentSerializer)

LanguageManager languageManager = wrapper.getLanguageManager();

// MiniMessage to Legacy
String mmCode = "<red>Hello <something>!";
String legacyCode = languageManager.convertMmToString(mmCode, Placeholder.unparsed("something", "World")); // §cHello World!

// Component to Legacy
Component component = Component.text("Hello!").color(TextColor.color(255,0,0));
String legacyCode2 = languageManager.convertComponentToString(component); // §x§f§f§0§0§0§0Hello!

// Legacy to Component
String legacyText = "§cHello World!";
Component component2 =  languageManager.convertLegacyStringToComponent(legacyText);